POSIX files (The GNU Algol 68 Compiler)

### 8.5 POSIX files ¶

File descriptors are `int` values that identify open files that can be accessed by the program. The `fopen` procedure allocates file descriptors as it opens files, and the descriptor is used in subsequent transput calls to perform operations on the files.

#### 8.5.1 Standard file descriptors ¶

There are three descriptors, however, which are automatically opened when the program starts executing and automatically closed when the program finishes. These are:

Constant: `int` stdin ¶

  File descriptor associated with the standard input. Its value is `0`.

Constant: `int` stdout ¶

  File descriptor associated with the standard output. Its value is `1`.

Constant: `int` stderr ¶

  File descriptor associated with the standard error. Its value is `2`.

#### 8.5.2 Opening and closing files ¶

Procedure: fopen `= (string pathname, bits flags) int` ¶

  Open the file specified by `pathname`. The argument `flags` is a combination of `file o` flags as defined below. If the specified file is successfully opened while satisfying the constraints implied by `flags` then this procedure yields a file descriptor that is used in subsequent I/O calls to refer to the open file. Otherwise, this procedure yields -1. The particular error can be inspected by calling the `errno` procedure.

Procedure: fclose `= (int fd) int` ¶

  Close the given file descriptor, which no longer refers to any file. This procedure yields zero on success, and -1 on error. In the later case, the program can look at the particular error by calling the `errno` procedure.

#### 8.5.3 Creating files ¶

Procedure: fcreate `= (string pathname, bits mode) int` ¶

  Create a file with name `pathname`. The argument `mode` is a `bits` value containing a bit pattern that determines the permissions on the created file. The bit pattern has the form `8rUGO`, where `U` reflects the permissions of the user who owns the file, `G` reflects the permissions of the users pertaining to the file’s group, and `O` reflects the permissions of all other users. The permission bits are 1 for execute, 2 for write and 4 for read. If the file is successfully created then this procedure yields a file descriptor that is used in subsequent I/O calls to refer to the newly created file. Otherwise, this procedure yields -1. The particular error can be inspected by calling the `errno` procedure.

#### 8.5.4 Flags for `fopen` ¶

The following flags can be combined using bit-wise operators. Note that in POSIX systems the effective mode of the created file is the mode specified by the programmer masked with the process’s umask.

Constant: `bits` file o default ¶

  Flag for `fopen` indicating that the file shall be opened with whatever capabilities allowed by its permissions.

Constant: `bits` file o rdwr ¶

  Flag for `fopen` indicating that the file shall be opened for both reading and writing.

Constant: `bits` file o rdonly ¶

  Flag for `fopen` indicating that the file shall be opened for reading only. This flag is not compatible with `file o rdwr` nor with `file o wronly`.

Constant: `bits` file o wronly ¶

  Flag for `fopen` indicating that the file shall be opened for write only. This flag is not compatible with `file o rdwr` nor with `file o rdonly`.

Constant: `bits` file o trunc ¶

  Flag for `fopen` indicating that the opened file shall be truncated upon opening it. The file must allow writing for this flag to take effect. The effect of combining `file o trunc` and `file o rdonly` is undefined and varies among implementations.

#### 8.5.5 Getting file properties ¶

Procedure: fsize `= (int fd) long long int` ¶

  Return the size in bytes of the file characterized by the file descriptor `fd`. If the system entity characterized by the given file descriptor doesn’t have a size, if the size of the file cannot be stored in a `long long int`, or if there is any other error condition, this procedure yields -1 and `errno` is set appropriately.

Procedure: lseek `= (int fd, long long int offset, int whence) long long int` ¶

  Set the file offset of the file characterized by the file descriptor `fd` depending on the values of `offset` and `whence`. On success, the resulting offset, as measured in bytes from the beginning of the file, is returned. Otherwise, -1 is returned, `errno` is set to indicate the error, and the file offset remains unchanged. The effects of `offset` and `whence` are:

  - If `whence` is `seek set`, the file offset is set to `offset` bytes.
  - If `whence` is `seek cur`, the file offset is set to its current location plus `offset`.
  - If `whence` is `seek end`, the file offset is set to the size of the file plus `offset`.