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

`AtFdCwd`

pub const AtFdCwd: int32 = -2;

AT_FDCWD: resolve a relative path against the current directory rather than a descriptor. Darwin spells this -2, where Linux and FreeBSD both use -100. Carrying the value between packages produces a descriptor number, not an error.

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.

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 = 0x01000000;

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

Source

`OpenDirectory`

pub const OpenDirectory: int32 = 0x00100000;

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

`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.

Source

Parameters

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

Returns: zero, or a negative error number

`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.

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

`Fstat`

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

Fills statBuffer with what the kernel knows about the file behind fd. Returns zero, or a negative error number. statBuffer must be writable for the whole of the 64-bit-inode struct stat, which is 144 bytes.

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

`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 the 64-bit-inode struct stat, which is 144 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 toward the storage device. Returns zero, or a negative error number. This is weaker on Darwin than everywhere else: it hands the data to the device without waiting for the device to commit it, so a power failure can still lose a write this reported as flushed. F_FULLFSYNC through fcntl is what actually waits, and this package does not wrap it.

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

`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.

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

`Pipe`

pub func Pipe(descriptors: *var 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. Darwin has no pipe2, so close-on-exec has to be set afterwards through fcntl — which leaves a window another thread can execute through. 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

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