Outdated CHICKEN release
This is a manual page for an old and unsupported version of CHICKEN. If you are still using it, please consider migrating to the latest version. You can find the manual for the latest release here.
TOC »
- Outdated CHICKEN release
- Unit posix
- Constants
- Directories
- Pipes
- Fifos
- File descriptors and low-level I/O
- Retrieving file attributes
- Changing file attributes
- Processes
- Hard and symbolic links
- Retrieving user & group information
- Changing user & group information
- Record locking
- Signal handling
- Environment access
- Memory mapped I/O
- Date and time routines
- Raw exit
- ERRNO values
- Finding files
- Getting the hostname and system information
- Setting the file buffering mode
- Terminal ports
- How Scheme procedures relate to UNIX C functions
- Windows specific notes
Unit posix
This unit provides services as used on many UNIX-like systems. Note that the following definitions are not all available on non-UNIX systems like Windows. See below for Windows specific notes.
This unit uses the regex, scheduler, extras and utils units.
All errors related to failing file-operations will signal a condition of kind (exn i/o file).
Constants
File-control Commands
- fcntl/dupfdconstant
- fcntl/getfdconstant
- fcntl/setfdconstant
- fcntl/getflconstant
- fcntl/setflconstant
Operations used with file-control.
Standard I/O file-descriptors
- fileno/stdinconstant
- fileno/stdoutconstant
- fileno/stderrconstant
Standard I/O file descriptor numbers, used with procedures such as open-input-file* which take file descriptors.
Open flags
- open/rdonlyconstant
- open/wronlyconstant
- open/rdwrconstant
- open/readconstant
- open/writeconstant
- open/creatconstant
- open/appendconstant
- open/exclconstant
- open/nocttyconstant
- open/nonblockconstant
- open/truncconstant
- open/syncconstant
- open/fsyncconstant
- open/binaryconstant
- open/textconstant
Open flags used with the file-open procedure. open/read is a convenience synonym for open/rdonly, as is open/write for open/wronly.
Permission bits
- perm/irusrconstant
- perm/iwusrconstant
- perm/ixusrconstant
- perm/irgrpconstant
- perm/iwgrpconstant
- perm/ixgrpconstant
- perm/irothconstant
- perm/iwothconstant
- perm/ixothconstant
- perm/irwxuconstant
- perm/irwxgconstant
- perm/irwxoconstant
- perm/isvtxconstant
- perm/isuidconstant
- perm/isgidconstant
Permission bits used with, for example, file-open.
Directories
change-directory
- change-directory NAMEprocedure
Changes the current working directory to NAME.
change-directory*
- change-directory* FDprocedure
Changes the current working directory to the one represented by the file-descriptor FD, which should be an exact integer.
current-directory
- current-directory #!optional DIRprocedure
Returns the name of the current working directory. If the optional argument DIR is given, then (current-directory DIR) is equivalent to (change-directory DIR).
create-directory
- create-directory NAME #!optional PARENTS?procedure
Creates a directory with the pathname NAME. If the PARENTS? argument is given and not false, any nonexistent parent directories are also created.
Notice that if NAME exists, create-directory won't try to create it and will return NAME (i.e., it won't raise an error when given a NAME that already exists).
delete-directory
- delete-directory NAME #!optional RECURSIVEprocedure
Deletes the directory with the pathname NAME. If RECURSIVE is not given or false, then the directory has to be empty.
directory
- directory #!optional PATHNAME SHOW-DOTFILES?procedure
Returns a list with all files that are contained in the directory with the name PATHNAME (which defaults to the value of (current-directory)). Files beginning with . are included only if SHOW-DOTFILES? is given and not #f.
directory?
- directory? FILEprocedure
Returns #t if FILE designates directory. Otherwise, it returns #f. FILE may be a pathname, a file-descriptor or a port object.
glob
- glob PATTERN1 ...procedure
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).
set-root-directory!
- set-root-directory! STRINGprocedure
Sets the root directory for the current process to the path given in STRING (using the chroot function). If the current process has no root permissions, the operation will fail.
Pipes
call-with-input-pipe
call-with-output-pipe
- call-with-input-pipe CMDLINE PROC #!optional MODEprocedure
- call-with-output-pipe CMDLINE PROC #!optional MODEprocedure
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.
close-input-pipe
close-output-pipe
- close-input-pipe PORTprocedure
- close-output-pipe PORTprocedure
Closes the pipe given in PORT and waits until the connected subprocess finishes. The exit-status code of the invoked process is returned.
create-pipe
- create-pipeprocedure
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.
open-input-pipe
- open-input-pipe CMDLINE #!optional MODEprocedure
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.
open-output-pipe
- open-output-pipe CMDLINE #!optional MODEprocedure
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.
pipe/buf
This variable contains the maximal number of bytes that can be written atomically into a pipe or FIFO.
with-input-from-pipe
with-output-to-pipe
- with-input-from-pipe CMDLINE THUNK #!optional MODEprocedure
- with-output-to-pipe CMDLINE THUNK #!optional MODEprocedure
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 ) ) )
Fifos
create-fifo
- create-fifo FILENAME #!optional MODEprocedure
Creates a FIFO with the name FILENAME and the permission bits MODE, which defaults to
(+ perm/irwxu perm/irwxg perm/irwxo)
fifo?
- fifo? FILEprocedure
Returns #t if FILE names a FIFO. FILE may be a filename, a port or a file-descriptor.
File descriptors and low-level I/O
duplicate-fileno
- duplicate-fileno OLD #!optional NEWprocedure
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 FILENOprocedure
Closes the input/output file with the file-descriptor FILENO.
file-open
- file-open FILENAME FLAGS #!optional MODEprocedure
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-FILENAMEprocedure
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 BUFFERprocedure
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 TIMEOUTprocedure
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 floating point number). 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 ().
file-write
- file-write FILENO BUFFER #!optional SIZEprocedure
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 ARGUMENTprocedure
Performs the fcntl operation COMMAND with the given FILENO and optional ARGUMENT. The return value is meaningful depending on the COMMAND.
open-input-file*
open-output-file*
- open-input-file* FILENO #!optional OPENMODEprocedure
- open-output-file* FILENO #!optional OPENMODEprocedure
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 PORTprocedure
If PORT is a file- or tcp-port, then a file-descriptor is returned for this port. Otherwise an error is signaled.
Retrieving file attributes
file-access-time
file-change-time
file-modification-time
- file-access-time FILEprocedure
- file-change-time FILEprocedure
- file-modification-time FILEprocedure
- set! (file-modification-time FILE) SECONDSprocedure
Returns time (in seconds) of the last access, modification or change of FILE. FILE may be a filename or a file-descriptor. If the file does not exist, an error is signaled.
file-access-time, file-change-time and file-modification-time also accept a port object as their argument.
(set! (file-modification-time FILE) SECONDS) sets the access- and modification time of FILE to SECONDS.
file-stat
- file-stat FILE #!optional LINKprocedure
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 FILEprocedure
Returns the current file position of FILE, which should be a port or a file-descriptor.
file-size
- file-size FILEprocedure
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.
regular-file?
- regular-file? FILEprocedure
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.
file-owner
- file-owner FILEprocedure
Returns the user-id of FILE. FILE may be a filename, a file-descriptor or a port object.
file-permissions
- file-permissions FILEprocedure
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.
file-read-access?
file-write-access?
file-execute-access?
- file-read-access? FILENAMEprocedure
- file-write-access? FILENAMEprocedure
- file-execute-access? FILENAMEprocedure
These procedures return #t if the current user has read, write or execute permissions on the file named FILENAME.
file-type
- file-type FILE #!optional LINK ERRORprocedure
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? FILEprocedure
- block-device? FILEprocedure
- socket? FILEprocedure
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.
Changing file attributes
file-truncate
- file-truncate FILE OFFSETprocedure
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.
set-file-position!
- set-file-position! FILE POSITION #!optional WHENCEprocedure
- set! (file-position FILE) POSITIONprocedure
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)
change-file-mode
- change-file-mode FILENAME MODEprocedure
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.
change-file-owner
- change-file-owner FILENAME UID GIDprocedure
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.
file-creation-mode
- file-creation-mode #!optional MODEprocedure
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.
Processes
current-process-id
- current-process-idprocedure
Returns the process ID of the current process.
parent-process-id
- parent-process-idprocedure
Returns the process ID of the parent of the current process.
process-group-id
- process-group-id PIDprocedure
[setter] (set! (process-group-id PID) PGID)
Get or set the process group ID of the process specified by PID.
process-execute
- process-execute PATHNAME #!optional ARGUMENT-LIST ENVIRONMENT-LISTprocedure
Replaces the running process with a new process image from the program stored at PATHNAME, using the C library function execvp(3). If the optional argument ARGUMENT-LIST is given, then it should contain a list of strings which are passed as arguments to the subprocess. If the optional argument ENVIRONMENT-LIST is supplied, then the library function execve(2) is used, and the environment passed in ENVIRONMENT-LIST (which should be of the form ("<NAME>=<VALUE>" ...) is given to the invoked process. Note that execvp(3) respects the current setting of the PATH environment variable while execve(3) does not.
This procedure never returns; it either replaces the process with a new one or it raises an exception in case something went wrong executing the program.
process-fork
- process-fork #!optional THUNK KILLOTHERS?procedure
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. If THUNK is given and the optional argument KILLOTHERS? is true, then kill all other existing threads in the child process, leaving only the current thread to run THUNK and terminate.
process-run
- process-run COMMANDLINEprocedure
- process-run COMMAND ARGUMENT-LISTprocedure
Creates a new child process. The PID of the new process is returned.
- The single parameter version passes the COMMANDLINE to the system shell, so usual argument expansion can take place.
- The multiple parameter version directly invokes the COMMAND with the ARGUMENT-LIST.
process-signal
- process-signal PID #!optional SIGNALprocedure
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.
process-wait
- process-wait #!optional PID NOHANGprocedure
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.
Note that suspending the current process implies that all threads are suspended as well.
process
- process COMMANDLINEprocedure
- process COMMAND ARGUMENT-LIST #!optional ENVIRONMENT-LISTprocedure
Creates 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. Blocking reads and writes to or from the ports returned by process only block the current thread, not other threads executing concurrently.
Standard error for the subprocess is linked up to the current process's standard error (see process* if you want to reify its standard error into a separate port).
- The single parameter version passes the string COMMANDLINE to the host-system's shell that is invoked as a subprocess.
- The multiple parameter version directly invokes the COMMAND as a subprocess. The ARGUMENT-LIST is directly passed, as is ENVIRONMENT-LIST.
Not using the shell may be preferrable for security reasons.
Once both the input- and output ports are closed, an implicit waitpid(3) is done to wait for the subprocess to finish or to reap a subprocess that has terminated. If the subprocess has not finished, waiting for it will necessarily block all executing threads.
process*
- process* COMMANDLINEprocedure
- process* COMMAND ARGUMENT-LIST #!optional ENVIRONMENT-LISTprocedure
Like process but returns 4 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, the process-id of the started sub-process, and an input port from which data written by the sub-process to stderr can be read.
sleep
- sleep SECONDSprocedure
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.
create-session
- create-sessionprocedure
Creates a new session if the calling process is not a process group leader and returns the session ID.
Hard and symbolic links
symbolic-link?
- symbolic-link? FILEprocedure
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 NEWNAMEprocedure
Creates a symbolic link with the filename NEWNAME that points to the file named OLDNAME.
read-symbolic-link
- read-symbolic-link FILENAME #!optional CANONICALIZEprocedure
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.
file-link
- file-link OLDNAME NEWNAMEprocedure
Creates a hard link from OLDNAME to NEWNAME (both strings).
Retrieving user & group information
current-user-id
- current-user-idprocedure
[setter] (set! (current-user-id) UID)
Get or set the real user-id of the current process. The procedure corresponds to the getuid and setuid C functions.
current-effective-user-id
- current-effective-user-idprocedure
[setter] (set! (current-effective-user-id) UID)
Get or set the effective user-id of the current process.
user-information
- user-information USER #!optional AS-VECTORprocedure
If USER specifes a valid username (as a string) or user ID, then the user database is consulted and a list of 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. When AS-VECTOR is #t a vector of 7 elements is returned instead of a list. If no user with this name or id then #f is returned.
Note: on Android systems, the user-specific string is always "", since pw_gecos is not available in the C passwd struct on that platform.
current-group-id
- current-group-idprocedure
[setter] (set! (current-group-id) GID)
Get or set the real group-id of the current process.
current-effective-group-id
- current-effective-group-idprocedure
[setter] (set! (current-effective-group-id) GID)
Get or set the effective group-id of the current process. ID can be found, then #f is returned.
group-information
- group-information GROUPprocedure
If GROUP specifies a valid group-name or group-id, then this procedure returns a list of 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.
get-groups
- get-groupsprocedure
Returns a list with the supplementary group IDs of the current user.
Changing user & group information
set-groups!
- set-groups! GIDLISTprocedure
Sets the supplementrary group IDs of the current user to the IDs given in the list GIDLIST.
Only the superuser may invoke this procedure.
initialize-groups
- initialize-groups USERNAME BASEGIDprocedure
Sets the supplementrary group IDs of the current user to the IDs from the user with name USERNAME (a string), including BASEGID.
Only the superuser may invoke this procedure.
Record locking
file-lock
- file-lock PORT #!optional START LENprocedure
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.
file-lock/blocking
- file-lock/blocking PORT #!optional START LENprocedure
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.
file-test-lock
- file-test-lock PORT #!optional START LENprocedure
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.
file-unlock
- file-unlock LOCKprocedure
Unlocks the previously locked portion of a file given in LOCK.
Signal handling
set-alarm!
- set-alarm! SECONDSprocedure
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.
set-signal-handler!
signal-handler
- signal-handler SIGNUMprocedure
Returns the signal handler for the code SIGNUM or #f.
- set-signal-handler! SIGNUM PROCprocedure
Establishes the procedure of one argument PROC as the handler for the signal with the code SIGNUM. PROC is called with the signal number as its sole argument. If the argument PROC is #f then any signal handler will be removed, and the corresponding signal set to SIG_IGN.
Notes
- it is unspecified in which thread of execution the signal handler will be invoked.
- when signals arrive in quick succession (specifically, before the handler for a signal has been started), then signals will be queued (up to a certain limit); the order in which the queued signals will be handled is not specified
- (set! (signal-handler SIG) PROC) can be used as an alternative to (set-signal-handler! SIG PROC)
- Any signal handlers for the signals signal/segv, signal/bus, signal/fpe and signal/ill will be ignored and these signals will always trigger an exception, unless the executable was started with the -:S runtime option. This feature is only available on platforms that support the sigprocmask(3) POSIX API function.
set-signal-mask!
- set-signal-mask! SIGLISTprocedure
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-mask
- signal-maskprocedure
Returns the signal mask of the current process.
signal-masked?
- signal-masked? SIGNUMprocedure
Returns whether the signal for the code SIGNUM is currently masked.
signal-mask!
- signal-mask! SIGNUMprocedure
Masks (blocks) the signal for the code SIGNUM.
signal-unmask!
- signal-unmask! SIGNUMprocedure
Unmasks (unblocks) the signal for the code SIGNUM.
Signal codes
- signal/termconstant
- signal/killconstant
- signal/intconstant
- signal/hupconstant
- signal/fpeconstant
- signal/illconstant
- signal/segvconstant
- signal/abrtconstant
- signal/trapconstant
- signal/quitconstant
- signal/alrmconstant
- signal/vtalrmconstant
- signal/profconstant
- signal/ioconstant
- signal/urgconstant
- signal/chldconstant
- signal/contconstant
- signal/stopconstant
- signal/tstpconstant
- signal/pipeconstant
- signal/xcpuconstant
- signal/xfszconstant
- signal/usr1constant
- signal/usr2constant
- signal/busconstant
- signal/winchconstant
- signal/breakconstant
These variables contain signal codes for use with process-signal, set-signal-handler!, signal-handler, signal-masked?, signal-mask!, or signal-unmask!.
Environment access
get-environment-variables
- get-environment-variablesprocedure
Returns a association list of the environment variables and their current values (see also SRFI-98).
setenv
- setenv VARIABLE VALUEprocedure
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.
unsetenv
- unsetenv VARIABLEprocedure
Removes the definition of the environment variable VARIABLE from the environment of the current process. If the variable is not defined, nothing happens.
Memory mapped I/O
Memory mapped I/O takes the contents of a file descriptor and places them in memory.
memory-mapped-file?
- memory-mapped-file? Xprocedure
Returns #t, if X is an object representing a memory mapped file, or #f otherwise.
map-file-to-memory
- map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO #!optional OFFSETprocedure
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.
memory-mapped-file-pointer
- memory-mapped-file-pointer MMAPprocedure
Returns a machine pointer to the start of the memory region to which the file is mapped.
unmap-file-from-memory
- unmap-file-from-memory MMAP #!optional LENprocedure
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.
Memory Mapped I/O Example
;; example-mmap.scm ;; ;; basic example of memory mapped I/O ;; ;; This example does no error checking or cleanup, and serves ;; only to demonstrate how the mmap functions work together. ;; (use posix) (use lolevel) ; open a file using the posix module, so we have the file descriptor. (let* ((fd (file-open "example-mmap.scm" (+ open/rdonly open/nonblock))) ; fstat(2) the file descriptor fd to determine its size (size (file-size fd)) ; mmap(2) the file for reading. (mmap (map-file-to-memory #f size prot/read (+ map/file map/shared) fd)) ; return a pointer object to the beginning of the memory map. (buf (memory-mapped-file-pointer mmap)) ; allocate a string the same size as the file. (str (make-string size))) ; copy the mapped memory into a string (move-memory! buf str size) (display str) ; alternately, print the string byte-by-byte without copying. (let loop ((p buf) (i 0)) (unless (= i size) (display (integer->char (pointer-s8-ref p))) (loop (pointer+ p 1) (+ i 1)))))
Date and time routines
seconds->local-time
- seconds->local-time #!optional SECONDSprocedure
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 (0)
- the number of seconds after the minute (0 - 59)
- minutes (1)
- the number of minutes after the hour (0 - 59)
- hours (2)
- the number of hours past midnight (0 - 23)
- mday (3)
- the day of the month (1 - 31)
- month (4)
- the number of months since january (0 - 11)
- year (5)
- the number of years since 1900
- wday (6)
- the number of days since Sunday (0 - 6)
- yday (7)
- the number of days since January 1 (0 - 365)
- dstflag (8)
- a flag that is true if Daylight Saving Time is in effect at the time described.
- timezone (9)
- the difference between UTC and the latest local standard time, in seconds west of UTC.
SECONDS defaults to the value of (current-seconds).
local-time->seconds
- local-time->seconds VECTORprocedure
Converts the ten-element vector VECTOR representing the time value relative to the current timezone into the number of seconds since the first of January, 1970 UTC.
local-timezone-abbreviation
- local-timezone-abbreviationprocedure
Returns the abbreviation for the local timezone as a string.
seconds->string
- seconds->string #!optional SECONDSprocedure
Converts the time represented in SECONDS into a local-time string of the form "Tue May 21 13:46:22 1991". SECONDS defaults to the value of (current-seconds).
seconds->utc-time
- seconds->utc-time #!optional SECONDSprocedure
Similar to seconds->local-time, but interpretes SECONDS as UTC time. SECONDS defaults to the value of (current-seconds).
utc-time->seconds
- utc-time->seconds VECTORprocedure
Converts the ten-element vector VECTOR representing the UTC time value into the number of seconds since the first of January, 1970 UTC.
time->string
- time->string VECTOR #!optional FORMATprocedure
Converts the broken down time represented in the 10 element vector VECTOR into a string of the form represented by the FORMAT string. The default time form produces something like "Tue May 21 13:46:22 1991".
The FORMAT string follows the rules for the C library procedure strftime. The default FORMAT string is "%a %b %e %H:%M:%S %Z %Y".
string->time
- string->time TIME #!optional FORMATprocedure
Converts a string of the form represented by the FORMAT string into the broken down time represented in a 10 element vector. The default time form understands something like "Tue May 21 13:46:22 1991".
The FORMAT string follows the rules for the C library procedure strptime. The default FORMAT string is "%a %b %e %H:%M:%S %Z %Y".
Raw exit
_exit
- _exit #!optional CODEprocedure
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.
ERRNO values
- errno/permconstant
- errno/noentconstant
- errno/srchconstant
- errno/intrconstant
- errno/ioconstant
- errno/noexecconstant
- errno/badfconstant
- errno/childconstant
- errno/nomemconstant
- errno/accesconstant
- errno/faultconstant
- errno/busyconstant
- errno/notdirconstant
- errno/isdirconstant
- errno/invalconstant
- errno/mfileconstant
- errno/nospcconstant
- errno/spipeconstant
- errno/pipeconstant
- errno/againconstant
- errno/rofsconstant
- errno/existconstant
- errno/wouldblockconstant
These variables contain error codes as returned by errno.
Finding files
find-files
- find-files DIRECTORY #!key test action seed limit dotfiles follow-symlinksprocedure
Recursively traverses the contents of DIRECTORY (which should be a string) and invokes the procedure action for all files in which the procedure test is true.
test may be a procedure of one argument or an irregex object, regex string or SRE expression that will be matched with a full pathname using irregex-match. test defaults to (constantly #t).
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 seed. action defaults to cons, seed defaults to ().
limit should be 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. For example, a depth of 0 means that only files in the top-level, specified directory are to be traversed. In this case, all nested directories are ignored. limit may also be #f (the default), which is equivalent to (constantly #t).
If dotfiles is given and true, then files starting with a "." character will not be ignored (but note that "." and ".." are always ignored). if follow-symlinks is given and true, then the traversal of a symbolic link that points to a directory will recursively traverse the latter. By default, symbolic links are not followed.
Note that action is called with the full pathname of each file, including the directory prefix.
This procedure's signature was changed in CHICKEN 4.6. In older versions, find-files has a different signature:
(find-files DIRECTORY [TEST [ACTION [SEED [LIMIT]]]])
The old signature was supported until CHICKEN 4.7.3 for compatibility reasons, at which point it became invalid. The optional arguments are ignored and use their default values, and no warning is issued. One symptom is that your TEST does not work, returning every file.
Getting the hostname and system information
get-host-name
- get-host-nameprocedure
Returns the hostname of the machine that this process is running on.
system-information
- system-informationprocedure
Invokes the UNIX system call uname() and returns a list of 5 values: system-name, node-name, OS release, OS version and machine.
Setting the file buffering mode
set-buffering-mode!
- set-buffering-mode! PORT MODE #!optional BUFSIZEprocedure
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).
Terminal ports
terminal-name
- terminal-name PORTprocedure
Returns the name of the terminal that is connected to PORT.
terminal-port?
- terminal-port? PORTprocedure
Returns #t if PORT is connected to a terminal and #f otherwise.
terminal-size
- terminal-size PORTprocedure
Returns two values, the number of columns and rows of the terminal that is connected to PORT or 0, 0 if the terminal size can not be obtained. On Windows, this procedure always returns 0, 0.
How Scheme procedures relate to UNIX C functions
- change-directory
- chdir
- change-directory*
- fchdir
- change-file-mode
- chmod
- change-file-owner
- chown
- create-directory
- mkdir
- create-fifo
- mkfifo
- create-pipe
- pipe
- create-session
- setsid
- create-symbolic-link
- link
- current-directory
- curdir
- current-effective-group-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-access-time
- stat
- file-change-time
- stat
- file-creation-mode
- umask
- file-modification-time
- stat
- 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-control
- fcntl
- file-stat
- stat
- file-test-lock
- fcntl
- file-truncate
- truncate/ftruncate
- file-unlock
- fcntl
- file-write
- write
- file-write-access?
- access
- get-groups
- getgroups
- get-host-name
- gethostname
- initialize-groups
- initgroups
- local-time->seconds
- mktime
- local-timezone-abbreviation
- localtime
- 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-group-id
- getpgid
- 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-groups!
- setgroups
- set-signal-mask!
- sigprocmask
- set-group-id!
- setgid
- set-user-id!
- setuid
- set-root-directory!
- chroot
- 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
- utc-time->seconds
- timegm
Windows specific notes
Use of UTF8 encoded strings is for pathnames is not supported. Windows uses a 16-bit UNICODE encoding with special system calls for wide-character support. Only single-byte string encoding can be used.
Procedure Changes
Exceptions to the above procedure definitions.
- create-pipe #!optional MODEprocedure
The optional parameter MODE, default open/binary | open/noinherit. This can be open/binary or open/text, optionally or'ed with open/noinherit.
- process-wait #!optional PID NOHANGprocedure
process-wait always returns #t for a terminated process and only the exit status is available. (Windows does not provide signals as an interprocess communication method.)
- process-execute PATHNAME #!optional ARGUMENT-LIST ENVIRONMENT-LIST EXACT-FLAGprocedure
- process COMMAND ARGUMENT-LIST #!optional ENVIRONMENT-LIST EXACT-FLAGprocedure
- process* COMMAND ARGUMENT-LIST #!optional ENVIRONMENT-LIST EXACT-FLAGprocedure
The optional parameter EXACT-FLAG, default #f. When #f any argument string with embedded whitespace will be wrapped in quotes. When #t no such wrapping occurs.
Unsupported Definitions
The following definitions are not supported for native Windows builds (compiled with the Microsoft tools or with MinGW):
open/noctty open/nonblock open/fsync open/sync perm/isvtx perm/isuid perm/isgid file-select file-control signal/... (except signal/term, signal/int, signal/fpe, signal/ill, signal/segv, signal/abrt, signal/break) set-signal-mask! signal-mask signal-masked? signal-mask! signal-unmask! user-information group-information get-groups set-groups! initialize-groups errno/wouldblock change-directory* change-file-owner current-user-id current-group-id current-effective-user-id current-effective-group-id set-user-id! set-group-id! create-session process-group-id create-symbolic-link read-symbolic-link file-truncate file-lock file-lock/blocking file-unlock file-test-lock create-fifo fifo? set-alarm! terminal-port? terminal-name process-fork process-signal parent-process-id set-root-directory! utc-time->seconds
Additional Definitions
Only available for Windows
- open/noinherit
This variable is a mode value for create-pipe. Useful when spawning a child process.
- spawn/overlay
- spawn/wait
- spawn/nowait
- spawn/nowaito
- spawn/detach
These variables contains special flags that specify the exact semantics of process-spawn: spawn/overlay replaces the current process with the new one. spawn/wait suspends execution of the current process until the spawned process returns. spawn/nowait does the opposite (spawn/nowaito is identical, according to the Microsoft documentation) and runs the process asynchronously. spawn/detach runs the new process in the background, without being attached to a console.
process-spawn
- process-spawn MODE COMMAND #!optional ARGUMENT-LIST ENVIRONMENT-LIST EXACT-FLAGprocedure
Creates and runs a new process with the given COMMAND filename and the optional ARGUMENT-LIST and ENVIRONMENT-LIST. MODE specifies how exactly the process should be executed and must be one or more of the spawn/... flags defined above.
The EXACT-FLAG, default #f, controls quote-wrapping of argument strings. When #t quote-wrapping is not performed.
Returns:
- the exit status when synchronous
- the PID when asynchronous
- -1 when failure
Previous: Unit srfi-69
Next: Unit utils