@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
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,
+@c 2008, 2009, 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node POSIX
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.
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
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
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.
block buffered, using a newly allocated buffer of @var{size} bytes.
If @var{size} is omitted, a default size will be used.
@end defvar
+
+Only certain types of ports are supported, most importantly
+file ports.
@end deffn
@deffn {Scheme Procedure} fcntl port/fd cmd [value]
@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).
@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.
@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
@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.
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)
@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
@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}.
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
@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
@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
@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},
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
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
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.
@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
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}
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)
@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
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
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
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))
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 interpretered
+specify the requested protocol (its value is interpreted
as in calls to @code{socket}).
On error, an exception with key @code{getaddrinfo-error} is
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.
@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 <http://bugs.gnu.org/13958>.
@end table
Users are encouraged to read the
@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.
@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
@defvarx SO_OOBINLINE
@defvarx SO_NO_CHECK
@defvarx SO_PRIORITY
+@defvarx SO_REUSEPORT
The @var{value} taken or returned is an integer.
@end defvar
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}.
(@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.
@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.
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 string into which
+@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
@vindex MSG_OOB
@vindex MSG_PEEK
@vindex MSG_DONTROUTE
-Transmit the string @var{message} on a socket port @var{sock}.
+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
any unflushed buffered port data is ignored.
@end deffn
-@deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
-@deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
+@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 the given @var{str}, the whole string
-or just the region between the optional @var{start} and @var{end}
-positions. The size of @var{str} limits the amount of data which can
-be received. For datagram protocols if a packet larger than this is
-received then excess bytes are irrevocably lost.
+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
@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 the string @var{message} as a datagram on socket port
+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
any unflushed buffered port data is ignored.
@end deffn
-The following functions can be used to convert short and long integers
-between ``host'' and ``network'' order. Although the procedures above do
-this automatically for addresses, the conversion will still need to
-be done when sending or receiving encoded integer data from the network.
-
-@deffn {Scheme Procedure} htons value
-@deffnx {C Function} scm_htons (value)
-Convert a 16 bit quantity from host to network byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} ntohs value
-@deffnx {C Function} scm_ntohs (value)
-Convert a 16 bit quantity from network to host byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} htonl value
-@deffnx {C Function} scm_htonl (value)
-Convert a 32 bit quantity from host to network byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} ntohl value
-@deffnx {C Function} scm_ntohl (value)
-Convert a 32 bit quantity from network to host byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-These procedures are inconvenient to use at present, but consider:
-
-@example
-(define write-network-long
- (lambda (value port)
- (let ((v (make-uniform-vector 1 1 0)))
- (uniform-vector-set! v 0 (htonl value))
- (uniform-vector-write v port))))
-
-(define read-network-long
- (lambda (port)
- (let ((v (make-uniform-vector 1 1 0)))
- (uniform-vector-read! v port)
- (ntohl (uniform-vector-ref v 0)))))
-@end example
-
@node Internet Socket Examples
@subsubsection Network Socket Examples