## Module (chicken file posix)

This module provides various operations on files and directories that are more POSIX-oriented than the generic higher-level operations from Module (chicken file).

Note that the following definitions are not all available on non-UNIX systems like Windows. See below for Windows specific notes.

All errors related to failing file-operations will signal a condition of kind `(exn i/o file)`.

- New in CHICKEN 5.4.0: Errors caused by underlying C calls that change errno will produce a condition object with an `errno` property, which can be accessed with `(get-condition-property <the-condition-object> 'exn 'errno)`.

### Constants

#### File-control Commands

fcntl/dupfd constant
fcntl/getfd constant
fcntl/setfd constant
fcntl/getfl constant
fcntl/setfl constant

  Operations used with `file-control`.

  NOTE: On native Windows builds (all except cygwin), these are all defined as zero. The `file-control` procedure to use these with is also unimplemented and will raise an error when called.

#### File positions

seek/cur constant
seek/set constant
seek/end constant

  File positions for `set-file-position!`.

#### Standard I/O file-descriptors

fileno/stdin constant
fileno/stdout constant
fileno/stderr constant

  Standard I/O file descriptor numbers, used with procedures such as `open-input-file*` which take file descriptors.

#### Open flags

open/rdonly constant
open/wronly constant
open/rdwr constant
open/read constant
open/write constant
open/creat constant
open/append constant
open/excl constant
open/noctty constant
open/nonblock constant
open/trunc constant
open/sync constant
open/fsync constant
open/binary constant
open/text constant

  Open flags used with the `file-open` procedure. `open/read` is a convenience synonym for `open/rdonly`, as is `open/write` for `open/wronly`.

  NOTE: On native Windows builds (all except cygwin), `open/noctty`, `open/nonblock`, `open/fsync` and `open/sync` are defined as zero because the corresponding flag doesn't exist. This means you can safely add these to any set of flags when opening a file or pipe, but it simply won't have an effect.

#### Open flags for create-pipe

open/noinherit constant

  This variable is a mode value for `create-pipe`. Useful when spawning a child process on Windows. On UNIX it is defined as zero, so you can safely pass it there, but it will have no effect.

#### Permission bits

perm/irusr constant
perm/iwusr constant
perm/ixusr constant
perm/irgrp constant
perm/iwgrp constant
perm/ixgrp constant
perm/iroth constant
perm/iwoth constant
perm/ixoth constant
perm/irwxu constant
perm/irwxg constant
perm/irwxo constant
perm/isvtx constant
perm/isuid constant
perm/isgid constant

  Permission bits used with, for example, `file-open`.

  NOTE: On native Windows builds (all except cygwin), `perm/isvtx`, `perm/isuid` and `perm/isgid` are defined as zero because the corresponding permission doesn't exist. This means you can safely add these to any set of flags when opening a file or pipe, but it simply won't have an effect.

### Information about files

#### directory?

directory? FILE procedure

  Returns `#t` if FILE designates a directory. Otherwise, it returns `#f`. FILE may be a pathname, a file-descriptor or a port object.

#### file-type

file-type FILE #!optional LINK ERROR procedure

  Returns the file-type for FILE, which should be a filename, a file-descriptor or a port object. If LINK is given and true, symbolic-links are not followed:

       regular-file
       directory
       fifo
       socket
       symbolic-link
       character-device
       block-device

  Note that not all types are supported on every platform. If ERROR is given and false, then `file-type` returns `#f` if the file does not exist; otherwise, it signals an error.

#### character-device?

#### block-device?

#### socket?

character-device? FILE procedure
block-device? FILE procedure
socket? FILE procedure

  These procedures return `#t` if FILE given is of the appropriate type. FILE may be a filename, a file-descriptor or a port object. Note that these operations follow symbolic links. If the file does not exist, `#f` is returned.

#### regular-file?

regular-file? FILE procedure

  Returns true, if FILE names a regular file (not a directory, socket, etc.) This operation follows symbolic links; use either `symbolic-link?` or `file-type` if you need to test for symlinks. FILE may refer to a filename, file descriptor or ports object.

### Fifos

#### create-fifo

create-fifo FILENAME #!optional MODE procedure

  Creates a FIFO with the name FILENAME and the permission bits MODE, which defaults to

       (+ perm/irwxu perm/irwxg perm/irwxo)

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### fifo?

fifo? FILE procedure

  Returns `#t` if FILE names a FIFO. FILE may be a filename, a port or a file-descriptor.

### Retrieving file attributes

#### file-access-time

#### file-change-time

#### file-modification-time

file-access-time FILE procedure
file-change-time FILE procedure
file-modification-time FILE procedure

  Returns time (in seconds) of the last access, inode change or content modification of FILE, respectively. FILE may be a filename, a file-descriptor or a file-backed port. If the file does not exist, an error is signaled.

#### set-file-times!

set-file-times! FILE #!optional MTIME ATIME procedure

  Sets the time of last modification MTIME and/or time of last access ATIME (in seconds) for FILE. FILE may be a filename, a file-descriptor or a file-backed port. If the file does not exist, an error is signaled.

  If neither MTIME nor ATIME is supplied, the current time is used. If only MTIME is supplied, ATIME will be set to the same value. If an argument is `#f`, it will not be changed.

  Consequently, if only MTIME is passed and it is `#f`, ATIME is assumed to be `#f` as well and neither will be changed.

#### file-stat

file-stat FILE #!optional LINK procedure

  Returns a 13-element vector with the following contents:

  index | value | field | notes
  --- | --- | --- | ---
  0 | inode number | `st_ino` |
  1 | mode | `st_mode` | bitfield combining file permissions and file type
  2 | number of hard links | `st_nlink` |
  3 | UID of owner | `st_uid` | as with `file-owner`
  4 | GID of owner | `st_gid` |
  5 | size | `st_size` | as with `file-size`
  6 | access time | `st_atime` | as with `file-access-time`
  7 | change time | `st_ctime` | as with `file-change-time`
  8 | modification time | `st_mtime` | as with `file-modification-time`
  9 | parent device ID | `st_dev` | ID of device on which this file resides
  10 | device ID | `st_rdev` | device ID for special files (i.e. the raw major/minor number)
  11 | block size | `st_blksize` |
  12 | number of blocks allocated | `st_blocks` |

  On Windows systems, the last 4 values are undefined.

  By default, symbolic links are followed and the status of the referenced file is returned; however, if the optional argument LINK is given and not `#f`, the status of the link itself is returned.

  FILE may be a filename, port or file-descriptor.

  Note that for very large files, the `file-size` value may be an inexact integer.

#### file-position

file-position FILE procedure

  Returns the current file position of FILE, which should be a port or a file-descriptor.

#### file-size

file-size FILE procedure

  Returns the size of the file designated by FILE. FILE may be a filename, a file-descriptor or a port object. If the file does not exist, an error is signaled. Note that for very large files, `file-size` may return an inexact integer.

#### file-owner

file-owner FILE procedure

  Returns the user-id of FILE (an exact integer). FILE may be a filename, a file-descriptor or a port object.

#### set-file-owner!

set-file-owner! FILE UID procedure
set! (file-owner FILE) UID procedure

  Changes the ownership of FILE to user-id UID (which should be an exact integer) using the `chown()` system call. FILE may be a filename, a file-descriptor or a port object.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-group

file-group FILE procedure

  Returns the group-id of FILE. FILE may be a filename, a file-descriptor or a port object.

#### set-file-group!

set-file-group! FILE GID procedure
set! (file-group FILE) GID procedure

  Changes the group ownership of FILE to group-id GID (which should be an exact integer) using the `chgrp()` system call. FILE may be a filename, a file-descriptor or a port object.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-permissions

file-permissions FILE procedure

  Returns the permission bits for FILE. You can test this value by performing bitwise operations on the result and the `perm/...` values. FILE may be a filename, a file-descriptor or a port object.

#### set-file-permissions!

set-file-permissions! FILE MODE procedure
set! (file-permissions FILE) MODE procedure

  Changes the current permission bits for FILE to MODE using the `chmod()` system call. The `perm/...` variables contain the various permission bits and can be combinded with the `bitwise-ior` procedure. FILE may be a filename, a file-descriptor or a port object, MODE should be a fixnum.

#### file-truncate

file-truncate FILE OFFSET procedure

  Truncates the file FILE to the length OFFSET, which should be an integer. If the file-size is smaller or equal to OFFSET then nothing is done. FILE should be a filename, a file-descriptor or a port object.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### set-file-position!

set-file-position! FILE POSITION #!optional WHENCE procedure
set! (file-position FILE) POSITION procedure

  Sets the current read/write position of FILE to POSITION, which should be an exact integer. FILE should be a port or a file-descriptor. WHENCE specifies how the position is to interpreted and should be one of the values `seek/set, seek/cur` and `seek/end`. It defaults to `seek/set`.

  Exceptions: `(exn bounds)`, `(exn i/o file)`

#### file-creation-mode

file-creation-mode #!optional MODE procedure

  Returns the initial file permissions used for newly created files (as with `umask(2)`). If MODE is supplied, the mode is changed to this value. You can set the mode by executing

       (set! (file-creation-mode) MODE)

  or

       (file-creation-mode MODE)

  where MODE is a bitwise combination of one or more of the `perm/...` flags.

### Hard and symbolic links

#### file-link

file-link OLDNAME NEWNAME procedure

  Creates a hard link from OLDNAME to NEWNAME (both strings).

#### symbolic-link?

symbolic-link? FILE procedure

  Returns true, if FILE names a symbolic link. If no such file exists, `#f` is returned. This operation does not follow symbolic links itself. FILE could be a filename, file descriptor or port object.

#### create-symbolic-link

create-symbolic-link OLDNAME NEWNAME procedure

  Creates a symbolic link with the filename NEWNAME that points to the file named OLDNAME.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### read-symbolic-link

read-symbolic-link FILENAME #!optional CANONICALIZE procedure

  Returns the filename to which the symbolic link FILENAME points. If CANONICALIZE is given and true, then symbolic links are resolved repeatedly until the result is not a link.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

### File descriptors and low-level I/O

#### duplicate-fileno

duplicate-fileno OLD #!optional NEW procedure

  If NEW is given, then the file-descriptor NEW is opened to access the file with the file-descriptor OLD. Otherwise a fresh file-descriptor accessing the same file as OLD is returned.

#### file-close

file-close FILENO procedure

  Closes the input/output file with the file-descriptor FILENO.

#### file-open

file-open FILENAME FLAGS #!optional MODE procedure

  Opens the file specified with the string FILENAME and open-flags FLAGS using the C function `open(2)`. On success a file-descriptor for the opened file is returned.

  FLAGS is a bitmask of `open/...` values ored together using `bitwise-ior` (or simply added together). You must provide exactly one of the access flags `open/rdonly`, `open/wronly`, or `open/rdwr`. Additionally, you may provide zero or more creation flags (`open/creat`, `open/excl`, `open/trunc`, and `open/noctty`) and status flags (the remaining `open/...` values). For example, to open a possibly new output file for appending:

      (file-open "/tmp/hen.txt" (+ open/wronly open/append open/creat))

  The optional MODE should be a bitmask composed of one or more permission values like `perm/irusr` and is only relevant when a new file is created. The default mode is `perm/irwxu | perm/irgrp | perm/iroth`.

#### file-mkstemp

file-mkstemp TEMPLATE-FILENAME procedure

  Create a file based on the given TEMPLATE-FILENAME, in which the six last characters must be XXXXXX. These will be replaced with a string that makes the filename unique. The file descriptor of the created file and the generated filename is returned. See the `mkstemp(3)` manual page for details on how this function works. The template string given is not modified.

  Example usage:

       (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
        (let ((temp-port (open-output-file* fd)))
          (format temp-port "This file is ~A.~%" temp-path)
          (close-output-port temp-port)))

#### file-read

file-read FILENO SIZE #!optional BUFFER procedure

  Reads SIZE bytes from the file with the file-descriptor FILENO. If a string or bytevector is passed in the optional argument BUFFER, then this string will be destructively modified to contain the read data. This procedure returns a list with two values: the buffer containing the data and the number of bytes read.

#### file-select

file-select READFDLIST WRITEFDLIST #!optional TIMEOUT procedure

  Waits until any of the file-descriptors given in the lists READFDLIST and WRITEFDLIST is ready for input or output, respectively. If the optional argument TIMEOUT is given and not false, then it should specify the number of seconds after which the wait is to be aborted (the value may be a float). This procedure returns two values: the lists of file-descriptors ready for input and output, respectively. READFDLIST and WRITEFDLIST may also be file-descriptors instead of lists. In this case the returned values are booleans indicating whether input/output is ready by `#t` or `#f` otherwise. You can also pass `#f` as READFDLIST or WRITEFDLIST argument, which is equivalent to `()`.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-write

file-write FILENO BUFFER #!optional SIZE procedure

  Writes the contents of the string or bytevector BUFFER into the file with the file-descriptor FILENO. If the optional argument SIZE is given, then only the specified number of bytes are written.

#### file-control

file-control FILENO COMMAND #!optional ARGUMENT procedure

  Performs the fcntl operation COMMAND with the given FILENO and optional ARGUMENT. The return value is meaningful depending on the COMMAND.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### open-input-file*

#### open-output-file*

open-input-file* FILENO #!optional OPENMODE procedure
open-output-file* FILENO #!optional OPENMODE procedure

  Opens file for the file-descriptor FILENO for input or output and returns a port. FILENO should be a positive exact integer. OPENMODE specifies an additional mode for opening the file (currently only the keyword `#:append` is supported, which opens an output-file for appending).

#### port->fileno

port->fileno PORT procedure

  If PORT is a file- or tcp-port, then a file-descriptor is returned for this port. Otherwise an error is signaled.

### Record locking

These procedures are all unsupported on native Windows builds (all except cygwin).

#### file-lock

file-lock PORT #!optional START LEN procedure

  Locks the file associated with PORT for reading or writing (according to whether PORT is an input- or output-port). START specifies the starting position in the file to be locked and defaults to 0. LEN specifies the length of the portion to be locked and defaults to `#t`, which means the complete file. `file-lock` returns a lock-object.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-lock/blocking

file-lock/blocking PORT #!optional START LEN procedure

  Similar to `file-lock`, but if a lock is held on the file, the current process blocks (including all threads) until the lock is released.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-test-lock

file-test-lock PORT #!optional START LEN procedure

  Tests whether the file associated with PORT is locked for reading or writing (according to whether PORT is an input- or output-port) and returns either `#f` or the process-id of the locking process.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

#### file-unlock

file-unlock LOCK procedure

  Unlocks the previously locked portion of a file given in LOCK.

  NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.

Previous: Module (chicken file)

Next: Module (chicken fixnum)