diff options
Diffstat (limited to 'doc/ref/posix.texi')
-rw-r--r-- | doc/ref/posix.texi | 3624 |
1 files changed, 3624 insertions, 0 deletions
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi new file mode 100644 index 000000000..5cb68a292 --- /dev/null +++ b/doc/ref/posix.texi @@ -0,0 +1,3624 @@ +@c -*-texinfo-*- +@c This is part of the GNU Guile Reference Manual. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, +@c 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2017 Free Software Foundation, Inc. +@c See the file guile.texi for copying conditions. + +@node POSIX +@section @acronym{POSIX} System Calls and Networking +@cindex POSIX + +@menu +* Conventions:: Conventions employed by the POSIX interface. +* Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors + have different representations. +* File System:: stat, chown, chmod, etc. +* User Information:: Retrieving a user's GECOS (/etc/passwd) entry. +* Time:: gettimeofday, localtime, strftime, etc. +* Runtime Environment:: Accessing and modifying Guile's environment. +* Processes:: getuid, getpid, etc. +* Signals:: sigaction, kill, pause, alarm, setitimer, etc. +* Terminals and Ptys:: ttyname, tcsetpgrp, etc. +* Pipes:: Communicating data between processes. +* Networking:: gethostbyaddr, getnetent, socket, bind, listen. +* System Identification:: Obtaining information about the system. +* Locales:: setlocale, etc. +* Encryption:: +@end menu + +@node Conventions +@subsection @acronym{POSIX} Interface Conventions + +These interfaces provide access to operating system facilities. +They provide a simple wrapping around the underlying C interfaces +to make usage from Scheme more convenient. They are also used +to implement the Guile port of scsh (@pxref{The Scheme shell (scsh)}). + +Generally there is a single procedure for each corresponding Unix +facility. There are some exceptions, such as procedures implemented for +speed and convenience in Scheme with no primitive Unix equivalent, +e.g.@: @code{copy-file}. + +The interfaces are intended as far as possible to be portable across +different versions of Unix. In some cases procedures which can't be +implemented on particular systems may become no-ops, or perform limited +actions. In other cases they may throw errors. + +General naming conventions are as follows: + +@itemize @bullet +@item +The Scheme name is often identical to the name of the underlying Unix +facility. +@item +Underscores in Unix procedure names are converted to hyphens. +@item +Procedures which destructively modify Scheme data have exclamation +marks appended, e.g., @code{recv!}. +@item +Predicates (returning only @code{#t} or @code{#f}) have question marks +appended, e.g., @code{access?}. +@item +Some names are changed to avoid conflict with dissimilar interfaces +defined by scsh, e.g., @code{primitive-fork}. +@item +Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted +to Scheme variables of the same name (underscores are not replaced +with hyphens). +@end itemize + +Unexpected conditions are generally handled by raising exceptions. +There are a few procedures which return a special value if they don't +succeed, e.g., @code{getenv} returns @code{#f} if it the requested +string is not found in the environment. These cases are noted in +the documentation. + +For ways to deal with exceptions, see @ref{Exceptions}. + +@cindex @code{errno} +Errors which the C library would report by returning a null pointer or +through some other means are reported by raising a @code{system-error} +exception with @code{scm-error} (@pxref{Error Reporting}). The +@var{data} parameter is a list containing the Unix @code{errno} value +(an integer). For example, + +@example +(define (my-handler key func fmt fmtargs data) + (display key) (newline) + (display func) (newline) + (apply format #t fmt fmtargs) (newline) + (display data) (newline)) + +(catch 'system-error + (lambda () (dup2 -123 -456)) + my-handler) + +@print{} +system-error +dup2 +Bad file descriptor +(9) +@end example + + +@sp 1 +@defun system-error-errno arglist +@cindex @code{errno} +Return the @code{errno} value from a list which is the arguments to an +exception handler. If the exception is not a @code{system-error}, +then the return is @code{#f}. For example, + +@example +(catch + 'system-error + (lambda () + (mkdir "/this-ought-to-fail-if-I'm-not-root")) + (lambda stuff + (let ((errno (system-error-errno stuff))) + (cond + ((= errno EACCES) + (display "You're not allowed to do that.")) + ((= errno EEXIST) + (display "Already exists.")) + (#t + (display (strerror errno)))) + (newline)))) +@end example +@end defun + + +@node Ports and File Descriptors +@subsection Ports and File Descriptors +@cindex file descriptor + +Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}. + +Each open file port has an associated operating system file descriptor. +File descriptors are generally not useful in Scheme programs; however +they may be needed when interfacing with foreign code and the Unix +environment. + +A file descriptor can be extracted from a port and a new port can be +created from a file descriptor. However a file descriptor is just an +integer and the garbage collector doesn't recognize it as a reference +to the port. If all other references to the port were dropped, then +it's likely that the garbage collector would free the port, with the +side-effect of closing the file descriptor prematurely. + +To assist the programmer in avoiding this problem, each port has an +associated @dfn{revealed count} which can be used to keep track of how many +times the underlying file descriptor has been stored in other places. +If a port's revealed count is greater than zero, the file descriptor +will not be closed when the port is garbage collected. A programmer +can therefore ensure that the revealed count will be greater than +zero if the file descriptor is needed elsewhere. + +For the simple case where a file descriptor is ``imported'' once to become +a port, it does not matter if the file descriptor is closed when the +port is garbage collected. There is no need to maintain a revealed +count. Likewise when ``exporting'' a file descriptor to the external +environment, setting the revealed count is not required provided the +port is kept open (i.e., is pointed to by a live Scheme binding) while +the file descriptor is in use. + +To correspond with traditional Unix behaviour, three file descriptors +(0, 1, and 2) are automatically imported when a program starts up and +assigned to the initial values of the current/standard input, output, +and error ports, respectively. The revealed count for each is +initially set to one, so that dropping references to one of these +ports will not result in its garbage collection: it could be retrieved +with @code{fdopen} or @code{fdes->ports}. + +Guile's ports can be buffered. This means that writing a byte to a file +port goes to the internal buffer first, and only when the buffer is full +(or the user invokes @code{force-output} on the port) is the data +actually written to the file descriptor. Likewise on input, bytes are +read in from the file descriptor in blocks and placed in a buffer. +Reading a character via @code{read-char} first goes to the buffer, +filling it as needed. Usually read buffering is more or less +transparent, but write buffering can sometimes cause writes to be +delayed unexpectedly, if you forget to call @code{force-output}. +@xref{Buffering}, for more on how to control port buffers. + +Note however that some procedures (e.g., @code{recv!}) will accept ports +as arguments, but will actually operate directly on the file descriptor +underlying the port. Any port buffering is ignored, including the +buffer which implements @code{peek-char} and @code{unread-char}. + +@deffn {Scheme Procedure} port-revealed port +@deffnx {C Function} scm_port_revealed (port) +Return the revealed count for @var{port}. +@end deffn + +@deffn {Scheme Procedure} set-port-revealed! port rcount +@deffnx {C Function} scm_set_port_revealed_x (port, rcount) +Sets the revealed count for a @var{port} to @var{rcount}. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} fileno port +@deffnx {C Function} scm_fileno (port) +Return the integer file descriptor underlying @var{port}. Does +not change its revealed count. +@end deffn + +@deffn {Scheme Procedure} port->fdes port +Returns the integer file descriptor underlying @var{port}. As a +side effect the revealed count of @var{port} is incremented. +@end deffn + +@deffn {Scheme Procedure} fdopen fdes modes +@deffnx {C Function} scm_fdopen (fdes, modes) +Return a new port based on the file descriptor @var{fdes}. Modes are +given by the string @var{modes}. The revealed count of the port is +initialized to zero. The @var{modes} string is the same as that +accepted by @code{open-file} (@pxref{File Ports, open-file}). +@end deffn + +@deffn {Scheme Procedure} fdes->ports fdes +@deffnx {C Function} scm_fdes_to_ports (fdes) +Return a list of existing ports which have @var{fdes} as an +underlying file descriptor, without changing their revealed +counts. +@end deffn + +@deffn {Scheme Procedure} fdes->inport fdes +Returns an existing input port which has @var{fdes} as its underlying file +descriptor, if one exists, and increments its revealed count. +Otherwise, returns a new input port with a revealed count of 1. +@end deffn + +@deffn {Scheme Procedure} fdes->outport fdes +Returns an existing output port which has @var{fdes} as its underlying file +descriptor, if one exists, and increments its revealed count. +Otherwise, returns a new output port with a revealed count of 1. +@end deffn + +@deffn {Scheme Procedure} primitive-move->fdes port fdes +@deffnx {C Function} scm_primitive_move_to_fdes (port, fdes) +Moves the underlying file descriptor for @var{port} to the integer +value @var{fdes} without changing the revealed count of @var{port}. +Any other ports already using this descriptor will be automatically +shifted to new descriptors and their revealed counts reset to zero. +The return value is @code{#f} if the file descriptor already had the +required value or @code{#t} if it was moved. +@end deffn + +@deffn {Scheme Procedure} move->fdes port fdes +Moves the underlying file descriptor for @var{port} to the integer +value @var{fdes} and sets its revealed count to one. Any other ports +already using this descriptor will be automatically +shifted to new descriptors and their revealed counts reset to zero. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} release-port-handle port +Decrements the revealed count for a port. +@end deffn + +@deffn {Scheme Procedure} fsync port_or_fd +@deffnx {C Function} scm_fsync (port_or_fd) +Copies any unwritten data for the specified output file descriptor to disk. +If @var{port_or_fd} is a port, its buffer is flushed before the underlying +file descriptor is fsync'd. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} open path flags [mode] +@deffnx {C Function} scm_open (path, flags, mode) +Open the file named by @var{path} for reading and/or writing. +@var{flags} is an integer specifying how the file should be opened. +@var{mode} is an integer specifying the permission bits of the file, +if it needs to be created, before the umask (@pxref{Processes}) is +applied. The default is 666 (Unix itself has no default). + +@var{flags} can be constructed by combining variables using @code{logior}. +Basic flags are: + +@defvar O_RDONLY +Open the file read-only. +@end defvar +@defvar O_WRONLY +Open the file write-only. +@end defvar +@defvar O_RDWR +Open the file read/write. +@end defvar +@defvar O_APPEND +Append to the file instead of truncating. +@end defvar +@defvar O_CREAT +Create the file if it does not already exist. +@end defvar + +@xref{File Status Flags,,,libc,The GNU C Library Reference Manual}, +for additional flags. +@end deffn + +@deffn {Scheme Procedure} open-fdes path flags [mode] +@deffnx {C Function} scm_open_fdes (path, flags, mode) +Similar to @code{open} but return a file descriptor instead of +a port. +@end deffn + +@deffn {Scheme Procedure} close fd_or_port +@deffnx {C Function} scm_close (fd_or_port) +Similar to @code{close-port} (@pxref{Ports, close-port}), +but also works on file descriptors. A side +effect of closing a file descriptor is that any ports using that file +descriptor are moved to a different file descriptor and have +their revealed counts set to zero. +@end deffn + +@deffn {Scheme Procedure} close-fdes fd +@deffnx {C Function} scm_close_fdes (fd) +A simple wrapper for the @code{close} system call. Close file +descriptor @var{fd}, which must be an integer. Unlike @code{close}, +the file descriptor will be closed even if a port is using it. The +return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} pipe +@deffnx {C Function} scm_pipe () +@cindex pipe +Return a newly created pipe: a pair of ports which are linked together +on the local machine. The @acronym{CAR} is the input port and the +@acronym{CDR} is the output port. Data written (and flushed) to the +output port can be read from the input port. Pipes are commonly used +for communication with a newly forked child process. The need to flush +the output port can be avoided by making it unbuffered using +@code{setvbuf} (@pxref{Buffering}). + +@defvar PIPE_BUF +A write of up to @code{PIPE_BUF} many bytes to a pipe is atomic, +meaning when done it goes into the pipe instantaneously and as a +contiguous block (@pxref{Pipe Atomicity,, Atomicity of Pipe I/O, libc, +The GNU C Library Reference Manual}). +@end defvar + +Note that the output port is likely to block if too much data has been +written but not yet read from the input port. Typically the capacity +is @code{PIPE_BUF} bytes. +@end deffn + +The next group of procedures perform a @code{dup2} +system call, if @var{newfd} (an +integer) is supplied, otherwise a @code{dup}. The file descriptor to be +duplicated can be supplied as an integer or contained in a port. The +type of value returned varies depending on which procedure is used. + +All procedures also have the side effect when performing @code{dup2} that any +ports using @var{newfd} are moved to a different file descriptor and have +their revealed counts set to zero. + +@deffn {Scheme Procedure} dup->fdes fd_or_port [fd] +@deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd) +Return a new integer file descriptor referring to the open file +designated by @var{fd_or_port}, which must be either an open +file port or a file descriptor. +@end deffn + +@deffn {Scheme Procedure} dup->inport port/fd [newfd] +Returns a new input port using the new file descriptor. +@end deffn + +@deffn {Scheme Procedure} dup->outport port/fd [newfd] +Returns a new output port using the new file descriptor. +@end deffn + +@deffn {Scheme Procedure} dup port/fd [newfd] +Returns a new port if @var{port/fd} is a port, with the same mode as the +supplied port, otherwise returns an integer file descriptor. +@end deffn + +@deffn {Scheme Procedure} dup->port port/fd mode [newfd] +Returns a new port using the new file descriptor. @var{mode} supplies a +mode string for the port (@pxref{File Ports, open-file}). +@end deffn + +@deffn {Scheme Procedure} duplicate-port port modes +Returns a new port which is opened on a duplicate of the file +descriptor underlying @var{port}, with mode string @var{modes} +as for @ref{File Ports, open-file}. The two ports +will share a file position and file status flags. + +Unexpected behaviour can result if both ports are subsequently used +and the original and/or duplicate ports are buffered. +The mode string can include @code{0} to obtain an unbuffered duplicate +port. + +This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}. +@end deffn + +@deffn {Scheme Procedure} redirect-port old_port new_port +@deffnx {C Function} scm_redirect_port (old_port, new_port) +This procedure takes two ports and duplicates the underlying file +descriptor from @var{old_port} into @var{new_port}. The +current file descriptor in @var{new_port} will be closed. +After the redirection the two ports will share a file position +and file status flags. + +The return value is unspecified. + +Unexpected behaviour can result if both ports are subsequently used +and the original and/or duplicate ports are buffered. + +This procedure does not have any side effects on other ports or +revealed counts. +@end deffn + +@deffn {Scheme Procedure} dup2 oldfd newfd +@deffnx {C Function} scm_dup2 (oldfd, newfd) +A simple wrapper for the @code{dup2} system call. +Copies the file descriptor @var{oldfd} to descriptor +number @var{newfd}, replacing the previous meaning +of @var{newfd}. Both @var{oldfd} and @var{newfd} must +be integers. +Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt +is made to move away ports which are using @var{newfd}. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} port-for-each proc +@deffnx {C Function} scm_port_for_each (SCM proc) +@deffnx {C Function} scm_c_port_for_each (void (*proc)(void *, SCM), void *data) +Apply @var{proc} to each port in the Guile port table +(FIXME: what is the Guile port table?) +in turn. The return value is unspecified. More specifically, +@var{proc} is applied exactly once to every port that exists in the +system at the time @code{port-for-each} is invoked. Changes to the +port table while @code{port-for-each} is running have no effect as far +as @code{port-for-each} is concerned. + +The C function @code{scm_port_for_each} takes a Scheme procedure +encoded as a @code{SCM} value, while @code{scm_c_port_for_each} takes +a pointer to a C function and passes along a arbitrary @var{data} +cookie. +@end deffn + +@deffn {Scheme Procedure} fcntl port/fd cmd [value] +@deffnx {C Function} scm_fcntl (object, cmd, value) +Apply @var{cmd} on @var{port/fd}, either a port or file descriptor. +The @var{value} argument is used by the @code{SET} commands described +below, it's an integer value. + +Values for @var{cmd} are: + +@defvar F_DUPFD +Duplicate the file descriptor, the same as @code{dup->fdes} above +does. +@end defvar + +@defvar F_GETFD +@defvarx F_SETFD +Get or set flags associated with the file descriptor. The only flag +is the following, + +@defvar FD_CLOEXEC +``Close on exec'', meaning the file descriptor will be closed on an +@code{exec} call (a successful such call). For example to set that +flag, + +@example +(fcntl port F_SETFD FD_CLOEXEC) +@end example + +Or better, set it but leave any other possible future flags unchanged, + +@example +(fcntl port F_SETFD (logior FD_CLOEXEC + (fcntl port F_GETFD))) +@end example +@end defvar +@end defvar + +@defvar F_GETFL +@defvarx F_SETFL +Get or set flags associated with the open file. These flags are +@code{O_RDONLY} etc described under @code{open} above. + +A common use is to set @code{O_NONBLOCK} on a network socket. The +following sets that flag, and leaves other flags unchanged. + +@example +(fcntl sock F_SETFL (logior O_NONBLOCK + (fcntl sock F_GETFL))) +@end example +@end defvar + +@defvar F_GETOWN +@defvarx F_SETOWN +Get or set the process ID of a socket's owner, for @code{SIGIO} signals. +@end defvar +@end deffn + +@deffn {Scheme Procedure} flock file operation +@deffnx {C Function} scm_flock (file, operation) +@cindex file locking +Apply or remove an advisory lock on an open file. +@var{operation} specifies the action to be done: + +@defvar LOCK_SH +Shared lock. More than one process may hold a shared lock +for a given file at a given time. +@end defvar +@defvar LOCK_EX +Exclusive lock. Only one process may hold an exclusive lock +for a given file at a given time. +@end defvar +@defvar LOCK_UN +Unlock the file. +@end defvar +@defvar LOCK_NB +Don't block when locking. This is combined with one of the other +operations using @code{logior} (@pxref{Bitwise Operations}). If +@code{flock} would block an @code{EWOULDBLOCK} error is thrown +(@pxref{Conventions}). +@end defvar + +The return value is not specified. @var{file} may be an open +file descriptor or an open file descriptor port. + +Note that @code{flock} does not lock files across NFS. +@end deffn + +@deffn {Scheme Procedure} select reads writes excepts [secs [usecs]] +@deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs) +This procedure has a variety of uses: waiting for the ability +to provide input, accept output, or the existence of +exceptional conditions on a collection of ports or file +descriptors, or waiting for a timeout to occur. + +When an error occurs, this procedure throws a @code{system-error} +exception (@pxref{Conventions, @code{system-error}}). Note that +@code{select} may return early for other reasons, for example due to +pending interrupts. @xref{Asyncs}, for more on interrupts. + +@var{reads}, @var{writes} and @var{excepts} can be lists or +vectors, with each member a port or a file descriptor. +The value returned is a list of three corresponding +lists or vectors containing only the members which meet the +specified requirement. The ability of port buffers to +provide input or accept output is taken into account. +Ordering of the input lists or vectors is not preserved. + +The optional arguments @var{secs} and @var{usecs} specify the +timeout. Either @var{secs} can be specified alone, as +either an integer or a real number, or both @var{secs} and +@var{usecs} can be specified as integers, in which case +@var{usecs} is an additional timeout expressed in +microseconds. If @var{secs} is omitted or is @code{#f} then +select will wait for as long as it takes for one of the other +conditions to be satisfied. + +The scsh version of @code{select} differs as follows: +Only vectors are accepted for the first three arguments. +The @var{usecs} argument is not supported. +Multiple values are returned instead of a list. +Duplicates in the input vectors appear only once in output. +An additional @code{select!} interface is provided. +@end deffn + +While it is sometimes necessary to operate at the level of file +descriptors, this is an operation whose correctness can only be +considered as part of a whole program. So for example while the effects +of @code{(string-set! x 34 #\y)} are limited to the bits of code that +can access @var{x}, @code{(close-fdes 34)} mutates the state of the +entire process. In particular if another thread is using file +descriptor 34 then their state might be corrupted; and another thread +which opens a file might cause file descriptor 34 to be re-used, so that +corruption could manifest itself in a strange way. + +@cindex fdes finalizers +@cindex file descriptor finalizers +@cindex finalizers, file descriptor +However when working with file descriptors, it's common to want to +associate information with the file descriptor, perhaps in a side table. +To support this use case and to allow user code to remove an association +when a file descriptor is closed, Guile offers @dfn{fdes finalizers}. + +As the name indicates, fdes finalizers are finalizers -- they can run in +response to garbage collection, and they can also run in response to +explicit calls to @code{close-port}, @code{close-fdes}, or the like. As +such they inherit many of the pitfalls of finalizers: they may be +invoked from concurrent threads, or not at all. @xref{Foreign Object +Memory Management}, for more on finalizers. + +To use fdes finalizers, import their module; + +@example +(use-modules (ice-9 fdes-finalizers)) +@end example + +@deffn {Scheme Procedure} add-fdes-finalizer! fdes finalizer +@deffnx {Scheme Procedure} remove-fdes-finalizer! fdes finalizer +Add or remove a finalizer for @var{fdes}. A finalizer is a procedure +that is called by Guile when a file descriptor is closed. The file +descriptor being closed is passed as the one argument to the finalizer. +If a finalizer has been added multiple times to a file descriptor, to +remove it would require that number of calls to +@code{remove-fdes-finalizer!}. + +The finalizers added to a file descriptor are called by Guile in an +unspecified order, and their return values are ignored. +@end deffn + + +@node File System +@subsection File System +@cindex file system + +These procedures allow querying and setting file system attributes +(such as owner, +permissions, sizes and types of files); deleting, copying, renaming and +linking files; creating and removing directories and querying their +contents; syncing the file system and creating special files. + +@deffn {Scheme Procedure} access? path how +@deffnx {C Function} scm_access (path, how) +Test accessibility of a file under the real UID and GID of the calling +process. The return is @code{#t} if @var{path} exists and the +permissions requested by @var{how} are all allowed, or @code{#f} if +not. + +@var{how} is an integer which is one of the following values, or a +bitwise-OR (@code{logior}) of multiple values. + +@defvar R_OK +Test for read permission. +@end defvar +@defvar W_OK +Test for write permission. +@end defvar +@defvar X_OK +Test for execute permission. +@end defvar +@defvar F_OK +Test for existence of the file. This is implied by each of the other +tests, so there's no need to combine it with them. +@end defvar + +It's important to note that @code{access?} does not simply indicate +what will happen on attempting to read or write a file. In normal +circumstances it does, but in a set-UID or set-GID program it doesn't +because @code{access?} tests the real ID, whereas an open or execute +attempt uses the effective ID. + +A program which will never run set-UID/GID can ignore the difference +between real and effective IDs, but for maximum generality, especially +in library functions, it's best not to use @code{access?} to predict +the result of an open or execute, instead simply attempt that and +catch any exception. + +The main use for @code{access?} is to let a set-UID/GID program +determine what the invoking user would have been allowed to do, +without the greater (or perhaps lesser) privileges afforded by the +effective ID. For more on this, see @ref{Testing File Access,,, libc, +The GNU C Library Reference Manual}. +@end deffn + +@findex fstat +@deffn {Scheme Procedure} stat object +@deffnx {C Function} scm_stat (object) +Return an object containing various information about the file +determined by @var{object}. @var{object} can be a string containing +a file name or a port or integer file descriptor which is open +on a file (in which case @code{fstat} is used as the underlying +system call). + +The object returned by @code{stat} can be passed as a single +parameter to the following procedures, all of which return +integers: + +@deffn {Scheme Procedure} stat:dev st +The device number containing the file. +@end deffn +@deffn {Scheme Procedure} stat:ino st +The file serial number, which distinguishes this file from all +other files on the same device. +@end deffn +@deffn {Scheme Procedure} stat:mode st +The mode of the file. This is an integer which incorporates file type +information and file permission bits. See also @code{stat:type} and +@code{stat:perms} below. +@end deffn +@deffn {Scheme Procedure} stat:nlink st +The number of hard links to the file. +@end deffn +@deffn {Scheme Procedure} stat:uid st +The user ID of the file's owner. +@end deffn +@deffn {Scheme Procedure} stat:gid st +The group ID of the file. +@end deffn +@deffn {Scheme Procedure} stat:rdev st +Device ID; this entry is defined only for character or block special +files. On some systems this field is not available at all, in which +case @code{stat:rdev} returns @code{#f}. +@end deffn +@deffn {Scheme Procedure} stat:size st +The size of a regular file in bytes. +@end deffn +@deffn {Scheme Procedure} stat:atime st +The last access time for the file, in seconds. +@end deffn +@deffn {Scheme Procedure} stat:mtime st +The last modification time for the file, in seconds. +@end deffn +@deffn {Scheme Procedure} stat:ctime st +The last modification time for the attributes of the file, in seconds. +@end deffn +@deffn {Scheme Procedure} stat:atimensec st +@deffnx {Scheme Procedure} stat:mtimensec st +@deffnx {Scheme Procedure} stat:ctimensec st +The fractional part of a file's access, modification, or attribute modification +time, in nanoseconds. Nanosecond timestamps are only available on some operating +systems and file systems. If Guile cannot retrieve nanosecond-level timestamps +for a file, these fields will be set to 0. +@end deffn +@deffn {Scheme Procedure} stat:blksize st +The optimal block size for reading or writing the file, in bytes. On +some systems this field is not available, in which case +@code{stat:blksize} returns a sensible suggested block size. +@end deffn +@deffn {Scheme Procedure} stat:blocks st +The amount of disk space that the file occupies measured in units of +512 byte blocks. On some systems this field is not available, in +which case @code{stat:blocks} returns @code{#f}. +@end deffn + +In addition, the following procedures return the information +from @code{stat:mode} in a more convenient form: + +@deffn {Scheme Procedure} stat:type st +A symbol representing the type of file. Possible values are +@samp{regular}, @samp{directory}, @samp{symlink}, +@samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket}, +and @samp{unknown}. +@end deffn +@deffn {Scheme Procedure} stat:perms st +An integer representing the access permission bits. +@end deffn +@end deffn + +@deffn {Scheme Procedure} lstat path +@deffnx {C Function} scm_lstat (path) +Similar to @code{stat}, but does not follow symbolic links, i.e., +it will return information about a symbolic link itself, not the +file it points to. @var{path} must be a string. +@end deffn + +@deffn {Scheme Procedure} readlink path +@deffnx {C Function} scm_readlink (path) +Return the value of the symbolic link named by @var{path} (a +string), i.e., the file that the link points to. +@end deffn + +@findex fchown +@findex lchown +@deffn {Scheme Procedure} chown object owner group +@deffnx {C Function} scm_chown (object, owner, group) +Change the ownership and group of the file referred to by @var{object} +to the integer values @var{owner} and @var{group}. @var{object} can +be a string containing a file name or, if the platform supports +@code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference +Manual}), a port or integer file descriptor which is open on the file. +The return value is unspecified. + +If @var{object} is a symbolic link, either the +ownership of the link or the ownership of the referenced file will be +changed depending on the operating system (lchown is +unsupported at present). If @var{owner} or @var{group} is specified +as @code{-1}, then that ID is not changed. +@end deffn + +@findex fchmod +@deffn {Scheme Procedure} chmod object mode +@deffnx {C Function} scm_chmod (object, mode) +Changes the permissions of the file referred to by @var{object}. +@var{object} can be a string containing a file name or a port or integer file +descriptor which is open on a file (in which case @code{fchmod} is used +as the underlying system call). +@var{mode} specifies +the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} utime pathname [actime [modtime [actimens [modtimens [flags]]]]] +@deffnx {C Function} scm_utime (pathname, actime, modtime, actimens, modtimens, flags) +@code{utime} sets the access and modification times for the +file named by @var{pathname}. If @var{actime} or @var{modtime} is +not supplied, then the current time is used. @var{actime} and +@var{modtime} must be integer time values as returned by the +@code{current-time} procedure. + +The optional @var{actimens} and @var{modtimens} are nanoseconds +to add @var{actime} and @var{modtime}. Nanosecond precision is +only supported on some combinations of file systems and operating +systems. +@lisp +(utime "foo" (- (current-time) 3600)) +@end lisp +will set the access time to one hour in the past and the +modification time to the current time. +@end deffn + +@findex unlink +@deffn {Scheme Procedure} delete-file str +@deffnx {C Function} scm_delete_file (str) +Deletes (or ``unlinks'') the file whose path is specified by +@var{str}. +@end deffn + +@deffn {Scheme Procedure} copy-file oldfile newfile +@deffnx {C Function} scm_copy_file (oldfile, newfile) +Copy the file specified by @var{oldfile} to @var{newfile}. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} sendfile out in count [offset] +@deffnx {C Function} scm_sendfile (out, in, count, offset) +Send @var{count} bytes from @var{in} to @var{out}, both of which +must be either open file ports or file descriptors. When +@var{offset} is omitted, start reading from @var{in}'s current +position; otherwise, start reading at @var{offset}. Return +the number of bytes actually sent. + +When @var{in} is a port, it is often preferable to specify @var{offset}, +because @var{in}'s offset as a port may be different from the offset of +its underlying file descriptor. + +On systems that support it, such as GNU/Linux, this procedure uses the +@code{sendfile} libc function, which usually corresponds to a system +call. This is faster than doing a series of @code{read} and +@code{write} system calls. A typical application is to send a file over +a socket. + +In some cases, the @code{sendfile} libc function may return +@code{EINVAL} or @code{ENOSYS}. In that case, Guile's @code{sendfile} +procedure automatically falls back to doing a series of @code{read} and +@code{write} calls. + +In other cases, the libc function may send fewer bytes than +@var{count}---for instance because @var{out} is a slow or limited +device, such as a pipe. When that happens, Guile's @code{sendfile} +automatically retries until exactly @var{count} bytes were sent or an +error occurs. +@end deffn + +@findex rename +@deffn {Scheme Procedure} rename-file oldname newname +@deffnx {C Function} scm_rename (oldname, newname) +Renames the file specified by @var{oldname} to @var{newname}. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} link oldpath newpath +@deffnx {C Function} scm_link (oldpath, newpath) +Creates a new name @var{newpath} in the file system for the +file named by @var{oldpath}. If @var{oldpath} is a symbolic +link, the link may or may not be followed depending on the +system. +@end deffn + +@deffn {Scheme Procedure} symlink oldpath newpath +@deffnx {C Function} scm_symlink (oldpath, newpath) +Create a symbolic link named @var{newpath} with the value (i.e., pointing to) +@var{oldpath}. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} mkdir path [mode] +@deffnx {C Function} scm_mkdir (path, mode) +Create a new directory named by @var{path}. If @var{mode} is omitted +then the permissions of the directory are set to @code{#o777} +masked with the current umask (@pxref{Processes, @code{umask}}). +Otherwise they are set to the value specified with @var{mode}. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} rmdir path +@deffnx {C Function} scm_rmdir (path) +Remove the existing directory named by @var{path}. The directory must +be empty for this to succeed. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} opendir dirname +@deffnx {C Function} scm_opendir (dirname) +@cindex directory contents +Open the directory specified by @var{dirname} and return a directory +stream. + +Before using this and the procedures below, make sure to see the +higher-level procedures for directory traversal that are available +(@pxref{File Tree Walk}). +@end deffn + +@deffn {Scheme Procedure} directory-stream? object +@deffnx {C Function} scm_directory_stream_p (object) +Return a boolean indicating whether @var{object} is a directory +stream as returned by @code{opendir}. +@end deffn + +@deffn {Scheme Procedure} readdir stream +@deffnx {C Function} scm_readdir (stream) +Return (as a string) the next directory entry from the directory stream +@var{stream}. If there is no remaining entry to be read then the +end of file object is returned. +@end deffn + +@deffn {Scheme Procedure} rewinddir stream +@deffnx {C Function} scm_rewinddir (stream) +Reset the directory port @var{stream} so that the next call to +@code{readdir} will return the first directory entry. +@end deffn + +@deffn {Scheme Procedure} closedir stream +@deffnx {C Function} scm_closedir (stream) +Close the directory stream @var{stream}. +The return value is unspecified. +@end deffn + +Here is an example showing how to display all the entries in a +directory: + +@lisp +(define dir (opendir "/usr/lib")) +(do ((entry (readdir dir) (readdir dir))) + ((eof-object? entry)) + (display entry)(newline)) +(closedir dir) +@end lisp + +@deffn {Scheme Procedure} sync +@deffnx {C Function} scm_sync () +Flush the operating system disk buffers. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} mknod path type perms dev +@deffnx {C Function} scm_mknod (path, type, perms, dev) +@cindex device file +Creates a new special file, such as a file corresponding to a device. +@var{path} specifies the name of the file. @var{type} should be one +of the following symbols: @samp{regular}, @samp{directory}, +@samp{symlink}, @samp{block-special}, @samp{char-special}, +@samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the +file permissions. @var{dev} (an integer) specifies which device the +special file refers to. Its exact interpretation depends on the kind +of special file being created. + +E.g., +@lisp +(mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2)) +@end lisp + +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} tmpnam +@deffnx {C Function} scm_tmpnam () +@cindex temporary file +Return an auto-generated name of a temporary file, a file which +doesn't already exist. The name includes a path, it's usually in +@file{/tmp} but that's system dependent. + +Care must be taken when using @code{tmpnam}. In between choosing the +name and creating the file another program might use that name, or an +attacker might even make it a symlink pointing at something important +and causing you to overwrite that. + +The safe way is to create the file using @code{open} with +@code{O_EXCL} to avoid any overwriting. A loop can try again with +another name if the file exists (error @code{EEXIST}). +@code{mkstemp!} below does that. +@end deffn + +@deffn {Scheme Procedure} mkstemp! tmpl [mode] +@deffnx {C Function} scm_mkstemp (tmpl) +@cindex temporary file +Create a new unique file in the file system and return a new buffered +port open for reading and writing to the file. + +@var{tmpl} is a string specifying where the file should be created: it +must end with @samp{XXXXXX} and those @samp{X}s will be changed in the +string to return the name of the file. (@code{port-filename} on the +port also gives the name.) + +POSIX doesn't specify the permissions mode of the file, on GNU and +most systems it's @code{#o600}. An application can use @code{chmod} +to relax that if desired. For example @code{#o666} less @code{umask}, +which is usual for ordinary file creation, + +@example +(let ((port (mkstemp! (string-copy "/tmp/myfile-XXXXXX")))) + (chmod port (logand #o666 (lognot (umask)))) + ...) +@end example + +The optional @var{mode} argument specifies a mode with which to open the +new file, as a string in the same format that @code{open-file} takes. +It defaults to @code{"w+"}. +@end deffn + +@deffn {Scheme Procedure} tmpfile +@deffnx {C Function} scm_tmpfile () +Return an input/output port to a unique temporary file +named using the path prefix @code{P_tmpdir} defined in +@file{stdio.h}. +The file is automatically deleted when the port is closed +or the program terminates. +@end deffn + +@deffn {Scheme Procedure} dirname filename +@deffnx {C Function} scm_dirname (filename) +Return the directory name component of the file name +@var{filename}. If @var{filename} does not contain a directory +component, @code{.} is returned. +@end deffn + +@deffn {Scheme Procedure} basename filename [suffix] +@deffnx {C Function} scm_basename (filename, suffix) +Return the base name of the file name @var{filename}. The +base name is the file name without any directory components. +If @var{suffix} is provided, and is equal to the end of +@var{basename}, it is removed also. + +@lisp +(basename "/tmp/test.xml" ".xml") +@result{} "test" +@end lisp +@end deffn + +@deffn {Scheme Procedure} file-exists? filename +Return @code{#t} if the file named @var{filename} exists, @code{#f} if +not. +@end deffn + +@cindex file name separator +@cindex absolute file name + +Many operating systems, such as GNU, use @code{/} (forward slash) to +separate the components of a file name; any file name starting with +@code{/} is considered an @dfn{absolute file name}. These conventions +are specified by the POSIX Base Definitions, which refer to conforming +file names as ``pathnames''. Some operating systems use a different +convention; in particular, Windows uses @code{\} (backslash) as the file +name separator, and also has the notion of @dfn{volume names} like +@code{C:\} for absolute file names. The following procedures and +variables provide support for portable file name manipulations. + +@deffn {Scheme Procedure} system-file-name-convention +Return either @code{posix} or @code{windows}, depending on +what kind of system this Guile is running on. +@end deffn + +@deffn {Scheme Procedure} file-name-separator? c +Return true if character @var{c} is a file name separator on the host +platform. +@end deffn + +@deffn {Scheme Procedure} absolute-file-name? file-name +Return true if @var{file-name} denotes an absolute file name on the host +platform. +@end deffn + +@defvr {Scheme Variable} file-name-separator-string +The preferred file name separator. + +Note that on MinGW builds for Windows, both @code{/} and @code{\} are +valid separators. Thus, programs should not assume that +@code{file-name-separator-string} is the @emph{only} file name +separator---e.g., when extracting the components of a file name. +@end defvr + + +@node User Information +@subsection User Information +@cindex user information +@cindex password file +@cindex group file + +The facilities in this section provide an interface to the user and +group database. +They should be used with care since they are not reentrant. + +The following functions accept an object representing user information +and return a selected component: + +@deffn {Scheme Procedure} passwd:name pw +The name of the userid. +@end deffn +@deffn {Scheme Procedure} passwd:passwd pw +The encrypted passwd. +@end deffn +@deffn {Scheme Procedure} passwd:uid pw +The user id number. +@end deffn +@deffn {Scheme Procedure} passwd:gid pw +The group id number. +@end deffn +@deffn {Scheme Procedure} passwd:gecos pw +The full name. +@end deffn +@deffn {Scheme Procedure} passwd:dir pw +The home directory. +@end deffn +@deffn {Scheme Procedure} passwd:shell pw +The login shell. +@end deffn +@sp 1 + +@deffn {Scheme Procedure} getpwuid uid +Look up an integer userid in the user database. +@end deffn + +@deffn {Scheme Procedure} getpwnam name +Look up a user name string in the user database. +@end deffn + +@deffn {Scheme Procedure} setpwent +Initializes a stream used by @code{getpwent} to read from the user database. +The next use of @code{getpwent} will return the first entry. The +return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} getpwent +Read the next entry in the user database stream. The return is a +passwd user object as above, or @code{#f} when no more entries. +@end deffn + +@deffn {Scheme Procedure} endpwent +Closes the stream used by @code{getpwent}. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setpw [arg] +@deffnx {C Function} scm_setpwent (arg) +If called with a true argument, initialize or reset the password data +stream. Otherwise, close the stream. The @code{setpwent} and +@code{endpwent} procedures are implemented on top of this. +@end deffn + +@deffn {Scheme Procedure} getpw [user] +@deffnx {C Function} scm_getpwuid (user) +Look up an entry in the user database. @var{user} can be an integer, +a string, or omitted, giving the behaviour of getpwuid, getpwnam +or getpwent respectively. +@end deffn + +The following functions accept an object representing group information +and return a selected component: + +@deffn {Scheme Procedure} group:name gr +The group name. +@end deffn +@deffn {Scheme Procedure} group:passwd gr +The encrypted group password. +@end deffn +@deffn {Scheme Procedure} group:gid gr +The group id number. +@end deffn +@deffn {Scheme Procedure} group:mem gr +A list of userids which have this group as a supplementary group. +@end deffn +@sp 1 + +@deffn {Scheme Procedure} getgrgid gid +Look up an integer group id in the group database. +@end deffn + +@deffn {Scheme Procedure} getgrnam name +Look up a group name in the group database. +@end deffn + +@deffn {Scheme Procedure} setgrent +Initializes a stream used by @code{getgrent} to read from the group database. +The next use of @code{getgrent} will return the first entry. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} getgrent +Return the next entry in the group database, using the stream set by +@code{setgrent}. +@end deffn + +@deffn {Scheme Procedure} endgrent +Closes the stream used by @code{getgrent}. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setgr [arg] +@deffnx {C Function} scm_setgrent (arg) +If called with a true argument, initialize or reset the group data +stream. Otherwise, close the stream. The @code{setgrent} and +@code{endgrent} procedures are implemented on top of this. +@end deffn + +@deffn {Scheme Procedure} getgr [group] +@deffnx {C Function} scm_getgrgid (group) +Look up an entry in the group database. @var{group} can be an integer, +a string, or omitted, giving the behaviour of getgrgid, getgrnam +or getgrent respectively. +@end deffn + +In addition to the accessor procedures for the user database, the +following shortcut procedure is also available. + +@deffn {Scheme Procedure} getlogin +@deffnx {C Function} scm_getlogin () +Return a string containing the name of the user logged in on +the controlling terminal of the process, or @code{#f} if this +information cannot be obtained. +@end deffn + + +@node Time +@subsection Time +@cindex time + +@deffn {Scheme Procedure} current-time +@deffnx {C Function} scm_current_time () +Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC}, +excluding leap seconds. +@end deffn + +@deffn {Scheme Procedure} gettimeofday +@deffnx {C Function} scm_gettimeofday () +Return a pair containing the number of seconds and microseconds +since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note: +whether true microsecond resolution is available depends on the +operating system. +@end deffn + +The following procedures either accept an object representing a broken down +time and return a selected component, or accept an object representing +a broken down time and a value and set the component to the value. +The numbers in parentheses give the usual range. + +@deffn {Scheme Procedure} tm:sec tm +@deffnx {Scheme Procedure} set-tm:sec tm val +Seconds (0-59). +@end deffn +@deffn {Scheme Procedure} tm:min tm +@deffnx {Scheme Procedure} set-tm:min tm val +Minutes (0-59). +@end deffn +@deffn {Scheme Procedure} tm:hour tm +@deffnx {Scheme Procedure} set-tm:hour tm val +Hours (0-23). +@end deffn +@deffn {Scheme Procedure} tm:mday tm +@deffnx {Scheme Procedure} set-tm:mday tm val +Day of the month (1-31). +@end deffn +@deffn {Scheme Procedure} tm:mon tm +@deffnx {Scheme Procedure} set-tm:mon tm val +Month (0-11). +@end deffn +@deffn {Scheme Procedure} tm:year tm +@deffnx {Scheme Procedure} set-tm:year tm val +Year (70-), the year minus 1900. +@end deffn +@deffn {Scheme Procedure} tm:wday tm +@deffnx {Scheme Procedure} set-tm:wday tm val +Day of the week (0-6) with Sunday represented as 0. +@end deffn +@deffn {Scheme Procedure} tm:yday tm +@deffnx {Scheme Procedure} set-tm:yday tm val +Day of the year (0-364, 365 in leap years). +@end deffn +@deffn {Scheme Procedure} tm:isdst tm +@deffnx {Scheme Procedure} set-tm:isdst tm val +Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than +0 for ``unknown''). +@end deffn +@deffn {Scheme Procedure} tm:gmtoff tm +@deffnx {Scheme Procedure} set-tm:gmtoff tm val +Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200). +For example on East coast USA (zone @samp{EST+5}) this would be 18000 +(ie.@: @m{5\times60\times60,5*60*60}) in winter, or 14400 +(ie.@: @m{4\times60\times60,4*60*60}) during daylight savings. + +Note @code{tm:gmtoff} is not the same as @code{tm_gmtoff} in the C +@code{tm} structure. @code{tm_gmtoff} is seconds east and hence the +negative of the value here. +@end deffn +@deffn {Scheme Procedure} tm:zone tm +@deffnx {Scheme Procedure} set-tm:zone tm val +Time zone label (a string), not necessarily unique. +@end deffn +@sp 1 + +@deffn {Scheme Procedure} localtime time [zone] +@deffnx {C Function} scm_localtime (time, zone) +@cindex local time +Return an object representing the broken down components of +@var{time}, an integer like the one returned by +@code{current-time}. The time zone for the calculation is +optionally specified by @var{zone} (a string), otherwise the +@env{TZ} environment variable or the system default is used. +@end deffn + +@deffn {Scheme Procedure} gmtime time +@deffnx {C Function} scm_gmtime (time) +Return an object representing the broken down components of +@var{time}, an integer like the one returned by +@code{current-time}. The values are calculated for @acronym{UTC}. +@end deffn + +@deffn {Scheme Procedure} mktime sbd-time [zone] +@deffnx {C Function} scm_mktime (sbd_time, zone) +For a broken down time object @var{sbd-time}, return a pair the +@code{car} of which is an integer time like @code{current-time}, and +the @code{cdr} of which is a new broken down time with normalized +fields. + +@var{zone} is a timezone string, or the default is the @env{TZ} +environment variable or the system default (@pxref{TZ Variable,, +Specifying the Time Zone with @env{TZ}, libc, GNU C Library Reference +Manual}). @var{sbd-time} is taken to be in that @var{zone}. + +The following fields of @var{sbd-time} are used: @code{tm:year}, +@code{tm:mon}, @code{tm:mday}, @code{tm:hour}, @code{tm:min}, +@code{tm:sec}, @code{tm:isdst}. The values can be outside their usual +ranges. For example @code{tm:hour} normally goes up to 23, but a +value say 33 would mean 9 the following day. + +@code{tm:isdst} in @var{sbd-time} says whether the time given is with +daylight savings or not. This is ignored if @var{zone} doesn't have +any daylight savings adjustment amount. + +The broken down time in the return normalizes the values of +@var{sbd-time} by bringing them into their usual ranges, and using the +actual daylight savings rule for that time in @var{zone} (which may +differ from what @var{sbd-time} had). The easiest way to think of +this is that @var{sbd-time} plus @var{zone} converts to the integer +UTC time, then a @code{localtime} is applied to get the normal +presentation of that time, in @var{zone}. +@end deffn + +@deffn {Scheme Procedure} tzset +@deffnx {C Function} scm_tzset () +Initialize the timezone from the @env{TZ} environment variable +or the system default. It's not usually necessary to call this procedure +since it's done automatically by other procedures that depend on the +timezone. +@end deffn + +@deffn {Scheme Procedure} strftime format tm +@deffnx {C Function} scm_strftime (format, tm) +@cindex time formatting +Return a string which is broken-down time structure @var{tm} formatted +according to the given @var{format} string. + +@var{format} contains field specifications introduced by a @samp{%} +character. See @ref{Formatting Calendar Time,,, libc, The GNU C +Library Reference Manual}, or @samp{man 3 strftime}, for the available +formatting. + +@lisp +(strftime "%c" (localtime (current-time))) +@result{} "Mon Mar 11 20:17:43 2002" +@end lisp + +If @code{setlocale} has been called (@pxref{Locales}), month and day +names are from the current locale and in the locale character set. +@end deffn + +@deffn {Scheme Procedure} strptime format string +@deffnx {C Function} scm_strptime (format, string) +@cindex time parsing +Performs the reverse action to @code{strftime}, parsing +@var{string} according to the specification supplied in +@var{format}. The interpretation of month and day names is +dependent on the current locale. The value returned is a pair. +The @acronym{CAR} has an object with time components +in the form returned by @code{localtime} or @code{gmtime}, +but the time zone components +are not usefully set. +The @acronym{CDR} reports the number of characters from @var{string} +which were used for the conversion. +@end deffn + +@defvar internal-time-units-per-second +The value of this variable is the number of time units per second +reported by the following procedures. +@end defvar + +@deffn {Scheme Procedure} times +@deffnx {C Function} scm_times () +Return an object with information about real and processor +time. The following procedures accept such an object as an +argument and return a selected component: + +@deffn {Scheme Procedure} tms:clock tms +The current real time, expressed as time units relative to an +arbitrary base. +@end deffn +@deffn {Scheme Procedure} tms:utime tms +The CPU time units used by the calling process. +@end deffn +@deffn {Scheme Procedure} tms:stime tms +The CPU time units used by the system on behalf of the calling +process. +@end deffn +@deffn {Scheme Procedure} tms:cutime tms +The CPU time units used by terminated child processes of the +calling process, whose status has been collected (e.g., using +@code{waitpid}). +@end deffn +@deffn {Scheme Procedure} tms:cstime tms +Similarly, the CPU times units used by the system on behalf of +terminated child processes. +@end deffn +@end deffn + +@deffn {Scheme Procedure} get-internal-real-time +@deffnx {C Function} scm_get_internal_real_time () +Return the number of time units since the interpreter was +started. +@end deffn + +@deffn {Scheme Procedure} get-internal-run-time +@deffnx {C Function} scm_get_internal_run_time () +Return the number of time units of processor time used by the +interpreter. Both @emph{system} and @emph{user} time are +included but subprocesses are not. +@end deffn + +@node Runtime Environment +@subsection Runtime Environment + +@deffn {Scheme Procedure} program-arguments +@deffnx {Scheme Procedure} command-line +@deffnx {Scheme Procedure} set-program-arguments +@deffnx {C Function} scm_program_arguments () +@deffnx {C Function} scm_set_program_arguments_scm (lst) +@cindex command line +@cindex program arguments +Get the command line arguments passed to Guile, or set new arguments. + +The arguments are a list of strings, the first of which is the invoked +program name. This is just @nicode{"guile"} (or the executable path) +when run interactively, or it's the script name when running a script +with @option{-s} (@pxref{Invoking Guile}). + +@example +guile -L /my/extra/dir -s foo.scm abc def + +(program-arguments) @result{} ("foo.scm" "abc" "def") +@end example + +@code{set-program-arguments} allows a library module or similar to +modify the arguments, for example to strip options it recognises, +leaving the rest for the mainline. + +The argument list is held in a fluid, which means it's separate for +each thread. Neither the list nor the strings within it are copied at +any point and normally should not be mutated. + +The two names @code{program-arguments} and @code{command-line} are an +historical accident, they both do exactly the same thing. The name +@code{scm_set_program_arguments_scm} has an extra @code{_scm} on the +end to avoid clashing with the C function below. +@end deffn + +@deftypefn {C Function} void scm_set_program_arguments (int argc, char **argv, char *first) +@cindex command line +@cindex program arguments +Set the list of command line arguments for @code{program-arguments} +and @code{command-line} above. + +@var{argv} is an array of null-terminated strings, as in a C +@code{main} function. @var{argc} is the number of strings in +@var{argv}, or if it's negative then a @code{NULL} in @var{argv} marks +its end. + +@var{first} is an extra string put at the start of the arguments, or +@code{NULL} for no such extra. This is a convenient way to pass the +program name after advancing @var{argv} to strip option arguments. +Eg.@: + +@example +@{ + char *progname = argv[0]; + for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++) + @{ + /* munch option ... */ + @} + /* remaining args for scheme level use */ + scm_set_program_arguments (-1, argv, progname); +@} +@end example + +This sort of thing is often done at startup under +@code{scm_boot_guile} with options handled at the C level removed. +The given strings are all copied, so the C data is not accessed again +once @code{scm_set_program_arguments} returns. +@end deftypefn + +@deffn {Scheme Procedure} getenv name +@deffnx {C Function} scm_getenv (name) +@cindex environment +Looks up the string @var{name} in the current environment. The return +value is @code{#f} unless a string of the form @code{NAME=VALUE} is +found, in which case the string @code{VALUE} is returned. +@end deffn + +@deffn {Scheme Procedure} setenv name value +Modifies the environment of the current process, which is +also the default environment inherited by child processes. + +If @var{value} is @code{#f}, then @var{name} is removed from the +environment. Otherwise, the string @var{name}=@var{value} is added +to the environment, replacing any existing string with name matching +@var{name}. + +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} unsetenv name +Remove variable @var{name} from the environment. The +name can not contain a @samp{=} character. +@end deffn + +@deffn {Scheme Procedure} environ [env] +@deffnx {C Function} scm_environ (env) +If @var{env} is omitted, return the current environment (in the +Unix sense) as a list of strings. Otherwise set the current +environment, which is also the default environment for child +processes, to the supplied list of strings. Each member of +@var{env} should be of the form @var{name}=@var{value} and values of +@var{name} should not be duplicated. If @var{env} is supplied +then the return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} putenv str +@deffnx {C Function} scm_putenv (str) +Modifies the environment of the current process, which is +also the default environment inherited by child processes. + +If @var{str} is of the form @code{NAME=VALUE} then it will be written +directly into the environment, replacing any existing environment string +with +name matching @code{NAME}. If @var{str} does not contain an equal +sign, then any existing string with name matching @var{str} will +be removed. + +The return value is unspecified. +@end deffn + + +@node Processes +@subsection Processes +@cindex processes +@cindex child processes + +@findex cd +@deffn {Scheme Procedure} chdir str +@deffnx {C Function} scm_chdir (str) +@cindex current directory +Change the current working directory to @var{str}. +The return value is unspecified. +@end deffn + +@findex pwd +@deffn {Scheme Procedure} getcwd +@deffnx {C Function} scm_getcwd () +Return the name of the current working directory. +@end deffn + +@deffn {Scheme Procedure} umask [mode] +@deffnx {C Function} scm_umask (mode) +If @var{mode} is omitted, returns a decimal number representing the +current file creation mask. Otherwise the file creation mask is set +to @var{mode} and the previous value is returned. @xref{Setting +Permissions,,Assigning File Permissions,libc,The GNU C Library +Reference Manual}, for more on how to use umasks. + +E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18. +@end deffn + +@deffn {Scheme Procedure} chroot path +@deffnx {C Function} scm_chroot (path) +Change the root directory to that specified in @var{path}. +This directory will be used for path names beginning with +@file{/}. The root directory is inherited by all children +of the current process. Only the superuser may change the +root directory. +@end deffn + +@deffn {Scheme Procedure} getpid +@deffnx {C Function} scm_getpid () +Return an integer representing the current process ID. +@end deffn + +@deffn {Scheme Procedure} getgroups +@deffnx {C Function} scm_getgroups () +Return a vector of integers representing the current +supplementary group IDs. +@end deffn + +@deffn {Scheme Procedure} getppid +@deffnx {C Function} scm_getppid () +Return an integer representing the process ID of the parent +process. +@end deffn + +@deffn {Scheme Procedure} getuid +@deffnx {C Function} scm_getuid () +Return an integer representing the current real user ID. +@end deffn + +@deffn {Scheme Procedure} getgid +@deffnx {C Function} scm_getgid () +Return an integer representing the current real group ID. +@end deffn + +@deffn {Scheme Procedure} geteuid +@deffnx {C Function} scm_geteuid () +Return an integer representing the current effective user ID. +If the system does not support effective IDs, then the real ID +is returned. @code{(provided? 'EIDs)} reports whether the +system supports effective IDs. +@end deffn + +@deffn {Scheme Procedure} getegid +@deffnx {C Function} scm_getegid () +Return an integer representing the current effective group ID. +If the system does not support effective IDs, then the real ID +is returned. @code{(provided? 'EIDs)} reports whether the +system supports effective IDs. +@end deffn + +@deffn {Scheme Procedure} setgroups vec +@deffnx {C Function} scm_setgroups (vec) +Set the current set of supplementary group IDs to the integers in the +given vector @var{vec}. The return value is unspecified. + +Generally only the superuser can set the process group IDs +(@pxref{Setting Groups, Setting the Group IDs,, libc, The GNU C +Library Reference Manual}). +@end deffn + +@deffn {Scheme Procedure} setuid id +@deffnx {C Function} scm_setuid (id) +Sets both the real and effective user IDs to the integer @var{id}, provided +the process has appropriate privileges. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setgid id +@deffnx {C Function} scm_setgid (id) +Sets both the real and effective group IDs to the integer @var{id}, provided +the process has appropriate privileges. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} seteuid id +@deffnx {C Function} scm_seteuid (id) +Sets the effective user ID to the integer @var{id}, provided the process +has appropriate privileges. If effective IDs are not supported, the +real ID is set instead---@code{(provided? 'EIDs)} reports whether the +system supports effective IDs. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setegid id +@deffnx {C Function} scm_setegid (id) +Sets the effective group ID to the integer @var{id}, provided the process +has appropriate privileges. If effective IDs are not supported, the +real ID is set instead---@code{(provided? 'EIDs)} reports whether the +system supports effective IDs. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} getpgrp +@deffnx {C Function} scm_getpgrp () +Return an integer representing the current process group ID. +This is the @acronym{POSIX} definition, not @acronym{BSD}. +@end deffn + +@deffn {Scheme Procedure} setpgid pid pgid +@deffnx {C Function} scm_setpgid (pid, pgid) +Move the process @var{pid} into the process group @var{pgid}. @var{pid} or +@var{pgid} must be integers: they can be zero to indicate the ID of the +current process. +Fails on systems that do not support job control. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setsid +@deffnx {C Function} scm_setsid () +Creates a new session. The current process becomes the session leader +and is put in a new process group. The process will be detached +from its controlling terminal if it has one. +The return value is an integer representing the new process group ID. +@end deffn + +@deffn {Scheme Procedure} getsid pid +@deffnx {C Function} scm_getsid (pid) +Returns the session ID of process @var{pid}. (The session +ID of a process is the process group ID of its session leader.) +@end deffn + +@deffn {Scheme Procedure} waitpid pid [options] +@deffnx {C Function} scm_waitpid (pid, options) +This procedure collects status information from a child process which +has terminated or (optionally) stopped. Normally it will +suspend the calling process until this can be done. If more than one +child process is eligible then one will be chosen by the operating system. + +The value of @var{pid} determines the behaviour: + +@table @asis +@item @var{pid} greater than 0 +Request status information from the specified child process. +@item @var{pid} equal to -1 or @code{WAIT_ANY} +@vindex WAIT_ANY +Request status information for any child process. +@item @var{pid} equal to 0 or @code{WAIT_MYPGRP} +@vindex WAIT_MYPGRP +Request status information for any child process in the current process +group. +@item @var{pid} less than -1 +Request status information for any child process whose process group ID +is @minus{}@var{pid}. +@end table + +The @var{options} argument, if supplied, should be the bitwise OR of the +values of zero or more of the following variables: + +@defvar WNOHANG +Return immediately even if there are no child processes to be collected. +@end defvar + +@defvar WUNTRACED +Report status information for stopped processes as well as terminated +processes. +@end defvar + +The return value is a pair containing: + +@enumerate +@item +The process ID of the child process, or 0 if @code{WNOHANG} was +specified and no process was collected. +@item +The integer status value. +@end enumerate +@end deffn + +The following three +functions can be used to decode the process status code returned +by @code{waitpid}. + +@deffn {Scheme Procedure} status:exit-val status +@deffnx {C Function} scm_status_exit_val (status) +Return the exit status value, as would be set if a process +ended normally through a call to @code{exit} or @code{_exit}, +if any, otherwise @code{#f}. +@end deffn + +@deffn {Scheme Procedure} status:term-sig status +@deffnx {C Function} scm_status_term_sig (status) +Return the signal number which terminated the process, if any, +otherwise @code{#f}. +@end deffn + +@deffn {Scheme Procedure} status:stop-sig status +@deffnx {C Function} scm_status_stop_sig (status) +Return the signal number which stopped the process, if any, +otherwise @code{#f}. +@end deffn + +@deffn {Scheme Procedure} system [cmd] +@deffnx {C Function} scm_system (cmd) +Execute @var{cmd} using the operating system's ``command +processor''. Under Unix this is usually the default shell +@code{sh}. The value returned is @var{cmd}'s exit status as +returned by @code{waitpid}, which can be interpreted using the +functions above. + +If @code{system} is called without arguments, return a boolean +indicating whether the command processor is available. +@end deffn + +@deffn {Scheme Procedure} system* arg1 arg2 @dots{} +@deffnx {C Function} scm_system_star (args) +Execute the command indicated by @var{arg1} @var{arg2} @enddots{}. The +first element must be a string indicating the command to be executed, +and the remaining items must be strings representing each of the +arguments to that command. + +This function returns the exit status of the command as provided by +@code{waitpid}. This value can be handled with @code{status:exit-val} +and the related functions. + +@code{system*} is similar to @code{system}, but accepts only one +string per-argument, and performs no shell interpretation. The +command is executed using fork and execlp. Accordingly this function +may be safer than @code{system} in situations where shell +interpretation is not required. + +Example: (system* "echo" "foo" "bar") +@end deffn + +@deffn {Scheme Procedure} quit [status] +@deffnx {Scheme Procedure} exit [status] +Terminate the current process with proper unwinding of the Scheme stack. +The exit status zero if @var{status} is not supplied. If @var{status} +is supplied, and it is an integer, that integer is used as the exit +status. If @var{status} is @code{#t} or @code{#f}, the exit status is +@var{EXIT_SUCCESS} or @var{EXIT_FAILURE}, respectively. + +The procedure @code{exit} is an alias of @code{quit}. They have the +same functionality. +@end deffn + +@defvr {Scheme Variable} EXIT_SUCCESS +@defvrx {Scheme Variable} EXIT_FAILURE +These constants represent the standard exit codes for success (zero) or +failure (one.) +@end defvr + +@deffn {Scheme Procedure} primitive-exit [status] +@deffnx {Scheme Procedure} primitive-_exit [status] +@deffnx {C Function} scm_primitive_exit (status) +@deffnx {C Function} scm_primitive__exit (status) +Terminate the current process without unwinding the Scheme stack. The +exit status is @var{status} if supplied, otherwise zero. + +@code{primitive-exit} uses the C @code{exit} function and hence runs +usual C level cleanups (flush output streams, call @code{atexit} +functions, etc, see @ref{Normal Termination,,, libc, The GNU C Library +Reference Manual})). + +@code{primitive-_exit} is the @code{_exit} system call +(@pxref{Termination Internals,,, libc, The GNU C Library Reference +Manual}). This terminates the program immediately, with neither +Scheme-level nor C-level cleanups. + +The typical use for @code{primitive-_exit} is from a child process +created with @code{primitive-fork}. For example in a Gdk program the +child process inherits the X server connection and a C-level +@code{atexit} cleanup which will close that connection. But closing +in the child would upset the protocol in the parent, so +@code{primitive-_exit} should be used to exit without that. +@end deffn + +@deffn {Scheme Procedure} execl filename arg @dots{} +@deffnx {C Function} scm_execl (filename, args) +Executes the file named by @var{filename} as a new process image. +The remaining arguments are supplied to the process; from a C program +they are accessible as the @code{argv} argument to @code{main}. +Conventionally the first @var{arg} is the same as @var{filename}. +All arguments must be strings. + +If @var{arg} is missing, @var{filename} is executed with a null +argument list, which may have system-dependent side-effects. + +This procedure is currently implemented using the @code{execv} system +call, but we call it @code{execl} because of its Scheme calling interface. +@end deffn + +@deffn {Scheme Procedure} execlp filename arg @dots{} +@deffnx {C Function} scm_execlp (filename, args) +Similar to @code{execl}, however if +@var{filename} does not contain a slash +then the file to execute will be located by searching the +directories listed in the @code{PATH} environment variable. + +This procedure is currently implemented using the @code{execvp} system +call, but we call it @code{execlp} because of its Scheme calling interface. +@end deffn + +@deffn {Scheme Procedure} execle filename env arg @dots{} +@deffnx {C Function} scm_execle (filename, env, args) +Similar to @code{execl}, but the environment of the new process is +specified by @var{env}, which must be a list of strings as returned by the +@code{environ} procedure. + +This procedure is currently implemented using the @code{execve} system +call, but we call it @code{execle} because of its Scheme calling interface. +@end deffn + +@deffn {Scheme Procedure} primitive-fork +@deffnx {C Function} scm_fork () +Creates a new ``child'' process by duplicating the current ``parent'' process. +In the child the return value is 0. In the parent the return value is +the integer process ID of the child. + +Note that it is unsafe to fork a process that has multiple threads +running, as only the thread that calls @code{primitive-fork} will +persist in the child. Any resources that other threads held, such as +locked mutexes or open file descriptors, are lost. Indeed, +@acronym{POSIX} specifies that only async-signal-safe procedures are +safe to call after a multithreaded fork, which is a very limited set. +Guile issues a warning if it detects a fork from a multi-threaded +program. + +If you are going to @code{exec} soon after forking, the procedures in +@code{(ice-9 popen)} may be useful to you, as they fork and exec within +an async-signal-safe function carefully written to ensure robust program +behavior, even in the presence of threads. @xref{Pipes}, for more. + +This procedure has been renamed from @code{fork} to avoid a naming conflict +with the scsh fork. +@end deffn + +@deffn {Scheme Procedure} nice incr +@deffnx {C Function} scm_nice (incr) +@cindex process priority +Increment the priority of the current process by @var{incr}. A higher +priority value means that the process runs less often. +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setpriority which who prio +@deffnx {C Function} scm_setpriority (which, who, prio) +@vindex PRIO_PROCESS +@vindex PRIO_PGRP +@vindex PRIO_USER +Set the scheduling priority of the process, process group +or user, as indicated by @var{which} and @var{who}. @var{which} +is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} +or @code{PRIO_USER}, and @var{who} is interpreted relative to +@var{which} (a process identifier for @code{PRIO_PROCESS}, +process group identifier for @code{PRIO_PGRP}, and a user +identifier for @code{PRIO_USER}. A zero value of @var{who} +denotes the current process, process group, or user. +@var{prio} is a value in the range [@minus{}20,20]. The default +priority is 0; lower priorities (in numerical terms) cause more +favorable scheduling. Sets the priority of all of the specified +processes. Only the super-user may lower priorities. The return +value is not specified. +@end deffn + +@deffn {Scheme Procedure} getpriority which who +@deffnx {C Function} scm_getpriority (which, who) +@vindex PRIO_PROCESS +@vindex PRIO_PGRP +@vindex PRIO_USER +Return the scheduling priority of the process, process group +or user, as indicated by @var{which} and @var{who}. @var{which} +is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} +or @code{PRIO_USER}, and @var{who} should be interpreted depending on +@var{which} (a process identifier for @code{PRIO_PROCESS}, +process group identifier for @code{PRIO_PGRP}, and a user +identifier for @code{PRIO_USER}). A zero value of @var{who} +denotes the current process, process group, or user. Return +the highest priority (lowest numerical value) of any of the +specified processes. +@end deffn + +@cindex affinity, CPU + +@deffn {Scheme Procedure} getaffinity pid +@deffnx {C Function} scm_getaffinity (pid) +Return a bitvector representing the CPU affinity mask for +process @var{pid}. Each CPU the process has affinity with +has its corresponding bit set in the returned bitvector. +The number of bits set is a good estimate of how many CPUs +Guile can use without stepping on other processes' toes. + +Currently this procedure is only defined on GNU variants +(@pxref{CPU Affinity, @code{sched_getaffinity},, libc, The +GNU C Library Reference Manual}). +@end deffn + +@deffn {Scheme Procedure} setaffinity pid mask +@deffnx {C Function} scm_setaffinity (pid, mask) +Install the CPU affinity mask @var{mask}, a bitvector, for +the process or thread with ID @var{pid}. The return value +is unspecified. + +Currently this procedure is only defined on GNU variants +(@pxref{CPU Affinity, @code{sched_setaffinity},, libc, The +GNU C Library Reference Manual}). +@end deffn + +@xref{Threads}, for information on how get the number of processors +available on a system. + + +@node Signals +@subsection Signals +@cindex signal + +The following procedures raise, handle and wait for signals. + +Scheme code signal handlers are run via an async (@pxref{Asyncs}), so +they're called in the handler's thread at the next safe opportunity. +Generally this is after any currently executing primitive procedure +finishes (which could be a long time for primitives that wait for an +external event). + +@deffn {Scheme Procedure} kill pid sig +@deffnx {C Function} scm_kill (pid, sig) +Sends a signal to the specified process or group of processes. + +@var{pid} specifies the processes to which the signal is sent: + +@table @asis +@item @var{pid} greater than 0 +The process whose identifier is @var{pid}. +@item @var{pid} equal to 0 +All processes in the current process group. +@item @var{pid} less than -1 +The process group whose identifier is -@var{pid} +@item @var{pid} equal to -1 +If the process is privileged, all processes except for some special +system processes. Otherwise, all processes with the current effective +user ID. +@end table + +@var{sig} should be specified using a variable corresponding to +the Unix symbolic name, e.g., + +@defvar SIGHUP +Hang-up signal. +@end defvar + +@defvar SIGINT +Interrupt signal. +@end defvar + +A full list of signals on the GNU system may be found in @ref{Standard +Signals,,,libc,The GNU C Library Reference Manual}. +@end deffn + +@deffn {Scheme Procedure} raise sig +@deffnx {C Function} scm_raise (sig) +Sends a specified signal @var{sig} to the current process, where +@var{sig} is as described for the @code{kill} procedure. +@end deffn + +@deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]] +@deffnx {C Function} scm_sigaction (signum, handler, flags) +@deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread) +Install or report the signal handler for a specified signal. + +@var{signum} is the signal number, which can be specified using the value +of variables such as @code{SIGINT}. + +If @var{handler} is omitted, @code{sigaction} returns a pair: the +@acronym{CAR} is the current signal hander, which will be either an +integer with the value @code{SIG_DFL} (default action) or +@code{SIG_IGN} (ignore), or the Scheme procedure which handles the +signal, or @code{#f} if a non-Scheme procedure handles the signal. +The @acronym{CDR} contains the current @code{sigaction} flags for the +handler. + +If @var{handler} is provided, it is installed as the new handler for +@var{signum}. @var{handler} can be a Scheme procedure taking one +argument, or the value of @code{SIG_DFL} (default action) or +@code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler +was installed before @code{sigaction} was first used. When a scheme +procedure has been specified, that procedure will run in the given +@var{thread}. When no thread has been given, the thread that made this +call to @code{sigaction} is used. + +@var{flags} is a @code{logior} (@pxref{Bitwise Operations}) of the +following (where provided by the system), or @code{0} for none. + +@defvar SA_NOCLDSTOP +By default, @code{SIGCHLD} is signalled when a child process stops +(ie.@: receives @code{SIGSTOP}), and when a child process terminates. +With the @code{SA_NOCLDSTOP} flag, @code{SIGCHLD} is only signalled +for termination, not stopping. + +@code{SA_NOCLDSTOP} has no effect on signals other than +@code{SIGCHLD}. +@end defvar + +@defvar SA_RESTART +If a signal occurs while in a system call, deliver the signal then +restart the system call (as opposed to returning an @code{EINTR} error +from that call). +@end defvar + +Guile handles signals asynchronously. When it receives a signal, the +synchronous signal handler just records the fact that a signal was +received and sets a flag to tell the relevant Guile thread that it has a +pending signal. When the Guile thread checks the pending-interrupt +flag, it will arrange to run the asynchronous part of the signal +handler, which is the handler attached by @code{sigaction}. + +This strategy has some perhaps-unexpected interactions with the +@code{SA_RESTART} flag, though: because the synchronous handler doesn't +do very much, and notably it doesn't run the Guile handler, it's +impossible to interrupt a thread stuck in a long-running system call via +a signal handler that is installed with @code{SA_RESTART}: the +synchronous handler just records the pending interrupt, but then the +system call resumes and Guile doesn't have a chance to actually check +the flag and run the asynchronous handler. That's just how it is. + +The return value is a pair with information about the old handler as +described above. + +This interface does not provide access to the ``signal blocking'' +facility. Maybe this is not needed, since the thread support may +provide solutions to the problem of consistent access to data +structures. +@end deffn + +@deffn {Scheme Procedure} restore-signals +@deffnx {C Function} scm_restore_signals () +Return all signal handlers to the values they had before any call to +@code{sigaction} was made. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} alarm i +@deffnx {C Function} scm_alarm (i) +Set a timer to raise a @code{SIGALRM} signal after the specified +number of seconds (an integer). It's advisable to install a signal +handler for +@code{SIGALRM} beforehand, since the default action is to terminate +the process. + +The return value indicates the time remaining for the previous alarm, +if any. The new value replaces the previous alarm. If there was +no previous alarm, the return value is zero. +@end deffn + +@deffn {Scheme Procedure} pause +@deffnx {C Function} scm_pause () +Pause the current process (thread?) until a signal arrives whose +action is to either terminate the current process or invoke a +handler procedure. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} sleep secs +@deffnx {Scheme Procedure} usleep usecs +@deffnx {C Function} scm_sleep (secs) +@deffnx {C Function} scm_usleep (usecs) +Wait the given period @var{secs} seconds or @var{usecs} microseconds +(both integers). If a signal arrives the wait stops and the return +value is the time remaining, in seconds or microseconds respectively. +If the period elapses with no signal the return is zero. + +On most systems the process scheduler is not microsecond accurate and +the actual period slept by @code{usleep} might be rounded to a system +clock tick boundary, which might be 10 milliseconds for instance. + +See @code{scm_std_sleep} and @code{scm_std_usleep} for equivalents at +the C level (@pxref{Blocking}). +@end deffn + +@deffn {Scheme Procedure} getitimer which_timer +@deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds +@deffnx {C Function} scm_getitimer (which_timer) +@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds) +Get or set the periods programmed in certain system timers. + +These timers have two settings. The first setting, the interval, is the +value at which the timer will be reset when the current timer expires. +The second is the current value of the timer, indicating when the next +expiry will be signalled. + +@var{which_timer} is one of the following values: + +@defvar ITIMER_REAL +A real-time timer, counting down elapsed real time. At zero it raises +@code{SIGALRM}. This is like @code{alarm} above, but with a higher +resolution period. +@end defvar + +@defvar ITIMER_VIRTUAL +A virtual-time timer, counting down while the current process is +actually using CPU. At zero it raises @code{SIGVTALRM}. +@end defvar + +@defvar ITIMER_PROF +A profiling timer, counting down while the process is running (like +@code{ITIMER_VIRTUAL}) and also while system calls are running on the +process's behalf. At zero it raises a @code{SIGPROF}. + +This timer is intended for profiling where a program is spending its +time (by looking where it is when the timer goes off). +@end defvar + +@code{getitimer} returns the restart timer value and its current value, +as a list containing two pairs. Each pair is a time in seconds and +microseconds: @code{((@var{interval_secs} . @var{interval_usecs}) +(@var{value_secs} . @var{value_usecs}))}. + +@code{setitimer} sets the timer values similarly, in seconds and +microseconds (which must be integers). The interval value can be zero +to have the timer run down just once. The return value is the timer's +previous setting, in the same form as @code{getitimer} returns. + +@example +(setitimer ITIMER_REAL + 5 500000 ;; Raise SIGALRM every 5.5 seconds + 2 0) ;; with the first SIGALRM in 2 seconds +@end example + +Although the timers are programmed in microseconds, the actual +accuracy might not be that high. + +Note that @code{ITIMER_PROF} and @code{ITIMER_VIRTUAL} are not +functional on all platforms and may always error when called. +@code{(provided? 'ITIMER_PROF)} and @code{(provided? 'ITIMER_VIRTUAL)} +can be used to test if the those itimers are supported on the given +host. @code{ITIMER_REAL} is supported on all platforms that support +@code{setitimer}. +@end deffn + + +@node Terminals and Ptys +@subsection Terminals and Ptys + +@deffn {Scheme Procedure} isatty? port +@deffnx {C Function} scm_isatty_p (port) +@cindex terminal +Return @code{#t} if @var{port} is using a serial non--file +device, otherwise @code{#f}. +@end deffn + +@deffn {Scheme Procedure} ttyname port +@deffnx {C Function} scm_ttyname (port) +@cindex terminal +Return a string with the name of the serial terminal device +underlying @var{port}. +@end deffn + +@deffn {Scheme Procedure} ctermid +@deffnx {C Function} scm_ctermid () +@cindex terminal +Return a string containing the file name of the controlling +terminal for the current process. +@end deffn + +@deffn {Scheme Procedure} tcgetpgrp port +@deffnx {C Function} scm_tcgetpgrp (port) +@cindex process group +Return the process group ID of the foreground process group +associated with the terminal open on the file descriptor +underlying @var{port}. + +If there is no foreground process group, the return value is a +number greater than 1 that does not match the process group ID +of any existing process group. This can happen if all of the +processes in the job that was formerly the foreground job have +terminated, and no other job has yet been moved into the +foreground. +@end deffn + +@deffn {Scheme Procedure} tcsetpgrp port pgid +@deffnx {C Function} scm_tcsetpgrp (port, pgid) +@cindex process group +Set the foreground process group ID for the terminal used by the file +descriptor underlying @var{port} to the integer @var{pgid}. +The calling process +must be a member of the same session as @var{pgid} and must have the same +controlling terminal. The return value is unspecified. +@end deffn + +@node Pipes +@subsection Pipes +@cindex pipe + +The following procedures are similar to the @code{popen} and +@code{pclose} system routines. The code is in a separate ``popen'' +module@footnote{This module is only available on systems where the +@code{popen} feature is provided (@pxref{Common Feature Symbols}).}: + +@lisp +(use-modules (ice-9 popen)) +@end lisp + +@findex popen +@deffn {Scheme Procedure} open-pipe command mode +@deffnx {Scheme Procedure} open-pipe* mode prog [args...] +Execute a command in a subprocess, with a pipe to it or from it, or +with pipes in both directions. + +@code{open-pipe} runs the shell @var{command} using @samp{/bin/sh -c}. +@code{open-pipe*} executes @var{prog} directly, with the optional +@var{args} arguments (all strings). + +@var{mode} should be one of the following values. @code{OPEN_READ} is +an input pipe, ie.@: to read from the subprocess. @code{OPEN_WRITE} +is an output pipe, ie.@: to write to it. + +@defvar OPEN_READ +@defvarx OPEN_WRITE +@defvarx OPEN_BOTH +@end defvar + +For an input pipe, the child's standard output is the pipe and +standard input is inherited from @code{current-input-port}. For an +output pipe, the child's standard input is the pipe and standard +output is inherited from @code{current-output-port}. In all cases +the child's standard error is inherited from +@code{current-error-port} (@pxref{Default Ports}). + +If those @code{current-X-ports} are not files of some kind, and hence +don't have file descriptors for the child, then @file{/dev/null} is +used instead. + +Care should be taken with @code{OPEN_BOTH}, a deadlock will occur if +both parent and child are writing, and waiting until the write completes +before doing any reading. Each direction has @code{PIPE_BUF} bytes of +buffering (@pxref{Buffering}), which will be enough for small writes, +but not for say putting a big file through a filter. +@end deffn + +@deffn {Scheme Procedure} open-input-pipe command +Equivalent to @code{open-pipe} with mode @code{OPEN_READ}. + +@lisp +(let* ((port (open-input-pipe "date --utc")) + (str (read-line port))) + (close-pipe port) + str) +@result{} "Mon Mar 11 20:10:44 UTC 2002" +@end lisp +@end deffn + +@deffn {Scheme Procedure} open-output-pipe command +Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}. + +@lisp +(let ((port (open-output-pipe "lpr"))) + (display "Something for the line printer.\n" port) + (if (not (eqv? 0 (status:exit-val (close-pipe port)))) + (error "Cannot print"))) +@end lisp +@end deffn + +@deffn {Scheme Procedure} open-input-output-pipe command +Equivalent to @code{open-pipe} with mode @code{OPEN_BOTH}. +@end deffn + +@findex pclose +@deffn {Scheme Procedure} close-pipe port +Close a pipe created by @code{open-pipe}, wait for the process to +terminate, and return the wait status code. The status is as per +@code{waitpid} and can be decoded with @code{status:exit-val} etc +(@pxref{Processes}) +@end deffn + +@sp 1 +@code{waitpid WAIT_ANY} should not be used when pipes are open, since +it can reap a pipe's child process, causing an error from a subsequent +@code{close-pipe}. + +@code{close-port} (@pxref{Ports}) can close a pipe, but it doesn't reap +the child process. + +The garbage collector will close a pipe no longer in use, and reap the +child process with @code{waitpid}. If the child hasn't yet terminated +the garbage collector doesn't block, but instead checks again in the +next GC. + +Many systems have per-user and system-wide limits on the number of +processes, and a system-wide limit on the number of pipes, so pipes +should be closed explicitly when no longer needed, rather than letting +the garbage collector pick them up at some later time. + + +@node Networking +@subsection Networking +@cindex network + +@menu +* Network Address Conversion:: +* Network Databases:: +* Network Socket Address:: +* Network Sockets and Communication:: +* Internet Socket Examples:: +@end menu + +@node Network Address Conversion +@subsubsection Network Address Conversion +@cindex network address + +This section describes procedures which convert internet addresses +between numeric and string formats. + +@subsubheading IPv4 Address Conversion +@cindex IPv4 + +An IPv4 Internet address is a 4-byte value, represented in Guile as an +integer in host byte order, so that say ``0.0.0.1'' is 1, or +``1.0.0.0'' is 16777216. + +Some underlying C functions use network byte order for addresses, +Guile converts as necessary so that at the Scheme level its host byte +order everywhere. + +@defvar INADDR_ANY +For a server, this can be used with @code{bind} (@pxref{Network +Sockets and Communication}) to allow connections from any interface on +the machine. +@end defvar + +@defvar INADDR_BROADCAST +The broadcast address on the local network. +@end defvar + +@defvar INADDR_LOOPBACK +The address of the local host using the loopback device, ie.@: +@samp{127.0.0.1}. +@end defvar + +@c INADDR_NONE is defined in the code, but serves no purpose. +@c inet_addr() returns it as an error indication, but that function +@c isn't provided, for the good reason that inet_aton() does the same +@c job and gives an unambiguous error indication. (INADDR_NONE is a +@c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.) +@c +@c @defvar INADDR_NONE +@c No address. +@c @end defvar + +@deffn {Scheme Procedure} inet-aton address +@deffnx {C Function} scm_inet_aton (address) +This function is deprecated in favor of @code{inet-pton}. + +Convert an IPv4 Internet address from printable string +(dotted decimal notation) to an integer. E.g., + +@lisp +(inet-aton "127.0.0.1") @result{} 2130706433 +@end lisp +@end deffn + +@deffn {Scheme Procedure} inet-ntoa inetid +@deffnx {C Function} scm_inet_ntoa (inetid) +This function is deprecated in favor of @code{inet-ntop}. + +Convert an IPv4 Internet address to a printable +(dotted decimal notation) string. E.g., + +@lisp +(inet-ntoa 2130706433) @result{} "127.0.0.1" +@end lisp +@end deffn + +@deffn {Scheme Procedure} inet-netof address +@deffnx {C Function} scm_inet_netof (address) +Return the network number part of the given IPv4 +Internet address. E.g., + +@lisp +(inet-netof 2130706433) @result{} 127 +@end lisp +@end deffn + +@deffn {Scheme Procedure} inet-lnaof address +@deffnx {C Function} scm_lnaof (address) +Return the local-address-with-network part of the given +IPv4 Internet address, using the obsolete class A/B/C system. +E.g., + +@lisp +(inet-lnaof 2130706433) @result{} 1 +@end lisp +@end deffn + +@deffn {Scheme Procedure} inet-makeaddr net lna +@deffnx {C Function} scm_inet_makeaddr (net, lna) +Make an IPv4 Internet address by combining the network number +@var{net} with the local-address-within-network number +@var{lna}. E.g., + +@lisp +(inet-makeaddr 127 1) @result{} 2130706433 +@end lisp +@end deffn + +@subsubheading IPv6 Address Conversion +@cindex IPv6 + +An IPv6 Internet address is a 16-byte value, represented in Guile as +an integer in host byte order, so that say ``::1'' is 1. + +@deffn {Scheme Procedure} inet-ntop family address +@deffnx {C Function} scm_inet_ntop (family, address) +Convert a network address from an integer to a printable string. +@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g., + +@lisp +(inet-ntop AF_INET 2130706433) @result{} "127.0.0.1" +(inet-ntop AF_INET6 (- (expt 2 128) 1)) + @result{} "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff" +@end lisp +@end deffn + +@deffn {Scheme Procedure} inet-pton family address +@deffnx {C Function} scm_inet_pton (family, address) +Convert a string containing a printable network address to an integer +address. @var{family} can be @code{AF_INET} or @code{AF_INET6}. +E.g., + +@lisp +(inet-pton AF_INET "127.0.0.1") @result{} 2130706433 +(inet-pton AF_INET6 "::1") @result{} 1 +@end lisp +@end deffn + + +@node Network Databases +@subsubsection Network Databases +@cindex network database + +This section describes procedures which query various network databases. +Care should be taken when using the database routines since they are not +reentrant. + +@subsubheading @code{getaddrinfo} + +@cindex @code{addrinfo} object type +@cindex host name lookup +@cindex service name lookup + +The @code{getaddrinfo} procedure maps host and service names to socket addresses +and associated information in a protocol-independent way. + +@deffn {Scheme Procedure} getaddrinfo name service [hint_flags [hint_family [hint_socktype [hint_protocol]]]] +@deffnx {C Function} scm_getaddrinfo (name, service, hint_flags, hint_family, hint_socktype, hint_protocol) +Return a list of @code{addrinfo} structures containing +a socket address and associated information for host @var{name} +and/or @var{service} to be used in creating a socket with +which to address the specified service. + +@example +(let* ((ai (car (getaddrinfo "www.gnu.org" "http"))) + (s (socket (addrinfo:fam ai) (addrinfo:socktype ai) + (addrinfo:protocol ai)))) + (connect s (addrinfo:addr ai)) + s) +@end example + +When @var{service} is omitted or is @code{#f}, return +network-level addresses for @var{name}. When @var{name} +is @code{#f} @var{service} must be provided and service +locations local to the caller are returned. + +Additional hints can be provided. When specified, +@var{hint_flags} should be a bitwise-or of zero or more +constants among the following: + +@table @code +@item AI_PASSIVE +Socket address is intended for @code{bind}. + +@item AI_CANONNAME +Request for canonical host name, available via +@code{addrinfo:canonname}. This makes sense mainly when +DNS lookups are involved. + +@item AI_NUMERICHOST +Specifies that @var{name} is a numeric host address string +(e.g., @code{"127.0.0.1"}), meaning that name resolution +will not be used. + +@item AI_NUMERICSERV +Likewise, specifies that @var{service} is a numeric port +string (e.g., @code{"80"}). + +@item AI_ADDRCONFIG +Return only addresses configured on the local system It is +highly recommended to provide this flag when the returned +socket addresses are to be used to make connections; +otherwise, some of the returned addresses could be unreachable +or use a protocol that is not supported. + +@item AI_V4MAPPED +When looking up IPv6 addresses, return mapped IPv4 addresses if +there is no IPv6 address available at all. + +@item AI_ALL +If this flag is set along with @code{AI_V4MAPPED} when looking up IPv6 +addresses, return all IPv6 addresses as well as all IPv4 addresses, the latter +mapped to IPv6 format. +@end table + +When given, @var{hint_family} should specify the requested +address family, e.g., @code{AF_INET6}. Similarly, +@var{hint_socktype} should specify the requested socket type +(e.g., @code{SOCK_DGRAM}), and @var{hint_protocol} should +specify the requested protocol (its value is interpreted +as in calls to @code{socket}). + +On error, an exception with key @code{getaddrinfo-error} is +thrown, with an error code (an integer) as its argument: + +@example +(catch 'getaddrinfo-error + (lambda () + (getaddrinfo "www.gnu.org" "gopher")) + (lambda (key errcode) + (cond ((= errcode EAI_SERVICE) + (display "doesn't know about Gopher!\n")) + ((= errcode EAI_NONAME) + (display "www.gnu.org not found\\n")) + (else + (format #t "something wrong: ~a\n" + (gai-strerror errcode)))))) +@end example + +Error codes are: + +@table @code +@item EAI_AGAIN +The name or service could not be resolved at this time. Future +attempts may succeed. + +@item EAI_BADFLAGS +@var{hint_flags} contains an invalid value. + +@item EAI_FAIL +A non-recoverable error occurred when attempting to +resolve the name. + +@item EAI_FAMILY +@var{hint_family} was not recognized. + +@item EAI_NONAME +Either @var{name} does not resolve for the supplied parameters, +or neither @var{name} nor @var{service} were supplied. + +@item EAI_NODATA +This non-POSIX error code can be returned on some systems (GNU +and Darwin, at least), for example when @var{name} is known +but requests that were made turned out no data. Error handling +code should be prepared to handle it when it is defined. + +@item EAI_SERVICE +@var{service} was not recognized for the specified socket type. + +@item EAI_SOCKTYPE +@var{hint_socktype} was not recognized. + +@item EAI_SYSTEM +A system error occurred. In C, the error code can be found in +@code{errno}; this value is not accessible from Scheme, but in +practice it provides little information about the actual error +cause. +@c See <http://bugs.gnu.org/13958>. +@end table + +Users are encouraged to read the +@url{http://www.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html, +"POSIX specification} for more details. +@end deffn + +The following procedures take an @code{addrinfo} object as returned by +@code{getaddrinfo}: + +@deffn {Scheme Procedure} addrinfo:flags ai +Return flags for @var{ai} as a bitwise or of @code{AI_} values (see above). +@end deffn + +@deffn {Scheme Procedure} addrinfo:fam ai +Return the address family of @var{ai} (a @code{AF_} value). +@end deffn + +@deffn {Scheme Procedure} addrinfo:socktype ai +Return the socket type for @var{ai} (a @code{SOCK_} value). +@end deffn + +@deffn {Scheme Procedure} addrinfo:protocol ai +Return the protocol of @var{ai}. +@end deffn + +@deffn {Scheme Procedure} addrinfo:addr ai +Return the socket address associated with @var{ai} as a @code{sockaddr} +object (@pxref{Network Socket Address}). +@end deffn + +@deffn {Scheme Procedure} addrinfo:canonname ai +Return a string for the canonical name associated with @var{ai} if +the @code{AI_CANONNAME} flag was supplied. +@end deffn + +@subsubheading The Host Database +@cindex @file{/etc/hosts} +@cindex network database + +A @dfn{host object} is a structure that represents what is known about a +network host, and is the usual way of representing a system's network +identity inside software. + +The following functions accept a host object and return a selected +component: + +@deffn {Scheme Procedure} hostent:name host +The ``official'' hostname for @var{host}. +@end deffn +@deffn {Scheme Procedure} hostent:aliases host +A list of aliases for @var{host}. +@end deffn +@deffn {Scheme Procedure} hostent:addrtype host +The host address type, one of the @code{AF} constants, such as +@code{AF_INET} or @code{AF_INET6}. +@end deffn +@deffn {Scheme Procedure} hostent:length host +The length of each address for @var{host}, in bytes. +@end deffn +@deffn {Scheme Procedure} hostent:addr-list host +The list of network addresses associated with @var{host}. For +@code{AF_INET} these are integer IPv4 address (@pxref{Network Address +Conversion}). +@end deffn + +The following procedures can be used to search the host database. However, +@code{getaddrinfo} should be preferred over them since it's more generic and +thread-safe. + +@deffn {Scheme Procedure} gethost [host] +@deffnx {Scheme Procedure} gethostbyname hostname +@deffnx {Scheme Procedure} gethostbyaddr address +@deffnx {C Function} scm_gethost (host) +Look up a host by name or address, returning a host object. The +@code{gethost} procedure will accept either a string name or an integer +address; if given no arguments, it behaves like @code{gethostent} (see +below). If a name or address is supplied but the address can not be +found, an error will be thrown to one of the keys: +@code{host-not-found}, @code{try-again}, @code{no-recovery} or +@code{no-data}, corresponding to the equivalent @code{h_error} values. +Unusual conditions may result in errors thrown to the +@code{system-error} or @code{misc_error} keys. + +@lisp +(gethost "www.gnu.org") +@result{} #("www.gnu.org" () 2 4 (3353880842)) + +(gethostbyname "www.emacs.org") +@result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978)) +@end lisp +@end deffn + +The following procedures may be used to step through the host +database from beginning to end. + +@deffn {Scheme Procedure} sethostent [stayopen] +Initialize an internal stream from which host objects may be read. This +procedure must be called before any calls to @code{gethostent}, and may +also be called afterward to reset the host entry stream. If +@var{stayopen} is supplied and is not @code{#f}, the database is not +closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls, +possibly giving an efficiency gain. +@end deffn + +@deffn {Scheme Procedure} gethostent +Return the next host object from the host database, or @code{#f} if +there are no more hosts to be found (or an error has been encountered). +This procedure may not be used before @code{sethostent} has been called. +@end deffn + +@deffn {Scheme Procedure} endhostent +Close the stream used by @code{gethostent}. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} sethost [stayopen] +@deffnx {C Function} scm_sethost (stayopen) +If @var{stayopen} is omitted, this is equivalent to @code{endhostent}. +Otherwise it is equivalent to @code{sethostent stayopen}. +@end deffn + +@subsubheading The Network Database +@cindex network database + +The following functions accept an object representing a network +and return a selected component: + +@deffn {Scheme Procedure} netent:name net +The ``official'' network name. +@end deffn +@deffn {Scheme Procedure} netent:aliases net +A list of aliases for the network. +@end deffn +@deffn {Scheme Procedure} netent:addrtype net +The type of the network number. Currently, this returns only +@code{AF_INET}. +@end deffn +@deffn {Scheme Procedure} netent:net net +The network number. +@end deffn + +The following procedures are used to search the network database: + +@deffn {Scheme Procedure} getnet [net] +@deffnx {Scheme Procedure} getnetbyname net-name +@deffnx {Scheme Procedure} getnetbyaddr net-number +@deffnx {C Function} scm_getnet (net) +Look up a network by name or net number in the network database. The +@var{net-name} argument must be a string, and the @var{net-number} +argument must be an integer. @code{getnet} will accept either type of +argument, behaving like @code{getnetent} (see below) if no arguments are +given. +@end deffn + +The following procedures may be used to step through the network +database from beginning to end. + +@deffn {Scheme Procedure} setnetent [stayopen] +Initialize an internal stream from which network objects may be read. This +procedure must be called before any calls to @code{getnetent}, and may +also be called afterward to reset the net entry stream. If +@var{stayopen} is supplied and is not @code{#f}, the database is not +closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls, +possibly giving an efficiency gain. +@end deffn + +@deffn {Scheme Procedure} getnetent +Return the next entry from the network database. +@end deffn + +@deffn {Scheme Procedure} endnetent +Close the stream used by @code{getnetent}. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setnet [stayopen] +@deffnx {C Function} scm_setnet (stayopen) +If @var{stayopen} is omitted, this is equivalent to @code{endnetent}. +Otherwise it is equivalent to @code{setnetent stayopen}. +@end deffn + +@subsubheading The Protocol Database +@cindex @file{/etc/protocols} +@cindex protocols +@cindex network protocols + +The following functions accept an object representing a protocol +and return a selected component: + +@deffn {Scheme Procedure} protoent:name protocol +The ``official'' protocol name. +@end deffn +@deffn {Scheme Procedure} protoent:aliases protocol +A list of aliases for the protocol. +@end deffn +@deffn {Scheme Procedure} protoent:proto protocol +The protocol number. +@end deffn + +The following procedures are used to search the protocol database: + +@deffn {Scheme Procedure} getproto [protocol] +@deffnx {Scheme Procedure} getprotobyname name +@deffnx {Scheme Procedure} getprotobynumber number +@deffnx {C Function} scm_getproto (protocol) +Look up a network protocol by name or by number. @code{getprotobyname} +takes a string argument, and @code{getprotobynumber} takes an integer +argument. @code{getproto} will accept either type, behaving like +@code{getprotoent} (see below) if no arguments are supplied. +@end deffn + +The following procedures may be used to step through the protocol +database from beginning to end. + +@deffn {Scheme Procedure} setprotoent [stayopen] +Initialize an internal stream from which protocol objects may be read. This +procedure must be called before any calls to @code{getprotoent}, and may +also be called afterward to reset the protocol entry stream. If +@var{stayopen} is supplied and is not @code{#f}, the database is not +closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls, +possibly giving an efficiency gain. +@end deffn + +@deffn {Scheme Procedure} getprotoent +Return the next entry from the protocol database. +@end deffn + +@deffn {Scheme Procedure} endprotoent +Close the stream used by @code{getprotoent}. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setproto [stayopen] +@deffnx {C Function} scm_setproto (stayopen) +If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}. +Otherwise it is equivalent to @code{setprotoent stayopen}. +@end deffn + +@subsubheading The Service Database +@cindex @file{/etc/services} +@cindex services +@cindex network services + +The following functions accept an object representing a service +and return a selected component: + +@deffn {Scheme Procedure} servent:name serv +The ``official'' name of the network service. +@end deffn +@deffn {Scheme Procedure} servent:aliases serv +A list of aliases for the network service. +@end deffn +@deffn {Scheme Procedure} servent:port serv +The Internet port used by the service. +@end deffn +@deffn {Scheme Procedure} servent:proto serv +The protocol used by the service. A service may be listed many times +in the database under different protocol names. +@end deffn + +The following procedures are used to search the service database: + +@deffn {Scheme Procedure} getserv [name [protocol]] +@deffnx {Scheme Procedure} getservbyname name protocol +@deffnx {Scheme Procedure} getservbyport port protocol +@deffnx {C Function} scm_getserv (name, protocol) +Look up a network service by name or by service number, and return a +network service object. The @var{protocol} argument specifies the name +of the desired protocol; if the protocol found in the network service +database does not match this name, a system error is signalled. + +The @code{getserv} procedure will take either a service name or number +as its first argument; if given no arguments, it behaves like +@code{getservent} (see below). + +@lisp +(getserv "imap" "tcp") +@result{} #("imap2" ("imap") 143 "tcp") + +(getservbyport 88 "udp") +@result{} #("kerberos" ("kerberos5" "krb5") 88 "udp") +@end lisp +@end deffn + +The following procedures may be used to step through the service +database from beginning to end. + +@deffn {Scheme Procedure} setservent [stayopen] +Initialize an internal stream from which service objects may be read. This +procedure must be called before any calls to @code{getservent}, and may +also be called afterward to reset the service entry stream. If +@var{stayopen} is supplied and is not @code{#f}, the database is not +closed by subsequent @code{getservbyname} or @code{getservbyport} calls, +possibly giving an efficiency gain. +@end deffn + +@deffn {Scheme Procedure} getservent +Return the next entry from the services database. +@end deffn + +@deffn {Scheme Procedure} endservent +Close the stream used by @code{getservent}. The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} setserv [stayopen] +@deffnx {C Function} scm_setserv (stayopen) +If @var{stayopen} is omitted, this is equivalent to @code{endservent}. +Otherwise it is equivalent to @code{setservent stayopen}. +@end deffn + + +@node Network Socket Address +@subsubsection Network Socket Address +@cindex socket address +@cindex network socket address +@tpindex Socket address + +A @dfn{socket address} object identifies a socket endpoint for +communication. In the case of @code{AF_INET} for instance, the socket +address object comprises the host address (or interface on the host) +and a port number which specifies a particular open socket in a +running client or server process. A socket address object can be +created with, + +@deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port +@deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]] +@deffnx {Scheme Procedure} make-socket-address AF_UNIX path +@deffnx {C Function} scm_make_socket_address (family, address, arglist) +Return a new socket address object. The first argument is the address +family, one of the @code{AF} constants, then the arguments vary +according to the family. + +For @code{AF_INET} the arguments are an IPv4 network address number +(@pxref{Network Address Conversion}), and a port number. + +For @code{AF_INET6} the arguments are an IPv6 network address number +and a port number. Optional @var{flowinfo} and @var{scopeid} +arguments may be given (both integers, default 0). + +For @code{AF_UNIX} the argument is a filename (a string). + +The C function @code{scm_make_socket_address} takes the @var{family} +and @var{address} arguments directly, then @var{arglist} is a list of +further arguments, being the port for IPv4, port and optional flowinfo +and scopeid for IPv6, or the empty list @code{SCM_EOL} for Unix +domain. +@end deffn + +@noindent +The following functions access the fields of a socket address object, + +@deffn {Scheme Procedure} sockaddr:fam sa +Return the address family from socket address object @var{sa}. This +is one of the @code{AF} constants (e.g.@: @code{AF_INET}). +@end deffn + +@deffn {Scheme Procedure} sockaddr:path sa +For an @code{AF_UNIX} socket address object @var{sa}, return the +filename. +@end deffn + +@deffn {Scheme Procedure} sockaddr:addr sa +For an @code{AF_INET} or @code{AF_INET6} socket address object +@var{sa}, return the network address number. +@end deffn + +@deffn {Scheme Procedure} sockaddr:port sa +For an @code{AF_INET} or @code{AF_INET6} socket address object +@var{sa}, return the port number. +@end deffn + +@deffn {Scheme Procedure} sockaddr:flowinfo sa +For an @code{AF_INET6} socket address object @var{sa}, return the +flowinfo value. +@end deffn + +@deffn {Scheme Procedure} sockaddr:scopeid sa +For an @code{AF_INET6} socket address object @var{sa}, return the +scope ID value. +@end deffn + +@tpindex @code{struct sockaddr} +@tpindex @code{sockaddr} +The functions below convert to and from the C @code{struct sockaddr} +(@pxref{Address Formats,,, libc, The GNU C Library Reference Manual}). +That structure is a generic type, an application can cast to or from +@code{struct sockaddr_in}, @code{struct sockaddr_in6} or @code{struct +sockaddr_un} according to the address family. + +In a @code{struct sockaddr} taken or returned, the byte ordering in +the fields follows the C conventions (@pxref{Byte Order,, Byte Order +Conversion, libc, The GNU C Library Reference Manual}). This means +network byte order for @code{AF_INET} host address +(@code{sin_addr.s_addr}) and port number (@code{sin_port}), and +@code{AF_INET6} port number (@code{sin6_port}). But at the Scheme +level these values are taken or returned in host byte order, so the +port is an ordinary integer, and the host address likewise is an +ordinary integer (as described in @ref{Network Address Conversion}). + +@deftypefn {C Function} {struct sockaddr *} scm_c_make_socket_address (SCM family, SCM address, SCM args, size_t *outsize) +Return a newly-@code{malloc}ed @code{struct sockaddr} created from +arguments like those taken by @code{scm_make_socket_address} above. + +The size (in bytes) of the @code{struct sockaddr} return is stored +into @code{*@var{outsize}}. An application must call @code{free} to +release the returned structure when no longer required. +@end deftypefn + +@deftypefn {C Function} SCM scm_from_sockaddr (const struct sockaddr *address, unsigned address_size) +Return a Scheme socket address object from the C @var{address} +structure. @var{address_size} is the size in bytes of @var{address}. +@end deftypefn + +@deftypefn {C Function} {struct sockaddr *} scm_to_sockaddr (SCM address, size_t *address_size) +Return a newly-@code{malloc}ed @code{struct sockaddr} from a Scheme +level socket address object. + +The size (in bytes) of the @code{struct sockaddr} return is stored +into @code{*@var{outsize}}. An application must call @code{free} to +release the returned structure when no longer required. +@end deftypefn + + +@node Network Sockets and Communication +@subsubsection Network Sockets and Communication +@cindex socket +@cindex network socket + +Socket ports can be created using @code{socket} and @code{socketpair}. +The ports are initially unbuffered, to make reading and writing to the +same port more reliable. A buffer can be added to the port using +@code{setvbuf} (@pxref{Buffering}). + +Most systems have limits on how many files and sockets can be open, so +it's strongly recommended that socket ports be closed explicitly when +no longer required (@pxref{Ports}). + +Some of the underlying C functions take values in network byte order, +but the convention in Guile is that at the Scheme level everything is +ordinary host byte order and conversions are made automatically where +necessary. + +@deffn {Scheme Procedure} socket family style proto +@deffnx {C Function} scm_socket (family, style, proto) +Return a new socket port of the type specified by @var{family}, +@var{style} and @var{proto}. All three parameters are integers. The +possible values for @var{family} are as follows, where supported by +the system, + +@defvar PF_UNIX +@defvarx PF_INET +@defvarx PF_INET6 +@end defvar + +The possible values for @var{style} are as follows, again where +supported by the system, + +@defvar SOCK_STREAM +@defvarx SOCK_DGRAM +@defvarx SOCK_RAW +@defvarx SOCK_RDM +@defvarx SOCK_SEQPACKET +@end defvar + +@var{proto} can be obtained from a protocol name using +@code{getprotobyname} (@pxref{Network Databases}). A value of zero +means the default protocol, which is usually right. + +A socket cannot by used for communication until it has been connected +somewhere, usually with either @code{connect} or @code{accept} below. +@end deffn + +@deffn {Scheme Procedure} socketpair family style proto +@deffnx {C Function} scm_socketpair (family, style, proto) +Return a pair, the @code{car} and @code{cdr} of which are two unnamed +socket ports connected to each other. The connection is full-duplex, +so data can be transferred in either direction between the two. + +@var{family}, @var{style} and @var{proto} are as per @code{socket} +above. But many systems only support socket pairs in the +@code{PF_UNIX} family. Zero is likely to be the only meaningful value +for @var{proto}. +@end deffn + +@deffn {Scheme Procedure} getsockopt sock level optname +@deffnx {Scheme Procedure} setsockopt sock level optname value +@deffnx {C Function} scm_getsockopt (sock, level, optname) +@deffnx {C Function} scm_setsockopt (sock, level, optname, value) +Get or set an option on socket port @var{sock}. @code{getsockopt} +returns the current value. @code{setsockopt} sets a value and the +return is unspecified. + +@var{level} is an integer specifying a protocol layer, either +@code{SOL_SOCKET} for socket level options, or a protocol number from +the @code{IPPROTO} constants or @code{getprotoent} (@pxref{Network +Databases}). + +@defvar SOL_SOCKET +@defvarx IPPROTO_IP +@defvarx IPPROTO_TCP +@defvarx IPPROTO_UDP +@end defvar + +@var{optname} is an integer specifying an option within the protocol +layer. + +For @code{SOL_SOCKET} level the following @var{optname}s are defined +(when provided by the system). For their meaning see +@ref{Socket-Level Options,,, libc, The GNU C Library Reference +Manual}, or @command{man 7 socket}. + +@defvar SO_DEBUG +@defvarx SO_REUSEADDR +@defvarx SO_STYLE +@defvarx SO_TYPE +@defvarx SO_ERROR +@defvarx SO_DONTROUTE +@defvarx SO_BROADCAST +@defvarx SO_SNDBUF +@defvarx SO_RCVBUF +@defvarx SO_KEEPALIVE +@defvarx SO_OOBINLINE +@defvarx SO_NO_CHECK +@defvarx SO_PRIORITY +@defvarx SO_REUSEPORT +The @var{value} taken or returned is an integer. +@end defvar + +@defvar SO_LINGER +The @var{value} taken or returned is a pair of integers +@code{(@var{ENABLE} . @var{TIMEOUT})}. On old systems without timeout +support (ie.@: without @code{struct linger}), only @var{ENABLE} has an +effect but the value in Guile is always a pair. +@end defvar + +@c Note that we refer only to ``man ip'' here. On GNU/Linux it's +@c ``man 7 ip'' but on NetBSD it's ``man 4 ip''. +@c +For IP level (@code{IPPROTO_IP}) the following @var{optname}s are +defined (when provided by the system). See @command{man ip} for what +they mean. + +@defvar IP_MULTICAST_IF +This sets the source interface used by multicast traffic. +@end defvar + +@defvar IP_MULTICAST_TTL +This sets the default TTL for multicast traffic. This defaults +to 1 and should be increased to allow traffic to pass beyond the +local network. +@end defvar + +@defvar IP_ADD_MEMBERSHIP +@defvarx IP_DROP_MEMBERSHIP +These can be used only with @code{setsockopt}, not @code{getsockopt}. +@var{value} is a pair @code{(@var{MULTIADDR} . @var{INTERFACEADDR})} +of integer IPv4 addresses (@pxref{Network Address Conversion}). +@var{MULTIADDR} is a multicast address to be added to or dropped from +the interface @var{INTERFACEADDR}. @var{INTERFACEADDR} can be +@code{INADDR_ANY} to have the system select the interface. +@var{INTERFACEADDR} can also be an interface index number, on systems +supporting that. +@end defvar +@end deffn + +For @code{IPPROTO_TCP} level the following @var{optname}s are defined +(when provided by the system). For their meaning see @command{man 7 +tcp}. + +@defvar TCP_NODELAY +@defvarx TCP_CORK +The @var{value} taken or returned is an integer. +@end defvar + +@deffn {Scheme Procedure} shutdown sock how +@deffnx {C Function} scm_shutdown (sock, how) +Sockets can be closed simply by using @code{close-port}. The +@code{shutdown} procedure allows reception or transmission on a +connection to be shut down individually, according to the parameter +@var{how}: + +@table @asis +@item 0 +Stop receiving data for this socket. If further data arrives, reject it. +@item 1 +Stop trying to transmit data from this socket. Discard any +data waiting to be sent. Stop looking for acknowledgement of +data already sent; don't retransmit it if it is lost. +@item 2 +Stop both reception and transmission. +@end table + +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} connect sock sockaddr +@deffnx {Scheme Procedure} connect sock AF_INET ipv4addr port +@deffnx {Scheme Procedure} connect sock AF_INET6 ipv6addr port [flowinfo [scopeid]] +@deffnx {Scheme Procedure} connect sock AF_UNIX path +@deffnx {C Function} scm_connect (sock, fam, address, args) +Initiate a connection on socket port @var{sock} to a given address. The +destination is either a socket address object, or arguments the same as +@code{make-socket-address} would take to make such an object +(@pxref{Network Socket Address}). Return true unless the socket was +configured as non-blocking and the connection could not be made +immediately. + +@example +(connect sock AF_INET INADDR_LOOPBACK 23) +(connect sock (make-socket-address AF_INET INADDR_LOOPBACK 23)) +@end example +@end deffn + +@deffn {Scheme Procedure} bind sock sockaddr +@deffnx {Scheme Procedure} bind sock AF_INET ipv4addr port +@deffnx {Scheme Procedure} bind sock AF_INET6 ipv6addr port [flowinfo [scopeid]] +@deffnx {Scheme Procedure} bind sock AF_UNIX path +@deffnx {C Function} scm_bind (sock, fam, address, args) +Bind socket port @var{sock} to the given address. The address is +either a socket address object, or arguments the same as +@code{make-socket-address} would take to make such an object +(@pxref{Network Socket Address}). The return value is unspecified. + +Generally a socket is only explicitly bound to a particular address +when making a server, i.e.@: to listen on a particular port. For an +outgoing connection the system will assign a local address +automatically, if not already bound. + +@example +(bind sock AF_INET INADDR_ANY 12345) +(bind sock (make-socket-address AF_INET INADDR_ANY 12345)) +@end example +@end deffn + +@deffn {Scheme Procedure} listen sock backlog +@deffnx {C Function} scm_listen (sock, backlog) +Enable @var{sock} to accept connection +requests. @var{backlog} is an integer specifying +the maximum length of the queue for pending connections. +If the queue fills, new clients will fail to connect until +the server calls @code{accept} to accept a connection from +the queue. + +The return value is unspecified. +@end deffn + +@deffn {Scheme Procedure} accept sock [flags] +@deffnx {C Function} scm_accept (sock) +Accept a connection from socket port @var{sock} which has been enabled +for listening with @code{listen} above. + +If there are no incoming connections in the queue, there are two +possible behaviors, depending on whether @var{sock} has been configured +for non-blocking operation or not: + +@itemize +@item +If there is no connection waiting and the socket was set to non-blocking +mode with the @code{O_NONBLOCK} port option (@pxref{Ports and File +Descriptors,@code{fcntl}}), return @code{#f} directly. + +@item +Otherwise wait until a connection is available. +@end itemize + +The return value is a pair. The @code{car} is a new socket port, +connected and ready to communicate. The @code{cdr} is a socket address +object (@pxref{Network Socket Address}) which is where the remote +connection is from (like @code{getpeername} below). + +@var{flags}, if given, may include @code{SOCK_CLOEXEC} or +@code{SOCK_NONBLOCK}, which like @code{O_CLOEXEC} and @code{O_NONBLOCK} +apply to the newly accepted socket. + +All communication takes place using the new socket returned. The +given @var{sock} remains bound and listening, and @code{accept} may be +called on it again to get another incoming connection when desired. +@end deffn + +@deffn {Scheme Procedure} getsockname sock +@deffnx {C Function} scm_getsockname (sock) +Return a socket address object which is the where @var{sock} is bound +locally. @var{sock} may have obtained its local address from +@code{bind} (above), or if a @code{connect} is done with an otherwise +unbound socket (which is usual) then the system will have assigned an +address. + +Note that on many systems the address of a socket in the +@code{AF_UNIX} namespace cannot be read. +@end deffn + +@deffn {Scheme Procedure} getpeername sock +@deffnx {C Function} scm_getpeername (sock) +Return a socket address object which is where @var{sock} is connected +to, i.e.@: the remote endpoint. + +Note that on many systems the address of a socket in the +@code{AF_UNIX} namespace cannot be read. +@end deffn + +@deffn {Scheme Procedure} recv! sock buf [flags] +@deffnx {C Function} scm_recv (sock, buf, flags) +Receive data from a socket port. +@var{sock} must already +be bound to the address from which data is to be received. +@var{buf} is a bytevector into which +the data will be written. The size of @var{buf} limits +the amount of +data which can be received: in the case of packet +protocols, if a packet larger than this limit is encountered +then some data +will be irrevocably lost. + +@vindex MSG_OOB +@vindex MSG_PEEK +@vindex MSG_DONTROUTE +The optional @var{flags} argument is a value or bitwise OR of +@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. + +The value returned is the number of bytes read from the +socket. + +Note that the data is read directly from the socket file +descriptor: +any unread buffered port data is ignored. +@end deffn + +@deffn {Scheme Procedure} send sock message [flags] +@deffnx {C Function} scm_send (sock, message, flags) +@vindex MSG_OOB +@vindex MSG_PEEK +@vindex MSG_DONTROUTE +Transmit bytevector @var{message} on socket port @var{sock}. +@var{sock} must already be bound to a destination address. The value +returned is the number of bytes transmitted---it's possible for this +to be less than the length of @var{message} if the socket is set to be +non-blocking. The optional @var{flags} argument is a value or bitwise +OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. + +Note that the data is written directly to the socket +file descriptor: +any unflushed buffered port data is ignored. +@end deffn + +@deffn {Scheme Procedure} recvfrom! sock buf [flags [start [end]]] +@deffnx {C Function} scm_recvfrom (sock, buf, flags, start, end) +Receive data from socket port @var{sock}, returning the originating +address as well as the data. This function is usually for datagram +sockets, but can be used on stream-oriented sockets too. + +The data received is stored in bytevector @var{buf}, using +either the whole bytevector or just the region between the optional +@var{start} and @var{end} positions. The size of @var{buf} +limits the amount of data that can be received. For datagram +protocols if a packet larger than this is received then excess +bytes are irrevocably lost. + +The return value is a pair. The @code{car} is the number of bytes +read. The @code{cdr} is a socket address object (@pxref{Network +Socket Address}) which is where the data came from, or @code{#f} if +the origin is unknown. + +@vindex MSG_OOB +@vindex MSG_PEEK +@vindex MSG_DONTROUTE +The optional @var{flags} argument is a or bitwise-OR (@code{logior}) +of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. + +Data is read directly from the socket file descriptor, any buffered +port data is ignored. + +@c This was linux kernel 2.6.15 and glibc 2.3.6, not sure what any +@c specs are supposed to say about recvfrom threading. +@c +On a GNU/Linux system @code{recvfrom!} is not multi-threading, all +threads stop while a @code{recvfrom!} call is in progress. An +application may need to use @code{select}, @code{O_NONBLOCK} or +@code{MSG_DONTWAIT} to avoid this. +@end deffn + +@deffn {Scheme Procedure} sendto sock message sockaddr [flags] +@deffnx {Scheme Procedure} sendto sock message AF_INET ipv4addr port [flags] +@deffnx {Scheme Procedure} sendto sock message AF_INET6 ipv6addr port [flowinfo [scopeid [flags]]] +@deffnx {Scheme Procedure} sendto sock message AF_UNIX path [flags] +@deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags) +Transmit bytevector @var{message} as a datagram socket port +@var{sock}. The destination is specified either as a socket address +object, or as arguments the same as would be taken by +@code{make-socket-address} to create such an object (@pxref{Network +Socket Address}). + +The destination address may be followed by an optional @var{flags} +argument which is a @code{logior} (@pxref{Bitwise Operations}) of +@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. + +The value returned is the number of bytes transmitted -- +it's possible for +this to be less than the length of @var{message} if the +socket is +set to be non-blocking. +Note that the data is written directly to the socket +file descriptor: +any unflushed buffered port data is ignored. +@end deffn + + +@node Internet Socket Examples +@subsubsection Network Socket Examples +@cindex network examples +@cindex socket examples + +The following give examples of how to use network sockets. + +@subsubheading Internet Socket Client Example + +@cindex socket client example +The following example demonstrates an Internet socket client. +It connects to the HTTP daemon running on the local machine and +returns the contents of the root index URL. + +@example +(let ((s (socket PF_INET SOCK_STREAM 0))) + (connect s AF_INET (inet-pton AF_INET "127.0.0.1") 80) + (display "GET / HTTP/1.0\r\n\r\n" s) + + (do ((line (read-line s) (read-line s))) + ((eof-object? line)) + (display line) + (newline))) +@end example + + +@subsubheading Internet Socket Server Example + +@cindex socket server example +The following example shows a simple Internet server which listens on +port 2904 for incoming connections and sends a greeting back to the +client. + +@example +(let ((s (socket PF_INET SOCK_STREAM 0))) + (setsockopt s SOL_SOCKET SO_REUSEADDR 1) + ;; @r{Specific address?} + ;; @r{(bind s AF_INET (inet-pton AF_INET "127.0.0.1") 2904)} + (bind s AF_INET INADDR_ANY 2904) + (listen s 5) + + (simple-format #t "Listening for clients in pid: ~S" (getpid)) + (newline) + + (while #t + (let* ((client-connection (accept s)) + (client-details (cdr client-connection)) + (client (car client-connection))) + (simple-format #t "Got new client connection: ~S" + client-details) + (newline) + (simple-format #t "Client address: ~S" + (gethostbyaddr + (sockaddr:addr client-details))) + (newline) + ;; @r{Send back the greeting to the client port} + (display "Hello client\r\n" client) + (close client)))) +@end example + + +@node System Identification +@subsection System Identification +@cindex system name + +This section lists the various procedures Guile provides for accessing +information about the system it runs on. + +@deffn {Scheme Procedure} uname +@deffnx {C Function} scm_uname () +Return an object with some information about the computer +system the program is running on. + +The following procedures accept an object as returned by @code{uname} +and return a selected component (all of which are strings). + +@deffn {Scheme Procedure} utsname:sysname un +The name of the operating system. +@end deffn +@deffn {Scheme Procedure} utsname:nodename un +The network name of the computer. +@end deffn +@deffn {Scheme Procedure} utsname:release un +The current release level of the operating system implementation. +@end deffn +@deffn {Scheme Procedure} utsname:version un +The current version level within the release of the operating system. +@end deffn +@deffn {Scheme Procedure} utsname:machine un +A description of the hardware. +@end deffn +@end deffn + +@deffn {Scheme Procedure} gethostname +@deffnx {C Function} scm_gethostname () +@cindex host name +Return the host name of the current processor. +@end deffn + +@deffn {Scheme Procedure} sethostname name +@deffnx {C Function} scm_sethostname (name) +Set the host name of the current processor to @var{name}. May +only be used by the superuser. The return value is not +specified. +@end deffn + +@node Locales +@subsection Locales +@cindex locale + +@deffn {Scheme Procedure} setlocale category [locale] +@deffnx {C Function} scm_setlocale (category, locale) +Get or set the current locale, used for various internationalizations. +Locales are strings, such as @samp{sv_SE}. + +If @var{locale} is given then the locale for the given @var{category} +is set and the new value returned. If @var{locale} is not given then +the current value is returned. @var{category} should be one of the +following values (@pxref{Locale Categories, Categories of Activities +that Locales Affect,, libc, The GNU C Library Reference Manual}): + +@defvar LC_ALL +@defvarx LC_COLLATE +@defvarx LC_CTYPE +@defvarx LC_MESSAGES +@defvarx LC_MONETARY +@defvarx LC_NUMERIC +@defvarx LC_TIME +@end defvar + +@cindex @code{LANG} +A common usage is @samp{(setlocale LC_ALL "")}, which initializes all +categories based on standard environment variables (@code{LANG} etc). +For full details on categories and locale names @pxref{Locales,, +Locales and Internationalization, libc, The GNU C Library Reference +Manual}. + +Note that @code{setlocale} affects locale settings for the whole +process. @xref{i18n Introduction, locale objects and +@code{make-locale}}, for a thread-safe alternative. +@end deffn + +@node Encryption +@subsection Encryption +@cindex encryption + +Please note that the procedures in this section are not suited for +strong encryption, they are only interfaces to the well-known and +common system library functions of the same name. They are just as good +(or bad) as the underlying functions, so you should refer to your system +documentation before using them (@pxref{crypt,, Encrypting Passwords, +libc, The GNU C Library Reference Manual}). + +@deffn {Scheme Procedure} crypt key salt +@deffnx {C Function} scm_crypt (key, salt) +Encrypt @var{key}, with the addition of @var{salt} (both strings), +using the @code{crypt} C library call. +@end deffn + +Although @code{getpass} is not an encryption procedure per se, it +appears here because it is often used in combination with @code{crypt}: + +@deffn {Scheme Procedure} getpass prompt +@deffnx {C Function} scm_getpass (prompt) +@cindex password +Display @var{prompt} to the standard error output and read +a password from @file{/dev/tty}. If this file is not +accessible, it reads from standard input. The password may be +up to 127 characters in length. Additional characters and the +terminating newline character are discarded. While reading +the password, echoing and the generation of signals by special +characters is disabled. +@end deffn + + +@c Local Variables: +@c TeX-master: "guile.texi" +@c End: |