Files v0.1.0

Opening, reading, writing and inspecting files through descriptors.

`StdIn`

pub const StdIn: int32 = 0;

The descriptor a process reads its input from, unless something reassigned it.

Source

`StdOut`

pub const StdOut: int32 = 1;

The descriptor a process writes its output to.

Source

`StdErr`

pub const StdErr: int32 = 2;

The descriptor a process writes its diagnostics to.

Source

`Read`

pub func Read(
    fd: FileDescriptor,
    buffer: *var opaque,
    count: uint
) -> int64

Reads up to count bytes from fd into buffer. buffer is borrowed and written. Returns the number of bytes read, zero at end of file, or a negative error number. A short count is ordinary. buffer must be writable for count bytes.

Source

Parameters

Name	Type	Description
`fd`	`FileDescriptor`	an open descriptor
`buffer`	`*var opaque`	receives the bytes
`count`	`uint`	how many bytes to ask for

Returns: the bytes read, zero at end of file, or a negative error number

`Write`

pub func Write(
    fd: FileDescriptor,
    buffer: *opaque,
    count: uint
) -> int64

Writes up to count bytes from buffer to fd. buffer is borrowed and read. Returns the number of bytes written, or a negative error number. A short count is ordinary and the rest has to be written by calling again. buffer must be readable for count bytes.

Source

Parameters

Name	Type	Description
`fd`	`FileDescriptor`	an open descriptor
`buffer`	`*opaque`	the bytes to write
`count`	`uint`	how many bytes to offer

Returns: the bytes written, or a negative error number

`Close`

pub func Close(fd: FileDescriptor) -> int64

Closes fd and releases what the kernel held for it. Returns zero, or a negative error number. A failure does not mean the descriptor is still open, so retrying a failed close can close one another thread has since opened under the same number.

Source

Parameters

Name	Type	Description
`fd`	`FileDescriptor`	an open descriptor

Returns: zero, or a negative error number

`AtFdCwd`

pub const AtFdCwd: int32 = -100;

AT_FDCWD: resolve a relative path against the current directory rather than a descriptor. FreeBSD spells this -100, the same value Linux uses, which is one of the few places the two agree exactly.

Source

`OpenReadOnly`

pub const OpenReadOnly: int32 = 0x0000;

O_RDONLY: open for reading only.

Source

`OpenWriteOnly`

pub const OpenWriteOnly: int32 = 0x0001;

O_WRONLY: open for writing only.

Source

`OpenReadWrite`

pub const OpenReadWrite: int32 = 0x0002;

O_RDWR: open for both reading and writing.

Source

`OpenCreate`

pub const OpenCreate: int32 = 0x0200;

O_CREAT: create the file when it does not exist, which is when the mode argument is read. FreeBSD's flag bits are the BSD ones and are not Linux's: O_CREAT is 0x0200 here and 0x40 there. A flag value must never be carried between the two packages.

Source

`OpenExclusive`

pub const OpenExclusive: int32 = 0x0800;

O_EXCL: with OpenCreate, fail rather than open a file that already exists.

Source

`OpenTruncate`

pub const OpenTruncate: int32 = 0x0400;

O_TRUNC: truncate the file to nothing when opening it for writing.

Source

`OpenAppend`

pub const OpenAppend: int32 = 0x0008;

O_APPEND: every write goes to the end.

Source

`OpenNonBlocking`

pub const OpenNonBlocking: int32 = 0x0004;

O_NONBLOCK: reads and writes report EAGAIN rather than waiting.

Source

`OpenCloseOnExec`

pub const OpenCloseOnExec: int32 = 0x00100000;

O_CLOEXEC: close this descriptor automatically when the process executes a new program.

Source

`OpenDirectory`

pub const OpenDirectory: int32 = 0x00020000;

O_DIRECTORY: fail unless the target is a directory.

Source

`SeekSet`

pub const SeekSet: int32 = 0;

SEEK_SET: measure the new offset from the start of the file.

Source

`SeekCurrent`

pub const SeekCurrent: int32 = 1;

SEEK_CUR: measure the new offset from the current one.

Source

`SeekEnd`

pub const SeekEnd: int32 = 2;

SEEK_END: measure the new offset from the end of the file.

Source

`OpenAt`

pub func OpenAt(
    directoryFd: FileDescriptor,
    path: *char8,
    flags: int32,
    mode: FileMode
) -> int64

Opens path relative to directoryFd and returns a descriptor, or a negative error number. directoryFd is AtFdCwd for an ordinary path. mode is read only when OpenCreate is set. path must be non-null and terminated. The mode is masked by the process umask.

Source

Parameters

Name	Type	Description
`directoryFd`	`FileDescriptor`	the directory `path` is relative to, or `AtFdCwd` for an ordinary path
`path`	`*char8`	the path to open, as a null-terminated byte string
`flags`	`int32`	the access mode and the open flags, combined with `\|`
`mode`	`FileMode`	the permission bits for a file this creates, ignored otherwise

Returns: the new descriptor, or a negative error number

`Lseek`

pub func Lseek(
    fd: FileDescriptor,
    offset: FileOffset,
    whence: int32
) -> int64

Moves the file offset of fd and returns where it ended up, or a negative error number. Seeking past the end creates a hole when something is later written there. A pipe reports ESPIPE.

Source

Parameters

Name	Type	Description
`fd`	`FileDescriptor`	an open descriptor
`offset`	`FileOffset`	how far to move, interpreted according to `whence`
`whence`	`int32`	`SeekSet`, `SeekCurrent` or `SeekEnd`

Returns: the resulting offset from the start, or a negative error number

`FstatAt`

pub func FstatAt(
    directoryFd: FileDescriptor,
    path: *char8,
    statBuffer: *var opaque,
    flags: int32
) -> int64

Fills statBuffer with what the kernel knows about the file path names. directoryFd is AtFdCwd for an ordinary path. flags is zero to follow a symbolic link at the end of the path, or SymlinkNoFollow to describe the link itself. Returns zero, or a negative error number. statBuffer must be writable for the whole of struct stat, which is 224 bytes and whose layout this package does not model.

Source

Parameters

Name	Type	Description
`directoryFd`	`FileDescriptor`	the directory `path` is relative to, or `AtFdCwd` for an ordinary path
`path`	`*char8`	the path to describe
`statBuffer`	`*var opaque`	receives the architecture's `struct stat`
`flags`	`int32`	zero to follow a final symbolic link, or `SymlinkNoFollow`

Returns: zero, or a negative error number

`FchmodAt`

pub func FchmodAt(
    directoryFd: FileDescriptor,
    path: *char8,
    mode: FileMode,
    flags: int32
) -> int64

Sets the permission bits of the file path names. directoryFd is AtFdCwd for an ordinary path. flags may carry SymlinkNoFollow. Returns zero, or a negative error number.

Source

Parameters

Name	Type	Description
`directoryFd`	`FileDescriptor`	the directory `path` is relative to, or `AtFdCwd` for an ordinary path
`path`	`*char8`	the path whose bits are set
`mode`	`FileMode`	the permission bits to set
`flags`	`int32`	zero, or `SymlinkNoFollow` where the system supports it

Returns: zero, or a negative error number

`UtimensAt`

pub func UtimensAt(
    directoryFd: FileDescriptor,
    path: *char8,
    times: *opaque,
    flags: int32
) -> int64

Sets the access and modification times of the file path names. times is borrowed and holds two timespec values — access first, then modification — each a whole-second count and a nanosecond fraction, both 8 bytes. A null times sets both to now. flags may carry SymlinkNoFollow. Returns zero, or a negative error number.

Source

Parameters

Name	Type	Description
`directoryFd`	`FileDescriptor`	the directory `path` is relative to, or `AtFdCwd` for an ordinary path
`path`	`*char8`	the path whose times are set
`times`	`*opaque`	two `timespec` values, or null for now
`flags`	`int32`	zero to follow a final symbolic link, or `SymlinkNoFollow`

Returns: zero, or a negative error number

`Fsync`

pub func Fsync(fd: FileDescriptor) -> int64

Flushes everything written to fd through to the storage device. Returns zero, or a negative error number. Without it, data a successful Write reported may still be lost.

Source

Parameters

Name	Type	Description
`fd`	`FileDescriptor`	an open descriptor

Returns: zero, or a negative error number

`Ftruncate`

pub func Ftruncate(
    fd: FileDescriptor,
    length: FileOffset
) -> int64

Sets the length of the file behind fd to length. Growing creates a hole rather than allocating, so a later write into it can still fail with ENOSPC.

Source

Parameters

Name	Type	Description
`fd`	`FileDescriptor`	an open descriptor
`length`	`FileOffset`	the size the file should have afterwards

Returns: zero, or a negative error number

`Fstat`

pub func Fstat(
    fd: FileDescriptor,
    statBuffer: *var opaque
) -> int64

Fills statBuffer with what the kernel knows about the file behind fd. The kernel's struct stat is not modelled here: its layout is FreeBSD's own and differs from Linux's in both size and field order. statBuffer must be writable for the whole of FreeBSD's struct stat, which this does not check.

Source

Parameters

Name	Type	Description
`fd`	`FileDescriptor`	an open descriptor
`statBuffer`	`*var opaque`	receives the architecture's `struct stat`

Returns: zero, or a negative error number

`Dup2`

pub func Dup2(
    oldFd: FileDescriptor,
    newFd: FileDescriptor
) -> int64

Makes newFd a copy of oldFd, closing whatever newFd was. Returns newFd, or a negative error number. Duplicating a descriptor onto itself returns it unchanged. FreeBSD has dup2 on both architectures, so this is the plain form rather than Linux's dup3; setting close-on-exec is a separate fcntl this package does not wrap.

Source

Parameters

Name	Type	Description
`oldFd`	`FileDescriptor`	the descriptor to duplicate
`newFd`	`FileDescriptor`	the number the duplicate should have

Returns: newFd, or a negative error number

`Pipe2`

pub func Pipe2(
    descriptors: *var int32,
    flags: int32
) -> int64

Creates a pipe and writes its two descriptors into descriptors. The reading end lands at index zero and the writing end at index one. flags may carry OpenCloseOnExec and OpenNonBlocking. descriptors must be writable for two int32 values.

Source

Parameters

Name	Type	Description
`descriptors`	`*var int32`	receives the read end at index zero and the write end at index one
`flags`	`int32`	zero, or `OpenCloseOnExec` for both ends

Returns: zero, or a negative error number

Errors

The error numbers, and telling a raw result from an error.

Memory

Mapping, protecting and advising on pages of memory.

Edit this page on GitHub