file

Working with files on the filesystem.

The functions included in this module are for high-level concepts such as reading and writing.

Types

Access

The read/write permissions a user can have for a file.

pub type Access {
  NoAccess
  Read
  ReadWrite
  Write
}

Constructors

```
NoAccess
```
```
Read
```
```
ReadWrite
```
```
Write
```

FileInfo

</>

Meta information for a file.

Timestamps are in seconds before or after the Unix time epoch, 1970-01-01 00:00:00 UTC.

pub type FileInfo {
  FileInfo(
    size: Int,
    file_type: FileType,
    access: Access,
    atime: Int,
    mtime: Int,
    ctime: Int,
    mode: Int,
    links: Int,
    major_device: Int,
    minor_device: Int,
    inode: Int,
    user_id: Int,
    group_id: Int,
  )
}

Constructors

```
FileInfo(
  size: Int,
  file_type: FileType,
  access: Access,
  atime: Int,
  mtime: Int,
  ctime: Int,
  mode: Int,
  links: Int,
  major_device: Int,
  minor_device: Int,
  inode: Int,
  user_id: Int,
  group_id: Int,
)
```
Arguments
- size
  
  File size in bytes.
- file_type
  
  Regular, Directory, Symlink, Device, or Other.
- access
  
  ReadWrite, Read, Write, or NoAccess.
- atime
  
  Timestamp of most recent access.
- mtime
  
  Timestamp of most recent modification.
- ctime
  
  Timestamp of most recent change (or file creation, depending on operating system).
- mode
  
  File permissions encoded as a sum of bit values, including but not limited to:
  
  Owner read, write, execute.
  
  0o400, 0o200, 0o100
  
  Group read, write, execute.
  
  0o40, 0o20, 0o10
  
  Other read, write, execute.
  
  0o4, 0o2, 0o1
  
  Set user ID, group ID on execution.
  
  0x800, 0x400
- links
  
  Total links to a file (always 1 for file systems without links).
- major_device
  
  The file system where a file is located (0 for drive A: on Windows, 1 for B:, etc.).
- minor_device
  
  Character device (or 0 on non-Unix systems).
- inode
  
  The inode number for a file (always 0 on non-Unix file systems).
- user_id
  
  The owner of a file (always 0 on non-Unix file systems).
- group_id
  
  The group id of a file (always 0 on non-Unix file systems).

FileType

</>

The type of file found by file_info or link_info.

pub type FileType {
  Device
  Directory
  Other
  Regular
  Symlink
}

Constructors

```
Device
```
```
Directory
```
```
Other
```
```
Regular
```
```
Symlink
```

Reason represents all of the reasons that Erlang surfaces of why a file system operation could fail. Most of these reasons are POSIX errors, which come from the operating system and start with E. Others have been added to represent other issues that may arise.

pub type Reason {
  Eacces
  Eagain
  Ebadf
  Ebadmsg
  Ebusy
  Edeadlk
  Edeadlock
  Edquot
  Eexist
  Efault
  Efbig
  Eftype
  Eintr
  Einval
  Eio
  Eisdir
  Eloop
  Emfile
  Emlink
  Emultihop
  Enametoolong
  Enfile
  Enobufs
  Enodev
  Enolck
  Enolink
  Enoent
  Enomem
  Enospc
  Enosr
  Enostr
  Enosys
  Enotblk
  Enotdir
  Enotsup
  Enxio
  Eopnotsupp
  Eoverflow
  Eperm
  Epipe
  Erange
  Erofs
  Espipe
  Esrch
  Estale
  Etxtbsy
  Exdev
  NotUtf8
}

Constructors

```
Eacces
```
Permission denied.
```
Eagain
```
Resource temporarily unavailable.
```
Ebadf
```
Bad file number
```
Ebadmsg
```
Bad message.
```
Ebusy
```
File busy.
```
Edeadlk
```
Resource deadlock avoided.
```
Edeadlock
```
On most architectures, same as Edeadlk. On some architectures, it means “File locking deadlock error.”
```
Edquot
```
Disk quota exceeded.
```
Eexist
```
File already exists.
```
Efault
```
Bad address in system call argument.
```
Efbig
```
File too large.
```
Eftype
```
Inappropriate file type or format. Usually caused by trying to set the “sticky bit” on a regular file (not a directory).
```
Eintr
```
Interrupted system call.
```
Einval
```
Invalid argument.
```
Eio
```
I/O error.
```
Eisdir
```
Illegal operation on a directory.
```
Eloop
```
Too many levels of symbolic links.
```
Emfile
```
Too many open files.
```
Emlink
```
Too many links.
```
Emultihop
```
Multihop attempted.
```
Enametoolong
```
Filename too long
```
Enfile
```
File table overflow
```
Enobufs
```
No buffer space available.
```
Enodev
```
No such device.
```
Enolck
```
No locks available.
```
Enolink
```
Link has been severed.
```
Enoent
```
No such file or directory.
```
Enomem
```
Not enough memory.
```
Enospc
```
No space left on device.
```
Enosr
```
No STREAM resources.
```
Enostr
```
Not a STREAM.
```
Enosys
```
Function not implemented.
```
Enotblk
```
Block device required.
```
Enotdir
```
Not a directory.
```
Enotsup
```
Operation not supported.
```
Enxio
```
No such device or address.
```
Eopnotsupp
```
Operation not supported on socket.
```
Eoverflow
```
Value too large to be stored in data type.
```
Eperm
```
Not owner.
```
Epipe
```
Broken pipe.
```
Erange
```
Result too large.
```
Erofs
```
Read-only file system.
```
Espipe
```
Invalid seek.
```
Esrch
```
No such process.
```
Estale
```
Stale remote file handle.
```
Etxtbsy
```
Text file busy.
```
Exdev
```
Cross-domain link.
```
NotUtf8
```
File was requested to be read as UTF-8, but is not UTF-8 encoded.

Functions

append

</>

pub fn append(contents contents: String, to path: String) -> Result(
  Nil,
  Reason,
)

Append the given String contents to a file of the given name.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> append("Hello, World!", "file.txt")
Ok(Nil)

> append(to: "file.txt", contents: "Hello, World!")
Ok(Nil)

> append("Hello, World!", "does_not_exist/file.txt")
Error(Enoent)

append_bits

</>

pub fn append_bits(contents contents: BitString, to path: String) -> Result(
  Nil,
  Reason,
)

Append the given BitString contents to a file of the given name.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> append_bits(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>, "cat.gif")
Ok(Nil)

> append_bits(to: "cat.gif", contents: <<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>)
Ok(Nil)

> append_bits(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>, "does_not_exist/cat.gif")
Error(Enoent)

delete

</>

pub external fn delete(String) -> Result(Nil, Reason)

Delete the given file.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> delete("file.txt")
Ok(Nil)

> delete("does_not_exist.txt")
Error(Enoent)

delete_directory

</>

pub external fn delete_directory(String) -> Result(Nil, Reason)

Deletes a directory.

The directory must be empty before it can be deleted. Returns a nil Success or Reason if the operation failed.

Examples

> delete_directory("foo")
Ok(Nil)

> delete_directory("does_not_exist/")
Error(Enoent)

file_exists

</>

pub fn file_exists(path: String) -> Result(Bool, Reason)

Results in a Bool on success that indicates whether the given path exists, otherwise a Reason for failure.

When path refers to a symlink, the result pertains to the link’s target. To find whether a symlink itself exists, use link_exists.

Examples

> file_exists("resume.pdf")
Ok(True)

> file_exists("/tmp")
Ok(True)

> file_exists("/does_not_exist")
Ok(False)

> file_exists("/root/.local/maybe_exists")
Error(Eacces)

file_info

</>

pub external fn file_info(String) -> Result(FileInfo, Reason)

Results in FileInfo about the given path on success, otherwise a Reason for failure.

When path refers to a symlink, the result pertains to the link’s target. To get FileInfo about a symlink itself, use link_info.

Examples

> file_info("gleam.toml")
Ok(FileInfo(
  size: 430,
  file_type: Regular,
  access: ReadWrite,
  atime: 1680580321,
  mtime: 1680580272,
  ctime: 1680580272,
  mode: 33188,
  links: 1,
  major_device: 64,
  minor_device: 0,
  inode: 469028,
  user_id: 1000,
  group_id: 1000,
))

> file_info("/root")
Ok(FileInfo(
  size: 16,
  file_type: Directory,
  access: Read,
  atime: 1677789967,
  mtime: 1664561240,
  ctime: 1664561240,
  mode: 16877,
  links: 11,
  major_device: 54,
  minor_device: 0,
  inode: 34,
  user_id: 0,
  group_id: 0,
))

> file_info("./build/dev/erlang/rad/priv")
Ok(FileInfo(
  size: 140,
  file_type: Directory,
  access: ReadWrite,
  atime: 1680580321,
  mtime: 1680580272,
  ctime: 1680580272,
  mode: 33188,
  links: 1,
  major_device: 64,
  minor_device: 0,
  inode: 469028,
  user_id: 1000,
  group_id: 1000,
))

> file_info("/does_not_exist")
Error(Enoent)

> file_info("/root/.local/maybe_exists")
Error(Eacces)

is_directory

</>

pub fn is_directory(path: String) -> Result(Bool, Reason)

Results in a Bool on success that indicates whether the given path has a Directory FileType, otherwise a Reason for failure.

When path refers to a symlink, the result pertains to the link’s target.

Examples

> is_directory("/tmp")
Ok(True)

> is_directory("resume.pdf")
Ok(False)

> is_directory("/does_not_exist")
Error(Enoent)

is_regular

</>

pub fn is_regular(path: String) -> Result(Bool, Reason)

Results in a Bool on success that indicates whether the given path has a Regular FileType, otherwise a Reason for failure.

When path refers to a symlink, the result pertains to the link’s target.

Examples

> is_regular("resume.pdf")
Ok(True)

> is_regular("/tmp")
Ok(False)

> is_regular("/does_not_exist.txt")
Error(Enoent)

link_exists

</>

pub fn link_exists(path: String) -> Result(Bool, Reason)

Results in a Bool on success that indicates whether the given path exists, otherwise a Reason for failure.

When path refers to a symlink, the result pertains to the link itself. To find whether a symlink’s target exists, use file_exists.

Examples

> link_exists("resume.pdf")
Ok(True)

> link_exists("/tmp")
Ok(True)

> link_exists("/does_not_exist")
Ok(False)

> link_exists("/root/.local/maybe_exists")
Error(Eacces)

link_info

</>

pub external fn link_info(String) -> Result(FileInfo, Reason)

Results in FileInfo about the given path on success, otherwise a Reason for failure.

When path refers to a symlink, the result pertains to the link itself. To get FileInfo about a symlink’s target, use file_info.

Examples

> link_info("gleam.toml")
Ok(FileInfo(
  size: 430,
  file_type: Regular,
  access: ReadWrite,
  atime: 1680580321,
  mtime: 1680580272,
  ctime: 1680580272,
  mode: 33188,
  links: 1,
  major_device: 64,
  minor_device: 0,
  inode: 469028,
  user_id: 1000,
  group_id: 1000,
))

> link_info("/root")
Ok(FileInfo(
  size: 16,
  file_type: Directory,
  access: Read,
  atime: 1677789967,
  mtime: 1664561240,
  ctime: 1664561240,
  mode: 16877,
  links: 11,
  major_device: 54,
  minor_device: 0,
  inode: 34,
  user_id: 0,
  group_id: 0,
))

> link_info("./build/dev/erlang/rad/priv")
Ok(FileInfo(
  size: 41,
  file_type: Symlink,
  access: ReadWrite,
  atime: 1680581150,
  mtime: 1680581150,
  ctime: 1680581150,
  mode: 41471,
  links: 1,
  major_device: 64,
  minor_device: 0,
  inode: 471587,
  user_id: 1000,
  group_id: 1000,
))

> link_info("/does_not_exist")
Error(Enoent)

> link_info("/root/.local/maybe_exists")
Error(Eacces)

list_directory

</>

pub external fn list_directory(
  String,
) -> Result(List(String), Reason)

Lists all files in a directory, except files with raw filenames.

Returns a Result containing the list of filenames in the directory, or Reason if the operation failed.

Examples

> list_directory("/tmp")
Ok(["FB01293B-8597-4359-80D5-130140A0C0DE","AlTest2.out"])

> list_directory("resume.docx")
Error(Enotdir)

make_directory

</>

pub external fn make_directory(String) -> Result(Nil, Reason)

Tries to create a directory. Missing parent directories are not created.

Returns a Result of nil if the directory is created or Reason if the operation failed.

Examples

> make_directory("/tmp/foo")
Ok(Nil)

> make_directory("relative_directory")
Ok(Nil)

> make_directory("/tmp/missing_intermediate_directory/foo")
Error(Enoent)

read

</>

pub fn read(from path: String) -> Result(String, Reason)

Read the contents of the given file as a String

Assumes the file is UTF-8 encoded. Returns a Result containing the file’s contents as a String if the operation was successful, or Reason if the file operation failed. If the file is not UTF-8 encoded, the NotUTF8 variant will be returned.

Examples

> read("example.txt")
Ok("Hello, World!")

> read(from: "example.txt")
Ok("Hello, World!")

> read("does_not_exist.txt")
Error(Enoent)

> read("cat.gif")
Error(NotUTF8)

read_bits

</>

pub fn read_bits(from path: String) -> Result(BitString, Reason)

Read the contents of the given file as a BitString

Returns a Result containing the file’s contents as a BitString if the operation was successful, or Reason if the operation failed.

Examples

> read_bits("example.txt")
Ok(<<"Hello, World!">>)

> read_bits(from: "cat.gif")
Ok(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>)

> read_bits("does_not_exist.txt")
Error(Enoent)

recursive_delete

</>

pub external fn recursive_delete(String) -> Result(Nil, Reason)

Deletes a file or directory recursively.

Returns a nil Success or Reason if the operation failed.

Examples

> recursive_delete("foo")
Ok(Nil)

> recursive_delete("/bar")
Ok(Nil)

> recursive_delete("does_not_exist/")
Error(Enoent)

write

</>

pub fn write(contents contents: String, to path: String) -> Result(
  Nil,
  Reason,
)

Write the given String contents to a file of the given name.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> write("Hello, World!", "file.txt")
Ok(Nil)

> write(to: "file.txt", contents: "Hello, World!")
Ok(Nil)

> write("Hello, World!", "does_not_exist/file.txt")
Error(Enoent)

write_bits

</>

pub fn write_bits(contents contents: BitString, to path: String) -> Result(
  Nil,
  Reason,
)

Write the given BitString contents to a file of the given name.

Returns a Result with Nil if the operation was successful or a Reason otherwise.

Examples

> write_bits(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>, "cat.gif")
Ok(Nil)

> write_bits(to: "cat.gif", contents: <<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>)
Ok(Nil)

> write_bits(<<71,73,70,56,57,97,1,0,1,0,0,0,0,59>>, "does_not_exist/cat.gif")
Error(Enoent)

Constructors

Constructors

Arguments

Constructors

Constructors

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples