Module fs/file

Open a file at path with the given mode and custom permissions.

Open a file from a str path with the given mode and custom permissions.

Open a file from a C string path with the given mode and custom permissions.

Open a file at path with the given mode and default permissions (0o644).

Open a file from a str path with the given mode and default permissions.

Open a file at path with an OpenOptions flag set and custom permissions.

perm is consulted only when opts.creates() — POSIX ignores the mode argument otherwise, so passing one for a non-creating open is silently meaningless and this mirrors that.

Throws when opts names a contradictory combination (see OpenOptions.to_flags): the thrown error is a Context carrying the explanation over an IoError.InvalidInput, so to_string() says which combination was rejected while source() still reports the kind Rust would report.

Open a file at path with an OpenOptions flag set and default permissions (0o644).

Open a file from a C string path with the given mode and default permissions.

Read an entire file into a byte list (ArrayList(u8)).

Write bytes to a file, creating or truncating it.

Write a String to a file, creating or truncating it.

Write bytes from an ArrayList(u8) to the file. Returns the number of bytes written.

A no-op — Rust's Write::flush for File. An fd write has no user-space buffer behind it, so there is nothing to push. The inherent File.flush is an fsync instead; see its doc.

Truncate or extend the file to exactly length bytes (Rust's File::set_len). Extending pads with zeroes. Takes effect regardless of this handle's read/write position.

Wrap an ALREADY-OPEN file descriptor without opening anything (Rust's File::from for raw fds). The handle starts at position 0 — use seek() if the descriptor's data should be read from elsewhere. The path is unknown, so path() reports an empty path.

Seek to a position relative to from. Returns the new absolute byte offset.

Get the current file position (byte offset from the beginning).

Reports _pos, not the descriptor's position. This used to ask the descriptor via lseek(SEEK_CUR), which ALWAYS answered 0: positional reads and writes never move it.

Move back to the beginning of the file (Rust's Seek::rewind).

Inherent rather than a Seek default because a trait generic over the reference-point type cannot name its own "start" — see io.Seek.

Get the file size in bytes.

Close the file descriptor. Safe to call multiple times.

Get the underlying file descriptor.

Get the path this file was opened with.

Get file metadata (size, permissions, timestamps).

fstats THIS handle's descriptor. It used to re-stat _path, which answered about a different inode the moment the two diverged: a from_fd handle has no path at all and an empty Path renders as ., so it reported the CURRENT DIRECTORY's size, mode and times with no error — issues/fixed/fs-metadata-restats-by-path-and-walker-drops-dt-unknown.md. A file renamed, replaced or unlinked after the open had the same problem. The descriptor names the inode; the path does not.

Release the resources self owns — a file descriptor, a socket, a lock, a buffer the allocator handed out. Called automatically when the last reference to the value goes away, so an implementor never calls it directly and must tolerate being the only one who ever does.

It must be safe to run exactly once: the runtime calls it at refcount zero, and a type that also exposes an explicit close/release is responsible for making the second call a no-op.

Read an entire file into a String.

All flags off. At least one of read/write/append must be set before to_flags() will accept it.

Read an entire file into a byte list (ArrayList(u8)).

Write bytes to a file, creating or truncating it.

Every write goes to the END of the file regardless of the seek position (O_APPEND). Grants write access on its own.

Truncate the file to zero length on open. Needs write access.

Create the file if it does not exist. Needs write or append access.

Create the file, failing if it ALREADY exists. Implies create, and the check-and-create is atomic (O_EXCL), which is what makes it usable as a lock.

True when this combination can create the file, so the caller knows whether the permission argument is consulted.

The POSIX flag set, or .Err naming the contradiction.

The rejected combinations are the ones POSIX does NOT diagnose — it quietly ignores whichever flag does not apply, handing back a file that behaves differently from what was asked:

• nothing to do: no read, write or append.
• truncate without write access: O_TRUNC with O_RDONLY is undefined by POSIX and a no-op on Linux.
• truncate with append: contradictory — append means every write goes to the end, truncate means the end is zero.
• create without write access: there is nothing to create the file for.

0o644 — rw-r--r--. The usual mode for a data file: writable by its owner, readable by everyone. This is what File.open passes when the mode creates a file and the caller named no permission; the process umask still clears bits from it, so a umask of 0o022 is what makes this the effective default rather than the request.

0o755 — rwxr-xr-x. default plus the execute bit for everyone: scripts and binaries. Note the execute bit is only meaningful on POSIX; Windows decides executability from the file extension.

0o444 — r--r--r--. Readable by everyone, writable by nobody, which is the state Metadata.is_readonly reports true for. It does not stop root, and it does not stop the file's owner from chmod-ing it back.

0o600 — rw-------. Owner only: the mode to use for anything holding a credential, and the mode mkstemp (so TempFile) already creates with. Unlike the other three this is not weakened by a typical umask, because no group or other bit is being asked for.