Next Previous Contents

## 14. Low-level POSIX I/O functions

## 14.1 close

Synopsis

  Close an open file descriptor

Usage

  `Int_Type close (FD_Type fd)`

Description

  The `close` function is used to close and open file descriptor created by the `open` function. Upon success `0` is returned, otherwise the function returns `-1` and sets `errno` accordingly.

See Also

  `open, fclose, read, write`

## 14.2 dup_fd

Synopsis

  Duplicate a file descriptor

Usage

  `FD_Type dup_fd (FD_Type fd)`

Description

  The `dup_fd` function duplicates a specified file descriptor and returns the duplicate. If the function fails, `NULL` will be returned and `errno` set accordingly.

Notes

  This function is essentially a wrapper around the POSIX `dup` function.

See Also

  `open, close`

## 14.3 fileno

Synopsis

  Convert a stdio File_Type object to a FD_Type descriptor

Usage

  `FD_Type fileno (File_Type fp)`

Description

  The `fileno` function returns the `FD_Type` descriptor associated with the stdio `File_Type` file pointer. Upon failure, `NULL` is returned.

See Also

  `fopen, open, fclose, close, dup_fd`

## 14.4 isatty

Synopsis

  Determine if an open file descriptor refers to a terminal

Usage

  `Int_Type isatty (FD_Type or File_Type fd)`

Description

  This function returns `1` if the file descriptor `fd` refers to a terminal; otherwise it returns `0`. The object `fd` may either be a `File_Type` stdio descriptor or a lower-level `FD_Type` object.

See Also

  `fopen, fclose, fileno`

## 14.5 lseek

Synopsis

  Reposition a file descriptor's file pointer

Usage

  `Long_Type lseek (FD_Type fd, LLong_Type ofs, int mode)` The `lseek` function repositions the file pointer associated with the open file descriptor `fd` to the offset `ofs` according to the mode parameter. Specifically, `mode` must be one of the values:

  > `

  >          SEEK_SET   Set the offset to ofs from the beginning of the file
  >          SEEK_CUR   Add ofs to the current offset
  >          SEEK_END   Add ofs to the current file size

  > `

  Upon error, `lseek` returns `-1` and sets `errno`. If successful, it returns the new filepointer offset.
Notes

  Not all file descriptors are capable of supporting the seek operation, e.g., a descriptor associated with a pipe.

  By using `SEEK_END` with a positive value of the `ofs` parameter, it is possible to position the file pointer beyond the current size of the file.

See Also

  `fseek, ftell, open, close`

## 14.6 open

Synopsis

  Open a file

Usage

  `FD_Type open (String_Type filename, Int_Type flags [,Int_Type mode])`

Description

  The `open` function attempts to open a file specified by the `filename` parameter according to the `flags` parameter, which must be one of the following values:

  > `

  >          O_RDONLY   (read-only)
  >          O_WRONLY   (write-only)
  >          O_RDWR     (read/write)

  > `

  In addition, `flags` may also be bitwise-or'd with any of the following:

  > `

  >          O_BINARY   (open the file in binary mode)
  >          O_TEXT     (open the file in text mode)
  >          O_CREAT    (create the file if it does not exist)
  >          O_EXCL     (fail if the file already exists)
  >          O_NOCTTY   (do not make the device the controlling terminal)
  >          O_TRUNC    (truncate the file if it exists)
  >          O_APPEND   (open the file in append mode)
  >          O_NONBLOCK (open the file in non-blocking mode)

  > `

  Some of these flags make sense only when combined with other flags. For example, if O_EXCL is used, then O_CREAT must also be specified, otherwise unpredictable behavior may result.

  If `O_CREAT` is used for the `flags` parameter then the `mode` parameter must be present. `mode` specifies the permissions to use if a new file is created. The actual file permissions will be affected by the process's `umask` via `mode&~umask`. The `mode` parameter's value is constructed via bitwise-or of the following values:

  > `

  >          S_IRWXU    (Owner has read/write/execute permission)
  >          S_IRUSR    (Owner has read permission)
  >          S_IWUSR    (Owner has write permission)
  >          S_IXUSR    (Owner has execute permission)
  >          S_IRWXG    (Group has read/write/execute permission)
  >          S_IRGRP    (Group has read permission)
  >          S_IWGRP    (Group has write permission)
  >          S_IXGRP    (Group has execute permission)
  >          S_IRWXO    (Others have read/write/execute permission)
  >          S_IROTH    (Others have read permission)
  >          S_IWOTH    (Others have write permission)
  >          S_IXOTH    (Others have execute permission)

  > `

  Upon success `open` returns a file descriptor object (`FD_Type`), otherwise `NULL` is returned and `errno` is set.
Notes

  If you are not familiar with the `open` system call, then it is recommended that you use `fopen` instead and use the higher level stdio interface.

See Also

  `fopen, close, read, write, stat_file`

## 14.7 read

Synopsis

  Read from an open file descriptor

Usage

  `UInt_Type read (FD_Type fd, Ref_Type buf, UInt_Type num)`

Description

  The `read` function attempts to read at most `num` bytes into the variable indicated by `buf` from the open file descriptor `fd`. It returns the number of bytes read, or `-1` upon failure and sets `errno`. The number of bytes read may be less than `num`, and will be zero if an attempt is made to read past the end of the file.

Notes

  `read` is a low-level function and may return `-1` for a variety of reasons. For example, if non-blocking I/O has been specified for the open file descriptor and no data is available for reading then the function will return `-1` and set `errno` to `EAGAIN`.

See Also

  `fread, open, close, write`

## 14.8 write

Synopsis

  Write to an open file descriptor

Usage

  `UInt_Type write (FD_Type fd, BString_Type buf)`

Description

  The `write` function attempts to write the bytes specified by the `buf` parameter to the open file descriptor `fd`. It returns the number of bytes successfully written, or `-1` and sets `errno` upon failure. The number of bytes written may be less than `length(buf)`.

See Also

  `read, fwrite, open, close`

Next Previous Contents