# Module `file` - File library

File library.

This library provides a subset of the standard POSIX file-handling functions, with some additions. Many of the provided processes (`file.open`, `file.close`, ...) are implemented as direct C calls rather than as blocking calls, as they are unlikely to block in the OS kernel.

This may be used as a replacement for the hostio/hostsp libraries when writing applications for POSIX platforms.

To use this library:

    #INCLUDE "file.module"

## Index

- Group `ACCESS` - Constants for
  - Constant `F.OK` - Check existance
  - Constant `R.OK` - Check read permission
  - Constant `W.OK` - Check write permission
  - Constant `X.OK` - Check execute permission
- Record `DIRENT` - Information about a directory entry
  - Variable `filename` - Filename, terminated with '*0'
- Group `FCNTL` - Constants for and
  - Constant `F.DUPFD` - Duplicate file descriptor
  - Constant `F.GETFD` - Read the close-on-exec flag
  - Constant `F.GETFL` - Get file descriptor flags
  - Constant `F.GETLK` - Get flock structure
  - Constant `F.GETLK64` - Get flock64 structure
  - Constant `F.GETOWN` - Get process ID receiving SIGIO and SIGURG signals
  - Constant `F.GETSIG` - Set signal sent when I/O becomes available on the descriptor
  - Constant `F.RDLCK` - Obtain read lock
  - Constant `F.SETFD` - Set the close-on-exec flag
  - Constant `F.SETFL` - Set file descriptor flags
  - Constant `F.SETLK` - Set file lock
  - Constant `F.SETLK64` - Set 64-bit file lock
  - Constant `F.SETLKW` - Set file lock with wait
  - Constant `F.SETLKW64` - Set 64-bit file lock with wait
  - Constant `F.SETOWN` - Set process ID that will receive SIGIO and SIGURG signals
  - Constant `F.SETSIG` - Get signal sent when I/O becomes available on the descriptor
  - Constant `F.UNLCK` - Release lock
  - Constant `F.WRLCK` - Obtain write lock
  - Constant `FD.CLOEXEC` - Close-on-exec flag for /
- Group `FILE.MODE` - Constants for file modes
  - Constant `S.I644` - User may write; all may read
  - Constant `S.I755` - User may write; all may read and execute
  - Constant `S.IFBLK` - Block device
  - Constant `S.IFCHR` - Character device
  - Constant `S.IFDIR` - Directory
  - Constant `S.IFIFO` - FIFO
  - Constant `S.IFLNK` - Symbolic link
  - Constant `S.IFMT` - Bitmask for the file type bitfields
  - Constant `S.IFREG` - Regular file
  - Constant `S.IFSOCK` - Socket
  - Constant `S.IRGRP` - Group may read
  - Constant `S.IROTH` - Others may read
  - Constant `S.IRUSR` - User may read
  - Constant `S.IRWXG` - Group may read, write and execute
  - Constant `S.IRWXO` - Others may read, write and execute
  - Constant `S.IRWXU` - User may read, write and execute
  - Constant `S.ISGID` - Set-GID
  - Constant `S.ISUID` - Set-UID
  - Constant `S.ISVTX` - Sticky
  - Constant `S.IWGRP` - Group may write
  - Constant `S.IWOTH` - Others may write
  - Constant `S.IWUSR` - User may write
  - Constant `S.IXGRP` - Group may execute
  - Constant `S.IXOTH` - Others may execute
  - Constant `S.IXUSR` - User may execute
- Protocol `GETOPT` - Responses from
  - Tag `arg` - A non-option argument (such as foo )
  - Tag `bad` - An unrecognised option
  - Tag `done` - No more options
  - Tag `opt` - An option (such as -a )
  - Tag `opt.arg` - An option with an argument (such as -a foo )
- Protocol `GETOPT.LONG` - Responses from
  - Tag `arg` - A non-option argument (such as foo )
  - Tag `bad` - An unrecognised option
  - Tag `done` - No more options
  - Tag `opt` - An option (such as -a or --arg )
  - Tag `opt.arg` - An option with an argument (such as -a foo or --arg foo )
- Group `OPEN.MODE` - Constants for
  - Constant `O.APPEND` - Position file pointer at EOF before each write
  - Constant `O.ASYNC` - Generate a signal when IO becomes possible
  - Constant `O.CREAT` - Create if not already present
  - Constant `O.DIRECT` - Don't cache data for this file
  - Constant `O.DIRECTORY` - Fail if not opening a directory
  - Constant `O.EXCL` - Fail if is given and the file already exists
  - Constant `O.LARGEFILE` - Allow the file to be larger than 2GB
  - Constant `O.NDELAY` - Synonym for
  - Constant `O.NOCTTY` - Don't become controlling terminal
  - Constant `O.NOFOLLOW` - Don't follow symbolic links when opening
  - Constant `O.NONBLOCK` - Make operations on this FD not block
  - Constant `O.RDONLY` - Open for reading
  - Constant `O.RDWR` - Open for reading and writing
  - Constant `O.SYNC` - Open for synchronous IO
  - Constant `O.TRUNC` - Truncate to zero length after opening
  - Constant `O.WRONLY` - Open for writing
- Group `SEEK` - Constants for
  - Constant `SEEK.CUR` - Relative to current location
  - Constant `SEEK.END` - Relative to end of file
  - Constant `SEEK.SET` - Relative to start of file
- Record `STAT` - Information about a filesystem object
  - Variable `atime` - Access time
  - Variable `blksize` - Block size for filesystem IO
  - Variable `blocks` - Number of blocks allocated
  - Variable `ctime` - Change time
  - Variable `dev` - Device number
  - Variable `gid` - Group's gid
  - Variable `ino` - Inode number
  - Variable `mode` - Object type and permissions
  - Variable `mtime` - Modification time
  - Variable `nlink` - Number of links
  - Variable `rdev` - Device type
  - Variable `size` - Size in bytes
  - Variable `uid` - Owner's uid
- Process `file.altable.fd.fd.copy` - ALT able equivalent of
- Process `file.altable.read` - ALT able equivalent of
- Process `file.altable.write` - ALT able equivalent of
- Process `file.array.select` - Wait for one of a set of file descriptors to become ready
- Process `file.blocking.read` - Read from a file descriptor into a buffer without blocking the occam system
- Process `file.blocking.write` - Write from a buffer to a file descriptor without blocking the occam system
- Process `file.check.access` - Check access to a filesystem object
- Process `file.chmod` - Change the permissions of a filesystem object
- Process `file.close` - Close a file descriptor
- Process `file.closedir` - Close a directory descriptor
- Process `file.dup2` - Make a copy of a file descriptor
- Process `file.fcntl0` - Perform various operations on file descriptors
- Process `file.fcntl1` - Perform various operations on file descriptors
- Process `file.fd.fd.copy` - Copy bytes between file descriptors
- Process `file.fstat` - Get information about an open filesystem object
- Process `file.fsync` - Force changes to an open file to be written to disk
- Process `file.get.long.options` - Parse command-line options
- Process `file.get.options` - Parse command-line options
- Function `file.high.fd` - Find the highest file descriptor in three sets
- Process `file.lstat` - Get information about a filesystem object or link
- Process `file.mkdir` - Create a directory
- Process `file.npipes` - Create several pipes using
- Process `file.nth.arg` - Get a program argument
- Process `file.num.args` - Get number of program arguments
- Process `file.open` - Open a file descriptor
- Process `file.open3` - Open a file descriptor
- Process `file.opendir` - Open a directory
- Process `file.pipe` - Create a pipe
- Process `file.read` - Read from a file descriptor into a buffer
- Process `file.readdir` - Read the next directory entry from a directory
- Process `file.rmdir` - Remove a directory
- Process `file.seek` - Move the read/write offset of a file descriptor
- Process `file.sendfile` - Copy bytes between file descriptors efficiently
- Process `file.size` - Get the size of a filesystem object
- Process `file.stat` - Get information about a filesystem object
- Process `file.unlink` - Unlink a filesystem object
- Process `file.write` - Write from a buffer to a file descriptor

## Declarations

### `filelib.inc`:22Group `ACCESS`

``

Constants for `file.check.access`.

### `filelib.inc`:23Constant `R.OK`

`VAL R.OK`

Check read permission

### `filelib.inc`:24Constant `W.OK`

`VAL W.OK`

Check write permission

### `filelib.inc`:25Constant `X.OK`

`VAL X.OK`

Check execute permission

### `filelib.inc`:26Constant `F.OK`

`VAL F.OK`

Check existance

### `filelib.inc`:28Group `OPEN.MODE`

``

Constants for `file.open`.

### `filelib.inc`:31Constant `O.RDONLY`

`VAL O.RDONLY`

Open for reading

### `filelib.inc`:33Constant `O.WRONLY`

`VAL O.WRONLY`

Open for writing

### `filelib.inc`:35Constant `O.RDWR`

`VAL O.RDWR`

Open for reading and writing

### `filelib.inc`:37Constant `O.CREAT`

`VAL O.CREAT`

Create if not already present

### `filelib.inc`:39Constant `O.EXCL`

`VAL O.EXCL`

Fail if `O.CREAT` is given and the file already exists

### `filelib.inc`:41Constant `O.NOCTTY`

`VAL O.NOCTTY`

Don't become controlling terminal

### `filelib.inc`:43Constant `O.TRUNC`

`VAL O.TRUNC`

Truncate to zero length after opening

### `filelib.inc`:45Constant `O.APPEND`

`VAL O.APPEND`

Position file pointer at EOF before each write

### `filelib.inc`:47Constant `O.NONBLOCK`

`VAL O.NONBLOCK`

Make operations on this FD not block

### `filelib.inc`:50Constant `O.NDELAY`

`VAL O.NDELAY`

Synonym for `O.NONBLOCK`

Deprecated: do not use in new code.

### `filelib.inc`:52Constant `O.SYNC`

`VAL O.SYNC`

Open for synchronous IO

### `filelib.inc`:54Constant `O.ASYNC`

`VAL O.ASYNC`

Generate a signal when IO becomes possible

### `filelib.inc`:56Constant `O.DIRECT`

`VAL O.DIRECT`

Don't cache data for this file

### `filelib.inc`:58Constant `O.LARGEFILE`

`VAL O.LARGEFILE`

Allow the file to be larger than 2GB

### `filelib.inc`:60Constant `O.DIRECTORY`

`VAL O.DIRECTORY`

Fail if not opening a directory

### `filelib.inc`:62Constant `O.NOFOLLOW`

`VAL O.NOFOLLOW`

Don't follow symbolic links when opening

### `filelib.inc`:64Group `SEEK`

``

Constants for `file.seek`.

### `filelib.inc`:65Constant `SEEK.SET`

`VAL SEEK.SET`

Relative to start of file

### `filelib.inc`:66Constant `SEEK.CUR`

`VAL SEEK.CUR`

Relative to current location

### `filelib.inc`:67Constant `SEEK.END`

`VAL SEEK.END`

Relative to end of file

### `filelib.inc`:69Group `FCNTL`

``

Constants for `file.fcntl0` and `file.fcntl1`.

### `filelib.inc`:70Constant `F.DUPFD`

`VAL F.DUPFD`

Duplicate file descriptor

### `filelib.inc`:71Constant `F.GETFD`

`VAL F.GETFD`

Read the close-on-exec flag

### `filelib.inc`:72Constant `F.SETFD`

`VAL F.SETFD`

Set the close-on-exec flag

### `filelib.inc`:75Constant `F.GETFL`

`VAL F.GETFL`

Get file descriptor flags. See `OPEN.MODE`.

### `filelib.inc`:78Constant `F.SETFL`

`VAL F.SETFL`

Set file descriptor flags. See `OPEN.MODE`.

### `filelib.inc`:81Constant `F.GETLK`

`VAL F.GETLK`

Get `flock` structure. Not fully supported.

### `filelib.inc`:84Constant `F.SETLK`

`VAL F.SETLK`

Set file lock. Not fully supported.

### `filelib.inc`:87Constant `F.SETLKW`

`VAL F.SETLKW`

Set file lock with wait. Not fully supported.

### `filelib.inc`:92Constant `F.SETOWN`

`VAL F.SETOWN`

Set process ID that will receive `SIGIO` and `SIGURG` signals. Use a negative ID for a process group. Not fully supported.

### `filelib.inc`:96Constant `F.GETOWN`

`VAL F.GETOWN`

Get process ID receiving SIGIO and SIGURG signals. Returns a negative ID for a process group. Not fully supported.

### `filelib.inc`:100Constant `F.SETSIG`

`VAL F.SETSIG`

Get signal sent when I/O becomes available on the descriptor. `0` means `SIGIO`. `SA_SIGINFO` may be available. Not fully supported.

### `filelib.inc`:104Constant `F.GETSIG`

`VAL F.GETSIG`

Set signal sent when I/O becomes available on the descriptor. `0` means `SIGIO`. `SA_SIGINFO` may be available. Not fully supported.

### `filelib.inc`:108Constant `F.GETLK64`

`VAL F.GETLK64`

Get `flock64` structure. Not fully supported.

### `filelib.inc`:111Constant `F.SETLK64`

`VAL F.SETLK64`

Set 64-bit file lock. Not fully supported.

### `filelib.inc`:114Constant `F.SETLKW64`

`VAL F.SETLKW64`

Set 64-bit file lock with wait. Not fully supported.

### `filelib.inc`:116Constant `FD.CLOEXEC`

`VAL FD.CLOEXEC`

Close-on-exec flag for `F.GETFD`/`F.SETFD`

### `filelib.inc`:117Constant `F.RDLCK`

`VAL F.RDLCK`

Obtain read lock

### `filelib.inc`:118Constant `F.WRLCK`

`VAL F.WRLCK`

Obtain write lock

### `filelib.inc`:119Constant `F.UNLCK`

`VAL F.UNLCK`

Release lock

### `filelib.inc`:123Group `FILE.MODE`

``

Constants for file modes.

### `filelib.inc`:124Constant `S.IRWXU`

`VAL S.IRWXU`

User may read, write and execute

### `filelib.inc`:125Constant `S.IRUSR`

`VAL S.IRUSR`

User may read

### `filelib.inc`:126Constant `S.IWUSR`

`VAL S.IWUSR`

User may write

### `filelib.inc`:127Constant `S.IXUSR`

`VAL S.IXUSR`

User may execute

### `filelib.inc`:128Constant `S.IRWXG`

`VAL S.IRWXG`

Group may read, write and execute

### `filelib.inc`:129Constant `S.IRGRP`

`VAL S.IRGRP`

Group may read

### `filelib.inc`:130Constant `S.IWGRP`

`VAL S.IWGRP`

Group may write

### `filelib.inc`:131Constant `S.IXGRP`

`VAL S.IXGRP`

Group may execute

### `filelib.inc`:132Constant `S.IRWXO`

`VAL S.IRWXO`

Others may read, write and execute

### `filelib.inc`:133Constant `S.IROTH`

`VAL S.IROTH`

Others may read

### `filelib.inc`:134Constant `S.IWOTH`

`VAL S.IWOTH`

Others may write

### `filelib.inc`:135Constant `S.IXOTH`

`VAL S.IXOTH`

Others may execute

### `filelib.inc`:136Constant `S.I644`

`VAL S.I644`

User may write; all may read

### `filelib.inc`:137Constant `S.I755`

`VAL S.I755`

User may write; all may read and execute

### `filelib.inc`:138Constant `S.IFMT`

`VAL INT32 S.IFMT`

Bitmask for the file type bitfields

### `filelib.inc`:139Constant `S.IFSOCK`

`VAL INT32 S.IFSOCK`

Socket

### `filelib.inc`:140Constant `S.IFLNK`

`VAL INT32 S.IFLNK`

Symbolic link

### `filelib.inc`:141Constant `S.IFREG`

`VAL INT32 S.IFREG`

Regular file

### `filelib.inc`:142Constant `S.IFBLK`

`VAL INT32 S.IFBLK`

Block device

### `filelib.inc`:143Constant `S.IFDIR`

`VAL INT32 S.IFDIR`

Directory

### `filelib.inc`:144Constant `S.IFCHR`

`VAL INT32 S.IFCHR`

Character device

### `filelib.inc`:145Constant `S.IFIFO`

`VAL INT32 S.IFIFO`

FIFO

### `filelib.inc`:146Constant `S.ISUID`

`VAL INT32 S.ISUID`

Set-UID

### `filelib.inc`:147Constant `S.ISGID`

`VAL INT32 S.ISGID`

Set-GID

### `filelib.inc`:148Constant `S.ISVTX`

`VAL INT32 S.ISVTX`

Sticky

### `filelib.inc`:157Protocol `GETOPT`

`PROTOCOL GETOPT`

Responses from `file.get.options`.

### `filelib.inc`:161Tag `opt`

`opt; BYTE`

An option (such as `-a`).

#### Parameters:

`BYTE` | `opt` | The option

### `filelib.inc`:165Tag `opt.arg`

`opt.arg; BYTE; MOBILE []BYTE`

An option with an argument (such as `-a foo`).

#### Parameters:

`BYTE` | `opt` | The option
`MOBILE []BYTE` | `arg` | The argument

### `filelib.inc`:168Tag `arg`

`arg; MOBILE []BYTE`

A non-option argument (such as `foo`).

#### Parameters:

`MOBILE []BYTE` | `arg` | The argument

### `filelib.inc`:172Tag `bad`

`bad; BYTE`

An unrecognised option. This will be followed immediately by `done`.

#### Parameters:

`BYTE` | `opt` | The option

### `filelib.inc`:174Tag `done`

`done`

No more options.

### `filelib.inc`:179Protocol `GETOPT.LONG`

`PROTOCOL GETOPT.LONG`

Responses from `file.get.long.options`.

### `filelib.inc`:183Tag `opt`

`opt; MOBILE []BYTE`

An option (such as `-a` or `--arg`).

#### Parameters:

`MOBILE []BYTE` | `opt` | The option (e.g. `a` or `arg`)

### `filelib.inc`:187Tag `opt.arg`

`opt.arg; MOBILE []BYTE; MOBILE []BYTE`

An option with an argument (such as `-a foo` or `--arg foo`).

#### Parameters:

`MOBILE []BYTE` | `opt` | The option (e.g. `a` or `arg`)
`MOBILE []BYTE` | `arg` | The argument

### `filelib.inc`:190Tag `arg`

`arg; MOBILE []BYTE`

A non-option argument (such as `foo`).

#### Parameters:

`MOBILE []BYTE` | `arg` | The argument

### `filelib.inc`:194Tag `bad`

`bad; MOBILE []BYTE`

An unrecognised option. This will be followed immediately by `done`.

#### Parameters:

`MOBILE []BYTE` | `opt` | The option

### `filelib.inc`:196Tag `done`

`done`

No more options.

### `filelib.inc`:207Record `STAT`

`DATA TYPE STAT`

Information about a filesystem object. This is the result from `file.stat`, `file.lstat` and `file.fstat`. See the `stat(2)` manual page for more information on the meaning of the fields.

### `filelib.inc`:209Variable `dev`

`INT64`

Device number

### `filelib.inc`:210Variable `ino`

`INT64`

Inode number

### `filelib.inc`:211Variable `mode`

`INT32`

Object type and permissions

### `filelib.inc`:212Variable `nlink`

`INT32`

Number of links

### `filelib.inc`:213Variable `uid`

`INT32`

Owner's uid

### `filelib.inc`:214Variable `gid`

`INT32`

Group's gid

### `filelib.inc`:215Variable `rdev`

`INT64`

Device type

### `filelib.inc`:216Variable `size`

`INT32`

Size in bytes

### `filelib.inc`:217Variable `blksize`

`INT32`

Block size for filesystem IO

### `filelib.inc`:218Variable `blocks`

`INT32`

Number of blocks allocated

### `filelib.inc`:219Variable `atime`

`INT32`

Access time

### `filelib.inc`:220Variable `mtime`

`INT32`

Modification time

### `filelib.inc`:221Variable `ctime`

`INT32`

Change time

### `filelib.inc`:229Record `DIRENT`

`DATA TYPE DIRENT`

Information about a directory entry. This is the result from `file.readdir`.

### `filelib.inc`:231Variable `filename`

`[256]BYTE`

Filename, terminated with `'*0'`

### `filelib.occ`:92Process `file.check.access`

`PROC file.check.access (VAL []BYTE filename, VAL INT what, BOOL result)`

Check access to a filesystem object.

#### Parameters:

`VAL []BYTE` | `filename` | The filename to check
`VAL INT` | `what` | Bitwise OR of permissions to test (see `ACCESS`)
`BOOL` | `result` | `TRUE` if the access check succeeded, else `FALSE`

### `filelib.occ`:108Process `file.size`

`PROC file.size (VAL []BYTE filename, INT result)`

Get the size of a filesystem object.

#### Parameters:

`VAL []BYTE` | `filename` | The filename to examine
`INT` | `result` | The size of the object in bytes, or `-1` if it does not exist

### `filelib.occ`:119Process `file.open`

`PROC file.open (VAL []BYTE filename, VAL INT mode, INT fd)`

Open a file descriptor. This form should be used when `O.CREAT` is not among the modes.

#### Parameters:

`VAL []BYTE` | `filename` | The filename to open
`VAL INT` | `mode` | Bitwise OR of the file descriptor's modes (see `OPEN.MODE`)
`INT` | `fd` | The file descriptor, or `-1` if it cannot be opened

### `filelib.occ`:131Process `file.open3`

`PROC file.open3 (VAL []BYTE filename, VAL INT mode, VAL INT perm, INT fd)`

Open a file descriptor. This form should be used when `O.CREAT` is among the modes.

#### Parameters:

`VAL []BYTE` | `filename` | The filename to open
`VAL INT` | `mode` | Bitwise OR of the file descriptor's modes (see `OPEN.MODE`)
`VAL INT` | `perm` | The permissions of `filename` after creation
`INT` | `fd` | The file descriptor, or `-1` if it cannot be opened

### `filelib.occ`:163Process `file.pipe`

`PROC file.pipe (INT fd.0, fd.1, result)`

Create a pipe.

Example that copies a string by sending it through a pipe:

    INT fd.read, fd.write:
     INT result, result.rd, result.wr:
     VAL []BYTE string IS "hello world!":
     [(SIZE string)]BYTE buffer:
     SEQ
       file.pipe (fd.read, fd.write, result)
       ASSERT (result = 0)
       PAR
         file.blocking.read (fd.read, buffer, (SIZE string), result.rd)
         file.write (fd.write, string, (SIZE string), result.wr)
       file.close (fd.read, result)
       ASSERT (result = 0)
       file.close (fd.write, result)
       ASSERT (result = 0)

See `file.npipes` if you're creating several pipes.

#### Parameters:

`INT` | `fd.0` | File descriptor for the read end of the pipe
`INT` | `fd.1` | File descriptor for the write end of the pipe
`INT` | `result` | `0` if the pipe was created, or `-1` if an error occurred

### `filelib.occ`:174Process `file.dup2`

`PROC file.dup2 (VAL INT old.fd, VAL INT new.fd, INT result)`

Make a copy of a file descriptor. `new.fd` will be closed first if it is already open.

#### Parameters:

`VAL INT` | `old.fd` | The source descriptor
`VAL INT` | `new.fd` | The destination descriptor
`INT` | `result` | `0` if successful, `-1` if an error occurred

### `filelib.occ`:191Process `file.read`

`PROC file.read (VAL INT fd, []BYTE buffer, INT result)`

Read from a file descriptor into a buffer. No more than `SIZE buffer` bytes will be read from the descriptor.

Note: `file.read` assumes that data is available (e.g. reading from a file), and is not a blocking call; if the read could block, use `file.blocking.read` instead.

#### Parameters:

`VAL INT` | `fd` | The file descriptor
`[]BYTE` | `buffer` | The buffer
`INT` | `result` | The number of bytes read; or `0` if at end of file; or `-1` if an error occurred

### `filelib.occ`:204Process `file.blocking.read`

`PROC file.blocking.read (VAL INT fd, []BYTE buffer, INT result)`

Read from a file descriptor into a buffer without blocking the occam system. No more than `SIZE buffer` bytes will be read from the descriptor.

#### Parameters:

`VAL INT` | `fd` | The file descriptor
`[]BYTE` | `buffer` | The buffer
`INT` | `result` | The number of bytes read; or `0` if at end of file; or `-1` if an error occurred

### `filelib.occ`:221Process `file.write`

`PROC file.write (VAL INT fd, VAL []BYTE buffer, INT result)`

Write from a buffer to a file descriptor. No more than `SIZE buffer` bytes will be written.

Note: `file.write` assumes that data can always be written (e.g. writing to a file), and is not a blocking call; if the write could block, use `file.blocking.write` instead.

#### Parameters:

`VAL INT` | `fd` | The file descriptor
`VAL []BYTE` | `buffer` | The buffer
`INT` | `result` | The number of bytes written, or `-1` if an error occurred

### `filelib.occ`:233Process `file.blocking.write`

`PROC file.blocking.write (VAL INT fd, VAL []BYTE buffer, INT result)`

Write from a buffer to a file descriptor without blocking the occam system. No more than `SIZE buffer` bytes will be written.

#### Parameters:

`VAL INT` | `fd` | The file descriptor
`VAL []BYTE` | `buffer` | The buffer
`INT` | `result` | The number of bytes written, or `-1` if an error occurred

### `filelib.occ`:245Process `file.seek`

`PROC file.seek (VAL INT fd, VAL INT offset, VAL INT whence, INT result)`

Move the read/write offset of a file descriptor.

#### Parameters:

`VAL INT` | `fd` | The file descriptor
`VAL INT` | `offset` | The offset from the location in `whence`
`VAL INT` | `whence` | The base location; one of the `SEEK` constants
`INT` | `result` | The new absolute file offset, or `-1` if an error occurred

### `filelib.occ`:254Process `file.close`

`PROC file.close (VAL INT fd, RESULT INT result)`

Close a file descriptor.

#### Parameters:

`VAL INT` | `fd` | The file descriptor
`RESULT INT` | `result` | `0` upon success; `-1` if an error occurred

### `filelib.occ`:264Process `file.mkdir`

`PROC file.mkdir (VAL []BYTE pathname, VAL INT perm, INT result)`

Create a directory.

#### Parameters:

`VAL []BYTE` | `pathname` | Name of the directory
`VAL INT` | `perm` | Permissions (see `FILE.MODE`)
`INT` | `result` | `0` upon success; `-1` if an error occurred

### `filelib.occ`:274Process `file.rmdir`

`PROC file.rmdir (VAL []BYTE pathname, INT result)`

Remove a directory. The directory must be empty before it can be removed.

#### Parameters:

`VAL []BYTE` | `pathname` | Name of the directory
`INT` | `result` | `0` upon success; `-1` if an error occurred

### `filelib.occ`:284Process `file.unlink`

`PROC file.unlink (VAL []BYTE filename, INT result)`

Unlink a filesystem object. This can be used to remove anything that isn't a directory.

#### Parameters:

`VAL []BYTE` | `filename` | Name of the object
`INT` | `result` | `0` upon success; `-1` if an error occurred

### `filelib.occ`:300Process `file.fd.fd.copy`

`PROC file.fd.fd.copy (VAL INT src.fd, dst.fd, count, INT result)`

Copy bytes between file descriptors. The copy is performed in the background to reduce overhead.

#### Parameters:

`VAL INT` | `src.fd` | The source file descriptor
`VAL INT` | `dst.fd` | The destination file descriptor
`VAL INT` | `count` | The number of bytes to copy, or `0` to copy until end of file on `src.fd`
`INT` | `result` | `0` if the copy completed successfully, or `count` was `0` and `src.fd` was at end of file; `-1` if an error occurred; `-3` if `src.fd` reached end of file before `count` bytes had been copied

### `filelib.occ`:317Process `file.sendfile`

`PROC file.sendfile (VAL INT src.fd, dst.fd, count, INT offset, result)`

Copy bytes between file descriptors efficiently. This uses the `sendfile(2)` system call to avoid copying data between userspace and kernelspace. Either or both descriptors may refer to a socket.

#### Parameters:

`VAL INT` | `src.fd` | The source file descriptor
`VAL INT` | `dst.fd` | The destination file descriptor
`VAL INT` | `count` | The number of bytes to copy
`INT` | `offset` | The offset (in `src.fd`) to start copying from. After a successful copy, this is updated to point at the byte following the last one read.
`INT` | `result` | The number of bytes written, or `-1` if an error occurred.

### `filelib.occ`:328Process `file.npipes`

`PROC file.npipes ([]INT readers, writers, INT result)`

Create several pipes using `file.pipe`.

#### Parameters:

`[]INT` | `readers` | The read ends of the pipes
`[]INT` | `writers` | The write ends of the pipes
`INT` | `result` | `0` if the pipes were created, or `-1` if an error occurred

### `filelib.occ`:358Process `file.altable.read`

`PROC file.altable.read (CHAN OF BOOL kill, CHAN OF INT response, VAL INT fd, []BYTE buffer, INT result)`

`ALT`able equivalent of `file.blocking.read`.

### `filelib.occ`:390Process `file.altable.write`

`PROC file.altable.write (CHAN OF BOOL kill, CHAN OF INT response, VAL INT fd, VAL []BYTE buffer, INT result)`

`ALT`able equivalent of `file.blocking.write`.

### `filelib.occ`:422Process `file.altable.fd.fd.copy`

`PROC file.altable.fd.fd.copy (CHAN OF BOOL kill, CHAN OF INT response, VAL INT src.fd, dst.fd, count, INT result)`

`ALT`able equivalent of `file.fd.fd.copy`.

### `filelib.occ`:472Process `file.array.select`

`PROC file.array.select ([]INT read.set, write.set, except.set, VAL INT high.fd, timeout, RESULT INT result)`

Wait for one of a set of file descriptors to become ready. This performs the `select(2)` system call.

After `file.array.select` returns, the file descriptors in the sets that are not ready are changed to `-1`. Any file descriptors passed that are already `-1` are ignored.

#### Parameters:

`[]INT` | `read.set` | The set of reading file descriptors
`[]INT` | `write.set` | The set of writing file descriptors
`[]INT` | `except.set` | The set of exception-watching file descriptors
`VAL INT` | `high.fd` | The highest file descriptor in all three sets, plus one; you can use `file.high.fd` to calculate this
`VAL INT` | `timeout` | The time to wait for a file descriptor to become ready; or `0` to return immediately if none are ready; or `-1` to wait indefinitely
`RESULT INT` | `result` | The number of ready file descriptors in the three sets (which may be `0` if the timeout passed before any were ready), or `-1` if an error occurred

### `filelib.occ`:485Function `file.high.fd`

`INT FUNCTION file.high.fd (VAL []INT read.set, write.set, except.set)`

Find the highest file descriptor in three sets. This is for use with `file.array.select`.

#### Parameters:

`VAL []INT` | `read.set` | The set of reading file descriptors
`VAL []INT` | `write.set` | The set of writing file descriptors
`VAL []INT` | `except.set` | The set of exception-watching file descriptors

#### Returns:

`INT` |  | The highest file descriptor in the sets; add one to this to get the value to pass to `file.array.select`

### `filelib.occ`:513Process `file.fcntl0`

`PROC file.fcntl0 (VAL INT fd, cmd, RESULT INT result)`

Perform various operations on file descriptors. This allows occam-pi programs to make a `fcntl(2)` system call with no optional parameter. See the `fcntl(2)` manual page for more information.

#### Parameters:

`VAL INT` | `fd` | The (source) file descriptor
`VAL INT` | `cmd` | The command (one of `FCNTL`, such as `F.GETFD` or `F.GETFL`)
`RESULT INT` | `result` | The result of the operation

### `filelib.occ`:528Process `file.fcntl1`

`PROC file.fcntl1 (VAL INT fd, cmd, arg, RESULT INT result)`

Perform various operations on file descriptors. This allows occam-pi programs to make a `fcntl(2)` system call with one optional parameter. See the `fcntl(2)` manual page for more information.

#### Parameters:

`VAL INT` | `fd` | The (source) file descriptor
`VAL INT` | `cmd` | The command (one of `FCNTL`, such as `F.DUPFD`, `F.SETFD` or `F.SETFL`)
`VAL INT` | `arg` | A parameter for the operation
`RESULT INT` | `result` | The result of the operation

### `filelib.occ`:538Process `file.num.args`

`PROC file.num.args (RESULT INT n)`

Get number of program arguments. This is the equivalent of `argc` in C. Programs always have at least one argument: their own name.

#### Parameters:

`RESULT INT` | `n` | The number of arguments the program was given

### `filelib.occ`:565Process `file.nth.arg`

`PROC file.nth.arg (VAL INT n, RESULT []BYTE arg, RESULT INT len)`

Get a program argument. This is the equivalent of `argv[n]` in C.

For example, if the occam-pi program was invoked as `./argtest foo "bar foo"`, then argument 1 will be `foo`, argument 2 will be `bar foo`, and `file.num.args` will return 3.

If you want to parse Unix-style command-line options, use `file.get.options` instead.

#### Parameters:

`VAL INT` | `n` | The number of the argument to fetch
`RESULT []BYTE` | `arg` | The buffer to copy the argument into
`RESULT INT` | `len` | The length of the argument in bytes, or `SIZE arg` if the argument was too long to fit in the buffer

### `filelib.occ`:620Process `file.get.long.options`

`PROC file.get.long.options (MOBILE []MOBILE []BYTE options, CHAN GETOPT.LONG out!)`

Parse command-line options. This is intended to behave like GNU `getopt_long(3)`, but without support for permuting options.

The `options` argument is an array of strings listing the possible options for the program. Options that can take an argument should be followed by an equals sign.

Example, for a program which can take `-v`/`--verbose` and `-h`/`--host HOST` arguments:

    CHAN GETOPT.LONG opts:
     PAR
       INITIAL MOBILE []MOBILE []BYTE spec IS MOBILE [4]MOBILE []BYTE:
       SEQ
         spec[0] := "v"
         spec[1] := "verbose"
         spec[2] := "h="
         spec[3] := "host="
         file.get.long.options (spec, opts!)
       INITIAL BOOL running IS TRUE:
       WHILE running
         MOBILE []BYTE o, a:
         opts ? CASE
           opt; o
             IF
               same.string (o, "v") OR same.string (o, "verbose")
                 ...  handle -v option
           opt.arg; o; a
             IF
               same.string (o, "h") OR same.string (o, "host")
                 ...  handle -h option; argument is in a
           arg; a
             ...  handle non-option argument a
           bad; o
             ...  print usage message and exit
           done
             running := FALSE

#### Parameters:

`MOBILE []MOBILE []BYTE` | `options` | List of options that this program can take
`CHAN GETOPT.LONG` | `out` | Channel down which options are reported (using `GETOPT.LONG`)

### `filelib.occ`:889Process `file.get.options`

`PROC file.get.options (VAL []BYTE options, CHAN GETOPT out!)`

Parse command-line options. This is intended to behave like POSIX (not GNU) `getopt(3)`. If you want to handle long options, use `file.get.long.options` instead; this `PROC` will report all long options as `bad`.

The `options` argument is a string listing the possible (single-character) options for the program. Options that can take an argument should be followed by a colon.

Example, for a program which can take `-v` and `-h HOST` arguments:

    CHAN GETOPT opts:
     PAR
       file.get.options ("vh:", opts!)
       INITIAL BOOL running IS TRUE:
       WHILE running
         BYTE o:
         MOBILE []BYTE a:
         opts ? CASE
           opt; o
             CASE o
               'v'
                 ...  handle -v option
           opt.arg; o; a
             CASE o
               'h'
                 ...  handle -h option; argument is in a
           arg; a
             ...  handle non-option argument a
           bad; o
             ...  print usage message and exit
           done
             running := FALSE

#### Parameters:

`VAL []BYTE` | `options` | List of options that this program can take
`CHAN GETOPT` | `out` | Channel down which options are reported (using `GETOPT`)

### `filelib.occ`:949Process `file.stat`

`PROC file.stat (VAL []BYTE name, RESULT STAT info, RESULT INT res)`

Get information about a filesystem object. Symbolic links will be followed.

#### Parameters:

`VAL []BYTE` | `name` | The filename to examine
`RESULT STAT` | `info` | The returned information (see `STAT`)
`RESULT INT` | `res` | `0` on success, `-1` on error

### `filelib.occ`:959Process `file.lstat`

`PROC file.lstat (VAL []BYTE name, RESULT STAT info, RESULT INT res)`

Get information about a filesystem object or link. Symbolic links will not be followed.

#### Parameters:

`VAL []BYTE` | `name` | The filename to examine
`RESULT STAT` | `info` | The returned information (see `STAT`)
`RESULT INT` | `res` | `0` on success, `-1` on error

### `filelib.occ`:968Process `file.fstat`

`PROC file.fstat (VAL INT fd, RESULT STAT info, RESULT INT res)`

Get information about an open filesystem object.

#### Parameters:

`VAL INT` | `fd` | The file descriptor to examine
`RESULT STAT` | `info` | The returned information (see `STAT`)
`RESULT INT` | `res` | `0` on success, `-1` on error

### `filelib.occ`:976Process `file.opendir`

`PROC file.opendir (VAL []BYTE filename, RESULT INT dd)`

Open a directory.

#### Parameters:

`VAL []BYTE` | `filename` | The directory path
`RESULT INT` | `dd` | The returned directory descriptor, or `-1` on error

### `filelib.occ`:986Process `file.readdir`

`PROC file.readdir (VAL INT dd, RESULT DIRENT info, RESULT INT res)`

Read the next directory entry from a directory.

#### Parameters:

`VAL INT` | `dd` | The directory descriptor
`RESULT DIRENT` | `info` | The returned directory entry (see `DIRENT`)
`RESULT INT` | `res` | `0` on success, `-1` on error

### `filelib.occ`:994Process `file.closedir`

`PROC file.closedir (VAL INT dd, RESULT INT res)`

Close a directory descriptor.

#### Parameters:

`VAL INT` | `dd` | The directory descriptor
`RESULT INT` | `res` | `0` on success, `-1` on error

### `filelib.occ`:1004Process `file.chmod`

`PROC file.chmod (VAL []BYTE filename, INT mode, RESULT INT res)`

Change the permissions of a filesystem object.

#### Parameters:

`VAL []BYTE` | `filename` | The filename to change
`INT` | `mode` | The new permissions of the object (see `FILE.MODE`)
`RESULT INT` | `res` | `0` on success, `-1` on error

### `filelib.occ`:1013Process `file.fsync`

`PROC file.fsync (VAL INT fd, RESULT INT result)`

Force changes to an open file to be written to disk.

#### Parameters:

`VAL INT` | `fd` | The file descriptor
`RESULT INT` | `result` | `0` on success, `-1` on error