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:

[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