## 5.20 Unit: posix

This unit provides services as used on many UNIX-like systems. Note that the following definitions are not available on non-UNIX systems like Windows or DOS.

This unit uses the `regex` and `extras` units.

### 5.20.1 Directories

[procedure] (change-directory NAME)
  Changes the current working directory to `NAME`.

[procedure] (current-directory)
  Returns the name of the current working directory.

[procedure] (create-directory NAME)
  Creates a directory with the pathname `NAME`.

[procedure] (delete-directory NAME)
  Deletes the directory with the pathname `NAME`. The directory has to be empty.

[procedure] (directory PATHNAME)
  Returns a list with all files that are contained in the directory with the name `PATHNAME`.

[procedure] (directory? NAME)
  Returns `#t` if there exists a file with the name `NAME` and if that file is a directory, or `#f` otherwise.

[procedure] (glob PATTERN1 ...)
  Returns a list of the pathnames of all existing files matching `PATTERN1 ...`, which should be strings containing the usual file-patterns (with `*` matching zero or more characters and `?` matching zero or one character).

### 5.20.2 Pipes

[procedure] (call-with-input-pipe CMDLINE PROC [MODE])
[procedure] (call-with-output-pipe CMDLINE PROC [MODE])
  Call `PROC` with a single argument: a input- or output port for a pipe connected to the subprocess named in `CMDLINE`. If `PROC` returns normally, the pipe is closed and any result values are returned.

[procedure] (close-input-pipe PORT)
[procedure] (close-output-pipe PORT)
  Closes the pipe given in `PORT` and waits until the connected subprocess finishes.

[procedure] (create-pipe)
  The fundamental pipe-creation operator. Calls the C function `pipe()` and returns 2 values: the file-descriptors of the input- and output-ends of the pipe.

[procedure] (open-input-pipe CMDLINE [MODE])
  Spawns a subprocess with the command-line string `CMDLINE` and returns a port, from which the output of the process can be read. If `MODE` is specified, it should be the keyword `#:text` (the default) or `#:binary`.

[procedure] (open-output-pipe CMDLINE [MODE])
  Spawns a subprocess with the command-line string `CMDLINE` and returns a port. Anything written to that port is treated as the input for the process. If `MODE` is specified, it should be the keyword `#:text` (the default) or `#:binary`.

[limit] pipe/buf
  This variable contains the maximal number of bytes that can be written atomically into a pipe or FIFO.

[procedure] (with-input-from-pipe CMDLINE THUNK [MODE])
[procedure] (with-output-to-pipe CMDLINE THUNK [MODE])
  Temporarily set the value of `current-input-port/current-output-port` to a port for a pipe connected to the subprocess named in `CMDLINE` and call the procedure `THUNK` with no arguments. After `THUNK` returns normally the pipe is closed and the standard input-/output port is restored to its previous value and any result values are returned.

      (with-output-to-pipe
        "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
        (lambda ()
          (print #<<EOF
      %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
      /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
      H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
      X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
      F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
      Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
      ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
      V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g{[}{]}J}J
      cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
      EOF
      ) ) )

### 5.20.3 Fifos

[procedure] (create-fifo FILENAME [MODE])
  Creates a FIFO with the name `FILENAME` and the permission bits `MODE`, which defaults to

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

[procedure] (fifo? FILENAME)
  Returns `#t` if the file with the name `FILENAME` names a FIFO.

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

[procedure] (duplicate-fileno OLD [NEW])
  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.

[procedure] (file-close FILENO)
  Closes the input/output file with the file-descriptor `FILENO`.

[procedure] (file-open FILENAME FLAGS [MODE])
  Opens the file specified with the string `FILENAME` and open-flags `FLAGS` using the C function `open()`. On success a file-descriptor for the opened file is returned. `FLAGS` should be a bitmask containing one or more of the `open/...` values ored together using `bitwise-ior` (or simply added together). 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`.

[procedure] (file-read FILENO SIZE [BUFFER])
  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.

[procedure] (file-select READFDLIST WRITEFDLIST [TIMEOUT])
  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. This procedure returns two values: the lists of file-descriptors ready for input and output, respectively. `READFDLIST` and WRITEFDLIST may also by 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 `()`.

[procedure] (file-write FILENO BUFFER [SIZE])
  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 descriptor] fileno/stdin
[file descriptor] fileno/stdout
[file descriptor] fileno/stderr
  These variables contain file-descriptors for the standard I/O files.

[flag] open/rdonly
[flag] open/wronly
[flag] open/rdwr
[flag] open/read
[flag] open/write
[flag] open/creat
[flag] open/append
[flag] open/excl
[flag] open/noctty
[flag] open/nonblock
[flag] open/trunc
[flag] open/sync
[flag] open/fsync
[flag] open/binary
[flag] open/text
  Flags for use with `file-open`.

[procedure] (open-input-file* FILENO [OPENMODE])
[procedure] (open-output-file* FILENO [OPENMODE])
  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).

[procedure] (port`->`fileno PORT)
  If `PORT` is a file-port, then a file-descriptor is returned for this port. Otherwise an error is signaled.

### 5.20.5 Retrieving file attributes

[procedure] (file-modification-time FILE)
  Returns time of last modification of `FILE`. `FILE` may be a filename or a file-descriptor. If the file does not exist, an error is signaled.

[procedure] (file-position FILE)
  Returns the current file position of `FILE`, which should be a port or a file-descriptor.

[procedure] (file-size FILENAME)
  Returns the size of the file designated by `FILE`. `FILE` may be a filename or a file-descriptor. If the file does not exist, an error is signaled.

### 5.20.6 Changing file attributes

[procedure] (file-truncate FILE OFFSET)
  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 or a file-descriptor.

[procedure] (set-file-position! FILE POSITION [WHENCE])
  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`.

### 5.20.7 Processes

[procedure] (current-process-id)
  Returns the process ID of the current process.

[procedure] (parent-process-id)
  Returns the process ID of the parent of the current process.

[procedure] (process-execute PATHNAME [LIST])
  Creates a new child process and replaces the running process with it using the UNIX system call `execv()`. If the optional argument `LIST` is given, then it should contain a list of strings which are passed as arguments to the subprocess.

[procedure] (process-fork [THUNK])
  Creates a new child process with the UNIX system call `fork()`. Returns either the PID of the child process or 0. If `THUNK` is given, then the child process calls it as a procedure with no arguments and terminates.

[procedure] (process-run PATHNAME [LIST])
  Creates a new child process using the UNIX system call `fork()` that executes the program given by the string `PATHNAME` using the UNIX system call `execv()`. The PID of the new process is returned. If `LIST` is not specified, then `PATHNAME` is passed to a program named by the environment variable `SHELL` (or `/bin/sh`, if the variable is not defined), so usual argument expansion can take place.

[procedure] (process-signal PID [SIGNAL])
  Sends `SIGNAL` to the process with the id `PID` using the UNIX system call `kill()`. `SIGNAL` defaults to the value of the variable `signal/term`.

[procedure] (process-wait [PID [NOHANG]])
  Suspends the current process until the child process with the id `PID` has terminated using the UNIX system call `waitpid()`. If `PID` is not given, then this procedure waits for any child process. If `NOHANG` is given and not `#f` then the current process is not suspended. This procedure returns three values:

  `PID` or 0, if `NOHANG` is true and the child process has not terminated yet;

  `#t` if the process exited normally or `#f` otherwise;

  either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.

[procedure] (process COMMANDLINE)
  Passes the string `COMMANDLINE` to the host-system's shell that is invoked as a subprocess and returns three values: an input port from which data written by the sub-process can be read, an output port from which any data written to will be received as input in the sub-process and the process-id of the started sub-process. All I/O from/to ports returned by `process` is fully nonblocking.

[procedure] (sleep SECONDS)
  Puts the process to sleep for `SECONDS`. Returns either 0 if the time has completely elapsed, or the number of remaining seconds, if a signal occurred.

### 5.20.8 Symbolic links

[procedure] (create-symbolic-link OLDNAME NEWNAME)
  Creates a symbolic link with the filename `NEWNAME` that points to the file named `OLDNAME`.

[procedure] (read-symbolic-link FILENAME)
  Returns the filename to which the symbolic link `FILENAME` points.

### 5.20.9 Permissions, owners, users and groups

[procedure] (file-owner FILE)
  Returns the user-id of `FILE`. `FILE` may be a filename or a file-descriptor.

[procedure] (file-permissions FILE)
  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 or a file-descriptor.

[procedure] (file-read-access? FILENAME)
[procedure] (file-write-access? FILENAME)
[procedure] (file-execute-access? FILENAME)
  These procedures return `#t` if the current user has read, write or execute permissions on the file named `FILENAME`.

[procedure] (change-file-mode FILENAME MODE)
  Changes the current file mode of the file named `FILENAME` to `MODE` using the `chmod()` system call. The `perm/...` variables contain the various permission bits and can be combinded with the `bitwise-ior` procedure.

[procedure] (change-file-owner FILENAME UID GID)
  Changes the owner information of the file named `FILENAME` to the user- and group-ids `UID` and `GID` (which should be exact integers) using the `chown()` system call.

[procedure] (current-user-id)
[procedure] (current-group-id)
[procedure] (current-effective-user-id)
[procedure] (current-effective-group-id)
  Return the user- and group-ids of the current process.

[procedure] (group-information GROUP)
  If `GROUP` specifies a valid group-name or group-id, then this procedure returns four values: the group-name, the encrypted group password, the group ID and a list of the names of all group members. If no group with the given name or ID exists, then `#f` is returned.

[permission bits] perm/irusr
[permission bits] perm/iwusr
[permission bits] perm/ixusr
[permission bits] perm/irgrp
[permission bits] perm/iwgrp
[permission bits] perm/ixgrp
[permission bits] perm/iroth
[permission bits] perm/iwoth
[permission bits] perm/ixoth
[permission bits] perm/irwxu
[permission bits] perm/irwxg
[permission bits] perm/irwxo
[permission bits] perm/isvtx
[permission bits] perm/isuid
[permission bits] perm/isgid
  These variables contain permission bits as used in `change-file-mode`.

[procedure] (set-user-id! UID)
  Sets the effective user id of the current process to `UID`, which should be a positive integer.

[procedure] (user-information USER)
  If `USER` specifes a valid username (as a string) or user ID, then the user database is consulted and 7 values are returned: the user-name, the encrypted password, the user ID, the group ID, a user-specific string, the home directory and the default shell. If no user with this name or ID can be found, then `#f` is returned.

### 5.20.10 Record locking

[procedure] (file-lock PORT [START [LEN]])
  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.

[procedure] (file-lock/blocking PORT [START [LEN]])
  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.

[procedure] (file-test-lock PORT [START [LEN]])
  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.

[procedure] (file-unlock LOCK)
  Unlocks the previously locked portion of a file given in `LOCK`.

### 5.20.11 Signal handling

[procedure] (set-alarm! SECONDS)
  Sets an internal timer to raise the `signal/alrm` after `SECONDS` are elapsed. You can use the `set-signal-handler!` procedure to write a handler for this signal.

[procedure] (set-signal-handler! SIGNUM PROC)
  Establishes the procedure of one argument `PROC` as the handler for the signal with the code `SIGNAL`. `PROC` is called with the signal number as its sole argument. If the argument `PROC` is `#f` then this signal will be ignored.

[procedure] (set-signal-mask! SIGLIST)
  Sets the signal mask of the current process to block all signals given in the list `SIGLIST`. Signals masked in that way will not be delivered to the current process.

[signal code] signal/term
[signal code] signal/kill
[signal code] signal/int
[signal code] signal/hup
[signal code] signal/fpe
[signal code] signal/ill
[signal code] signal/segv
[signal code] signal/abrt
[signal code] signal/trap
[signal code] signal/quit
[signal code] signal/alrm
[signal code] signal/vtalrm
[signal code] signal/prof
[signal code] signal/io
[signal code] signal/urg
[signal code] signal/chld
[signal code] signal/cont
[signal code] signal/stop
[signal code] signal/tstp
[signal code] signal/pipe
[signal code] signal/xcpu
[signal code] signal/xfsz
[signal code] signal/usr1
[signal code] signal/usr2
[signal code] signal/winch
  These variables contain signal codes for use with `process-signal` or `set-signal-handler!`.

### 5.20.12 Environment access

[procedure] (current-environment)
  Returns a association list of the environment variables and their current values.

  Note: Under Mac OS X, this procedure always returns the empty list.

[procedure] (setenv VARIABLE VALUE)
  Sets the environment variable named `VARIABLE` to `VALUE`. Both arguments should be strings. If the variable is not defined in the environment, a new definition is created.

[procedure] (unsetenv VARIABLE)
  Removes the definition of the environment variable `VARIABLE` from the environment of the current process. If the variable is not defined, nothing happens.

### 5.20.13 Memory mapped I/O

[procedure] (map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])
  Maps a section of a file to memory using the C function `mmap()`. `ADDRESS` should be a foreign pointer object or `#f`; `LEN` specifies the size of the section to be mapped; `PROTECTION` should be one or more of the flags `prot/read, prot/write, prot/exec` or `prot/none` bitwise-iored together; `FLAG` should be one or more of the flags `map/fixed, map/shared, map/private, map/anonymous` or `map/file`; `FILENO` should be the file-descriptor of the mapped file. The optional argument `OFFSET` gives the offset of the section of the file to be mapped and defaults to 0. This procedure returns an object representing the mapped file section. The procedure `move-memory!` can be used to access the mapped memory.

[procedure] (memory-mapped-file-pointer MMAP)
  Returns a machine pointer to the start of the memory region to which the file is mapped.

[procedure] (unmap-file-from-memory MMAP [LEN])
  Unmaps the section of a file mapped to memory using the C function `munmap()`. `MMAP` should be a mapped file as returned by the procedure `map-file-to-memory`. The optional argument `LEN` specifies the length of the section to be unmapped and defaults to the complete length given when the file was mapped.

### 5.20.14 Time routines

[procedure] (seconds`->`local-time SECONDS)
  Breaks down the time value represented in `SECONDS` into a 10 element vector of the form `#(seconds minutes hours mday month year wday yday dstflag timezone)`, in the following format:

  - seconds: the number of seconds after the minute (0 - 59)

  - minutes: the number of minutes after the hour (0 - 59)

  - hours: the number of hours past midnight (0 - 23)

  - mday: the day of the month (1 - 31)

  - month: the number of months since january (0 - 11)

  - year: the number of years since 1900

  - wday: the number of days since Sunday (0 - 6)

  - yday: the number of days since January 1 (0 - 365)

  - dstflag: a flag that is true if Daylight Saving Time is in effect at the time described.

  - timezone: the difference between UTC and the latest local standard time, in seconds west of UTC.

[procedure] (seconds`->`string SECONDS)
  Converts the local time represented in `SECONDS` into a string of the form `"Tue May 21 13:46:22 1991n"`.

[procedure] (seconds`->`utc-time SECONDS)
  Similar to `seconds`->`local-time`, but interpretes `SECONDS` as local time.

[procedure] (time`->`string VECTOR)
  Converts the broken down time represented in the 10 element vector `VECTOR` into a string of the form `"Tue May 21 13:46:22 1991n"`.

### 5.20.15 Miscellaneous routines

[procedure] (_exit [CODE])
  Exits the current process without flushing any buffered output (using the C function `_exit`). Note that the `exit-handler` is not called when this procedure is invoked. The optional return-code `CODE` defaults to `0`.

[error code] errno/perm
[error code] errno/noent
[error code] errno/srch
[error code] errno/intr
[error code] errno/io
[error code] errno/noexec
[error code] errno/badf
[error code] errno/child
[error code] errno/nomem
[error code] errno/acces
[error code] errno/fault
[error code] errno/busy
[error code] errno/notdir
[error code] errno/isdir
[error code] errno/inval
[error code] errno/mfile
[error code] errno/nospc
[error code] errno/spipe
[error code] errno/pipe
[error code] errno/again
[error code] errno/rofs
[error code] errno/wouldblock
  These variables contain error codes as returned by `errno`.

[procedure] (find-files DIRECTORY PREDICATE [ACTION [IDENTITY [LIMIT]]])
  Recursively traverses the contents of `DIRECTORY` (which should be a string) and invokes the procedure `ACTION` for all files for which the procedure `PREDICATE` is true. `PREDICATE` may me a procedure of one argument or a regular-expression string. `ACTION` should be a procedure of two arguments: the currently encountered file and the result of the previous invocation of `ACTION`, or, if this is the first invocation, the value of `IDENTITY`. `ACTION` defaults to `cons`, `IDENTITY` defaults to `()`. `LIMIT` should a procedure of one argument that is called for each nested directory and which should return true, if that directory is to be traversed recursively. `LIMIT` may also be an exact integer that gives the maximum recursion depth. A depth of `0` means the files in the specified directory are traversed but not any nested directories. `LIMIT` may also be `#f` (the default), which is equivalent to `(constantly #t)`.

  Note that `ACTION` is called with the full pathname of each file, including the directory prefix.

[procedure] (get-host-name)
  Returns the hostname of the machine that this process is running on.

[procedure] (set-buffering-mode! PORT MODE [BUFSIZE])
  Sets the buffering-mode for the file associated with `PORT` to `MODE`, which should be one of the keywords `#:full, #:line` or `#:none`. If `BUFSIZE` is specified it determines the size of the buffer to be used (if any).

[procedure] (terminal-name PORT)
  Returns the name of the terminal that is connected to `PORT`.

[procedure] (terminal-port? PORT)
  Returns `#t` if `PORT` is connected to a terminal and `#f` otherwise.

[procedure] (system-information)
  Invokes the UNIX system call `uname()` and returns 5 values: system-name, node-name, OS release, OS version and machine.

### 5.20.16 How Scheme procedures relate to UNIX C functions

``

change-directory | chdir
change-file-mode | chmod
change-file-owner | chown
create-directory | mkdir
create-fifo | mkfifo
create-pipe | pipe
create-symbolic-link | link
current-directory | curdir
current-effective-groupd-id | getegid
current-effective-user-id | geteuid
current-group-id | getgid
current-parent-id | getppid
current-process-id | getpid
current-user-id | getuid
delete-directory | rmdir
duplicate-fileno | dup/dup2
_exit | _exit
file-close | close
file-execute-access? | access
file-open | open
file-lock | fcntl
file-position | ftell/lseek
file-read | read
file-read-access? | access
file-select | select
file-test-lock | fcntl
file-truncate | truncate/ftruncate
file-unlock | fcntl
file-write | write
file-write-access? | access
get-host-name | gethostname
map-file-to-memory | mmap
open-input-file* | fdopen
open-output-file* | fdopen
open-input-pipe | popen
open-output-pipe | popen
port->fileno | fileno
process-execute | execvp
process-fork | fork
process-signal | kill
process-wait | waitpid
close-input-pipe | pclose
close-output-pipe | pclose
read-symbolic-link | readlink
seconds->local-time | localtime
seconds->string | ctime
seconds->utc-time | gmtime
set-alarm! | alarm
set-buffering-mode! | setvbuf
set-file-position! | fseek/seek
set-signal-mask! | sigprocmask
set-user-id! | setuid
setenv | setenv/putenv
sleep | sleep
system-information | uname
terminal-name | ttyname
terminal-port? | isatty
time->string | asctime
unsetenv | putenv
unmap-file-from-memory | munmap
user-information | getpwnam/getpwuid