X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/ecb8733562079227b96b1a2884cd3cce6d3974bb..b958141cdb081ceb16ca5828abda71f772fe0c57:/doc/ref/posix.texi diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index 704fe6312..40c20e7e9 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011 -@c Free Software Foundation, Inc. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, +@c 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @node POSIX @@ -211,8 +211,8 @@ 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 fd -@deffnx {C Function} scm_fdes_to_ports (fd) +@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. @@ -230,8 +230,8 @@ 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 fd -@deffnx {C Function} scm_primitive_move_to_fdes (port, fd) +@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 @@ -252,10 +252,10 @@ The return value is unspecified. Decrements the revealed count for a port. @end deffn -@deffn {Scheme Procedure} fsync object -@deffnx {C Function} scm_fsync (object) +@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/fd} is a port, its buffer is flushed before the underlying +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 @@ -402,11 +402,11 @@ port. This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}. @end deffn -@deffn {Scheme Procedure} redirect-port old new -@deffnx {C Function} scm_redirect_port (old, new) +@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. +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. @@ -648,7 +648,7 @@ The GNU C Library Reference Manual}. @deffn {Scheme Procedure} stat object @deffnx {C Function} scm_stat (object) Return an object containing various information about the file -determined by @var{obj}. @var{obj} can be a string containing +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). @@ -728,8 +728,8 @@ An integer representing the access permission bits. @end deffn @end deffn -@deffn {Scheme Procedure} lstat str -@deffnx {C Function} scm_lstat (str) +@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. @@ -762,8 +762,8 @@ as @code{-1}, then that ID is not changed. @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{obj}. -@var{obj} can be a string containing a file name or a port or integer file +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 @@ -774,7 +774,7 @@ The return value is unspecified. @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{path}. If @var{actime} or @var{modtime} is +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. @@ -803,6 +803,36 @@ 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) @@ -843,6 +873,10 @@ be empty for this to succeed. The return value is unspecified. @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 @@ -949,7 +983,7 @@ which is usual for ordinary file creation, @end deffn @deffn {Scheme Procedure} tmpfile -@deffnx {C Function} scm_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}. @@ -982,6 +1016,43 @@ 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 @@ -1051,7 +1122,7 @@ stream. Otherwise, close the stream. The @code{setpwent} and @deffn {Scheme Procedure} getpw [user] @deffnx {C Function} scm_getpwuid (user) -Look up an entry in the user database. @var{obj} can be an integer, +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 @@ -1104,9 +1175,9 @@ stream. Otherwise, close the stream. The @code{setgrent} and @code{endgrent} procedures are implemented on top of this. @end deffn -@deffn {Scheme Procedure} getgr [name] -@deffnx {C Function} scm_getgrgid (name) -Look up an entry in the group database. @var{obj} can be an integer, +@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 @@ -1280,7 +1351,7 @@ names are from the current locale and in the locale character set. @cindex time parsing Performs the reverse action to @code{strftime}, parsing @var{string} according to the specification supplied in -@var{template}. The interpretation of month and day names is +@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}, @@ -1407,8 +1478,8 @@ 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 nam -@deffnx {C Function} scm_getenv (nam) +@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 @@ -1438,8 +1509,8 @@ 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 +@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 @@ -1448,11 +1519,11 @@ then the return value is unspecified. Modifies the environment of the current process, which is also the default environment inherited by child processes. -If @var{string} is of the form @code{NAME=VALUE} then it will be written +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{string} does not contain an equal -sign, then any existing string with name matching @var{string} will +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. @@ -1468,7 +1539,7 @@ The return value is unspecified. @deffn {Scheme Procedure} chdir str @deffnx {C Function} scm_chdir (str) @cindex current directory -Change the current working directory to @var{path}. +Change the current working directory to @var{str}. The return value is unspecified. @end deffn @@ -1694,12 +1765,12 @@ If @code{system} is called without arguments, return a boolean indicating whether the command processor is available. @end deffn -@deffn {Scheme Procedure} system* . args +@deffn {Scheme Procedure} system* arg1 arg2 @dots{} @deffnx {C Function} scm_system_star (args) -Execute the command indicated by @var{args}. 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. +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} @@ -1714,6 +1785,18 @@ 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 0 +or 1, respectively. + +The procedure @code{exit} is an alias of @code{quit}. They have the +same functionality. +@end deffn + @deffn {Scheme Procedure} primitive-exit [status] @deffnx {Scheme Procedure} primitive-_exit [status] @deffnx {C Function} scm_primitive_exit (status) @@ -1739,22 +1822,22 @@ 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 . args +@deffn {Scheme Procedure} execl filename arg @dots{} @deffnx {C Function} scm_execl (filename, args) -Executes the file named by @var{path} as a new process image. +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{path}. +Conventionally the first @var{arg} is the same as @var{filename}. All arguments must be strings. -If @var{arg} is missing, @var{path} is executed with a null +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 . args +@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 @@ -1765,7 +1848,7 @@ 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 . args +@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 @@ -1781,6 +1864,20 @@ 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 @@ -2136,7 +2233,8 @@ controlling terminal. The return value is unspecified. The following procedures are similar to the @code{popen} and @code{pclose} system routines. The code is in a separate ``popen'' -module: +module@footnote{This module is only available on systems where the +@code{fork} feature is provided (@pxref{Common Feature Symbols}).}: @lisp (use-modules (ice-9 popen)) @@ -2498,9 +2596,9 @@ 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 GNU systems when a -request was actually made but returned no data, meaning -that no address is associated with @var{name}. Error handling +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 @@ -2510,8 +2608,11 @@ code should be prepared to handle it when it is defined. @var{hint_socktype} was not recognized. @item EAI_SYSTEM -A system error occurred; the error code can be found in -@code{errno}. +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 . @end table Users are encouraged to read the @@ -2837,7 +2938,7 @@ 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 +@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. @@ -2863,7 +2964,7 @@ 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 (eg. @code{AF_INET}). +is one of the @code{AF} constants (e.g.@: @code{AF_INET}). @end deffn @deffn {Scheme Procedure} sockaddr:path sa @@ -3034,6 +3135,7 @@ Manual}, or @command{man 7 socket}. @defvarx SO_OOBINLINE @defvarx SO_NO_CHECK @defvarx SO_PRIORITY +@defvarx SO_REUSEPORT The @var{value} taken or returned is an integer. @end defvar @@ -3122,7 +3224,7 @@ either a socket address object, or arguments the same as (@pxref{Network Socket Address}). The return value is unspecified. Generally a socket is only explicitly bound to a particular address -when making a server, ie. to listen on a particular port. For an +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. @@ -3177,7 +3279,7 @@ Note that on many systems the address of a socket in the @deffn {Scheme Procedure} getpeername sock @deffnx {C Function} scm_getpeername (sock) Return a socket address object which is where @var{sock} is connected -to, ie. the remote endpoint. +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.