@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
-@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
@menu
* Conventions:: Conventions employed by the POSIX interface.
* Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
- have different representations.
+ have different representations.
* File System:: stat, chown, chmod, etc.
* User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
* Time:: gettimeofday, localtime, strftime, etc.
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 object cmd [value]
+@deffn {Scheme Procedure} fcntl port/fd cmd [value]
@deffnx {C Function} scm_fcntl (object, cmd, value)
-Apply @var{command} to the specified file descriptor or the underlying
-file descriptor of the specified port. @var{value} is an optional
-integer argument.
+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{command} are:
+Values for @var{cmd} are:
@defvar F_DUPFD
-Duplicate a file descriptor
+Duplicate the file descriptor, the same as @code{dup->fdes} above
+does.
@end defvar
+
@defvar F_GETFD
-Get flags associated with the file descriptor.
+@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
-@defvar F_SETFD
-Set flags associated with the file descriptor to @var{value}.
@end defvar
+
@defvar F_GETFL
-Get flags associated with the open file.
-@end defvar
-@defvar F_SETFL
-Set flags associated with the open file to @var{value}
+@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
-Get the process ID of a socket's owner, for @code{SIGIO} signals.
-@end defvar
-@defvar F_SETOWN
-Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
-@end defvar
-@defvar FD_CLOEXEC
-The value used to indicate the ``close on exec'' flag with @code{F_GETFL} or
-@code{F_SETFL}.
+@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} 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).
The size of a regular file in bytes.
@end deffn
@deffn {Scheme Procedure} stat:atime st
-The last access time for the file.
+The last access time for the file, in seconds.
@end deffn
@deffn {Scheme Procedure} stat:mtime st
-The last modification time for the file.
+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.
+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
@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
The return value is unspecified.
@end deffn
-@deffn {Scheme Procedure} utime pathname [actime [modtime]]
-@deffnx {C Function} scm_utime (pathname, actime, modtime)
-@cindex file times
+@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 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
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
@deffn {Scheme Procedure} tmpnam
@deffnx {C Function} scm_tmpnam ()
@cindex temporary file
-Return a name in the file system that does not match any
-existing file. However there is no guarantee that another
-process will not create the file after @code{tmpnam} is called.
-Care should be taken if opening the file, e.g., use the
-@code{O_EXCL} open flag or use @code{mkstemp!} instead.
+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
@deffnx {C Function} scm_mkstemp (tmpl)
@cindex temporary file
-Create a new unique file in the file system and returns a new
-buffered port open for reading and writing to the 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 will be changed in
-place to return the name of the temporary 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 a GNU
-system it's @code{#o600} (but was @code{#o666} in the past). An
-application can use @code{chmod} to set what it wants. For example
-@code{#o666} less @code{umask} is usual for ordinary files,
+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 "file-XXXXXX"))))
+(let ((port (mkstemp! (string-copy "/tmp/myfile-XXXXXX"))))
(chmod port (logand #o666 (lognot (umask))))
...)
@end example
@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
@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
@end deffn
@deffn {Scheme Procedure} getpwent
-Return the next entry in the user database, using the stream set by
-@code{setpwent}.
+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
@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
In addition to the accessor procedures for the user database, the
-following shortcut procedures are also available.
-
-@deffn {Scheme Procedure} cuserid
-@deffnx {C Function} scm_cuserid ()
-Return a string containing a user name associated with the
-effective user id of the process. Return @code{#f} if this
-information cannot be obtained.
-
-This function has been removed from the latest POSIX specification,
-Guile provides it only if the system has it. Using @code{(getpwuid
-(geteuid))} may be a better idea.
-@end deffn
+following shortcut procedure is also available.
@deffn {Scheme Procedure} getlogin
@deffnx {C Function} scm_getlogin ()
@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
timezone.
@end deffn
-@deffn {Scheme Procedure} strftime format stime
-@deffnx {C Function} scm_strftime (format, stime)
+@deffn {Scheme Procedure} strftime format tm
+@deffnx {C Function} scm_strftime (format, tm)
@cindex time formatting
-Formats a time specification @var{time} using @var{template}. @var{time}
-is an object with time components in the form returned by @code{localtime}
-or @code{gmtime}. @var{template} is a string which can include formatting
-specifications introduced by a @samp{%} character. The formatting of
-month and day names is dependent on the current locale. The value returned
-is the formatted string.
-@xref{Formatting Calendar Time, , , libc, The GNU C Library Reference Manual}.
+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
@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},
@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
-Return the list of command line arguments passed to Guile, as a list of
-strings. The list includes the invoked program name, which is usually
-@code{"guile"}, but excludes switches and parameters for command line
-options like @code{-e} and @code{-l}.
+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
-@deffn {Scheme Procedure} getenv nam
-@deffnx {C Function} scm_getenv (nam)
+@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
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
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
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)
-Terminate the current process without unwinding the Scheme stack.
-This is would typically be useful after a fork. The exit status
-is @var{status} if supplied, otherwise zero.
+@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 . 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
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
+
+@deffn {Scheme Procedure} total-processor-count
+@deffnx {C Function} scm_total_processor_count ()
+Return the total number of processors of the machine, which
+is guaranteed to be at least 1. A ``processor'' here is a
+thread execution unit, which can be either:
+
+@itemize
+@item an execution core in a (possibly multi-core) chip, in a
+ (possibly multi- chip) module, in a single computer, or
+@item a thread execution unit inside a core in the case of
+ @dfn{hyper-threaded} CPUs.
+@end itemize
+
+Which of the two definitions is used, is unspecified.
+@end deffn
+
+@deffn {Scheme Procedure} current-processor-count
+@deffnx {C Function} scm_current_processor_count ()
+Like @code{total-processor-count}, but return the number of
+processors available to the current process. See
+@code{setaffinity} and @code{getaffinity} for more
+information.
+@end deffn
+
@node Signals
@subsection Signals
@cindex signal
-Procedures to raise, handle and wait for signals.
+The following procedures raise, handle and wait for signals.
+
+Scheme code signal handlers are run via a system async (@pxref{System
+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)
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).
-
-Guile always enables this flag where available, no matter what
-@var{flags} are specified. This avoids spurious error returns in low
-level operations.
@end defvar
The return value is a pair with information about the old handler as
handler procedure. The return value is unspecified.
@end deffn
-@deffn {Scheme Procedure} sleep i
-@deffnx {C Function} scm_sleep (i)
-Wait for the given number of seconds (an integer) or until a signal
-arrives. The return value is zero if the time elapses or the number
-of seconds remaining otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} usleep i
-@deffnx {C Function} scm_usleep (i)
-Sleep for @var{i} microseconds. @code{usleep} is not available on
-all platforms. [FIXME: so what happens when it isn't?]
-@end deffn
-
-@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
-@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
-Set the timer specified by @var{which_timer} according to the given
-@var{interval_seconds}, @var{interval_microseconds},
-@var{value_seconds}, and @var{value_microseconds} values.
+@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.
-Return information about the timer's previous setting.
+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.
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
+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 periodic_seconds periodic_microseconds
@deffnx {C Function} scm_getitimer (which_timer)
-Return information about the timer specified by @var{which_timer}.
+@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, periodic_seconds, periodic_microseconds)
+Get or set the periods programmed in certain system timers. These
+timers have a current interval value which counts down and on reaching
+zero raises a signal. An optional periodic value can be set to
+restart from there each time, for periodic operation.
+@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 current timer value and its programmed
+restart value, as a list containing two pairs. Each pair is a time in
+seconds and microseconds: @code{((@var{interval_secs}
+. @var{interval_usecs}) (@var{periodic_secs}
+. @var{periodic_usecs}))}.
+
+@code{setitimer} sets the timer values similarly, in seconds and
+microseconds (which must be integers). The periodic 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.
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
+@example
+(setitimer ITIMER_REAL
+ 5 500000 ;; first SIGALRM in 5.5 seconds time
+ 2 0) ;; then repeat every 2 seconds
+@end example
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
+Although the timers are programmed in microseconds, the actual
+accuracy might not be that high.
@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}).}:
-@smalllisp
+@lisp
(use-modules (ice-9 popen))
-@end smalllisp
+@end lisp
@findex popen
@deffn {Scheme Procedure} open-pipe command mode
@cindex network
@menu
-* Network Address Conversion::
-* Network Databases::
-* Network Sockets and Communication::
-* Internet Socket Examples::
+* Network Address Conversion::
+* Network Databases::
+* Network Socket Address::
+* Network Sockets and Communication::
+* Internet Socket Examples::
@end menu
@node Network Address Conversion
@cindex IPv4
An IPv4 Internet address is a 4-byte value, represented in Guile as an
-integer in network byte order (meaning the first byte is the most
-significant in the number).
+integer in host byte order, so that say ``0.0.0.1'' is 1, or
+``1.0.0.0'' is 16777216.
-@defvar INADDR_LOOPBACK
-The address of the local host using the loopback device, ie.@:
-@samp{127.0.0.1}.
+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
@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.,
@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.,
@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 into a printable string.
-Note that unlike the C version of this function,
-the input is an integer with normal host byte ordering.
+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
+(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. Note that unlike the C version of this
-function,
-the result is an integer with normal host byte ordering.
-@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
+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
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 list of aliases for @var{host}.
@end deffn
@deffn {Scheme Procedure} hostent:addrtype host
-The host address type. For hosts with Internet addresses, this will
-return @code{AF_INET}.
+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}.
+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 are used to search the host database:
+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
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
it's strongly recommended that socket ports be closed explicitly when
no longer required (@pxref{Ports}).
-The convention used for ``host'' vs.@: ``network'' addresses is that
-addresses are always held in host order at the Scheme level. The
-procedures in this section automatically convert between host and
-network order when required. The arguments and return values are thus
-in host order.
+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)
@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)
-Return the value of a particular socket option for the socket
-port @var{sock}. @var{level} is an integer code for type of
-option being requested, e.g., @code{SOL_SOCKET} for
-socket-level options. @var{optname} is an integer code for the
-option required and should be specified using one of the
-symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
+@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
-The returned value is typically an integer but @code{SO_LINGER}
-returns a pair of integers.
-@end deffn
+@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
-@deffn {Scheme Procedure} setsockopt sock level optname value
-@deffnx {C Function} scm_setsockopt (sock, level, optname, value)
-Set the value of a particular socket option for the socket
-port @var{sock}. @var{level} is an integer code for type of option
-being set, e.g., @code{SOL_SOCKET} for socket-level options.
-@var{optname} is an
-integer code for the option to set and should be specified using one of
-the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
-@var{value} is the value to which the option should be set. For
-most options this must be an integer, but for @code{SO_LINGER} it must
-be a pair.
+@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
-The return value is unspecified.
+@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
@deffn {Scheme Procedure} shutdown sock how
@deffnx {C Function} scm_shutdown (sock, how)
-Sockets can be closed simply by using @code{close-port}. The
+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.
+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
The return value is unspecified.
@end deffn
-@deffn {Scheme Procedure} connect sock fam address . args
+@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 from a socket using a specified address
-family to the address
-specified by @var{address} and possibly @var{args}.
-The format required for @var{address}
-and @var{args} depends on the family of the socket.
-
-For a socket of family @code{AF_UNIX},
-only @var{address} is specified and must be a string with the
-filename where the socket is to be created.
-
-For a socket of family @code{AF_INET},
-@var{address} must be an integer IPv4 host address and
-@var{args} must be a single integer port number.
-
-For a socket of family @code{AF_INET6},
-@var{address} must be an integer IPv6 host address and
-@var{args} may be up to three integers:
-port [flowinfo] [scope_id],
-where flowinfo and scope_id default to zero.
+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}). The return value is unspecified.
-The return value is unspecified.
+@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 fam address . args
+@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)
-Assign an address to the socket port @var{sock}.
-Generally this only needs to be done for server sockets,
-so they know where to look for incoming connections. A socket
-without an address will be assigned one automatically when it
-starts communicating.
-
-The format of @var{address} and @var{args} depends
-on the family of the socket.
-
-For a socket of family @code{AF_UNIX}, only @var{address}
-is specified and must be a string with the filename where
-the socket is to be created.
-
-For a socket of family @code{AF_INET}, @var{address}
-must be an integer IPv4 address and @var{args}
-must be a single integer port number.
+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.
-The values of the following variables can also be used for
-@var{address}:
+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.
-@defvar INADDR_ANY
-Allow connections from any address.
-@end defvar
-
-@defvar INADDR_LOOPBACK
-The address of the local host using the loopback device.
-@end defvar
-
-@defvar INADDR_BROADCAST
-The broadcast address on the local network.
-@end defvar
-
-@defvar INADDR_NONE
-No address.
-@end defvar
-
-For a socket of family @code{AF_INET6}, @var{address}
-must be an integer IPv6 address and @var{args}
-may be up to three integers:
-port [flowinfo] [scope_id],
-where flowinfo and scope_id default to zero.
-
-The return value is unspecified.
+@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
@deffn {Scheme Procedure} accept sock
@deffnx {C Function} scm_accept (sock)
-Accept a connection on a bound, listening socket.
-If there
-are no pending connections in the queue, wait until
-one is available unless the non-blocking option has been
-set on the socket.
+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, wait until one is available (unless
+@code{O_NONBLOCK} has been set on the socket, @pxref{Ports and File
+Descriptors,@code{fcntl}}).
-The return value is a
-pair in which the @acronym{CAR} is a new socket port for the
-connection and
-the @acronym{CDR} is an object with address information about the
-client which initiated the connection.
+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{sock} does not become part of the
-connection and will continue to accept new requests.
-@end deffn
-
-The following functions take a socket address object, as returned
-by @code{accept} and other procedures, and return a selected component.
-
-@deffn {Scheme Procedure} sockaddr:fam sa
-The socket family, typically equal to the value of @code{AF_UNIX} or
-@code{AF_INET}.
-@end deffn
-@deffn {Scheme Procedure} sockaddr:path sa
-If the socket family is @code{AF_UNIX}, returns the path of the
-filename the socket is based on.
-@end deffn
-@deffn {Scheme Procedure} sockaddr:addr sa
-If the socket family is @code{AF_INET}, returns the Internet host
-address.
-@end deffn
-@deffn {Scheme Procedure} sockaddr:port sa
-If the socket family is @code{AF_INET}, returns the Internet port
-number.
+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 the address of @var{sock}, in the same form as the
-object returned by @code{accept}. On many systems the address
-of a socket in the @code{AF_FILE} namespace cannot be read.
+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 the address that @var{sock}
-is connected to, in the same form as the object returned by
-@code{accept}. On many systems the address of a socket in the
-@code{AF_FILE} namespace cannot be read.
+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]
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)
-Return data from the socket port @var{sock} and also
-information about where the data was received from.
-@var{sock} must already be bound to the address from which
-data is to be received. @code{str}, is a string into which the
-data will be written. The size of @var{str} 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.
+@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 value or bitwise OR of
-@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
+The optional @var{flags} argument is a or bitwise-OR (@code{logior})
+of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
-The value returned is a pair: the @acronym{CAR} is the number of
-bytes read from the socket and the @acronym{CDR} an address object
-in the same form as returned by @code{accept}. The address
-will given as @code{#f} if not available, as is usually the
-case for stream sockets.
+Data is read directly from the socket file descriptor, any buffered
+port data is ignored.
-The @var{start} and @var{end} arguments specify a substring of
-@var{str} to which the data should be written.
-
-Note that the data is read directly from the socket file
-descriptor: any unread 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 fam address . args_and_flags
+@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 the string @var{message} on the socket port
-@var{sock}. The
-destination address is specified using the @var{fam},
-@var{address} and
-@var{args_and_flags} arguments, in a similar way to the
-@code{connect} procedure. @var{args_and_flags} contains
-the usual connection arguments optionally followed by
-a flags argument, which is a value or
-bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
+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
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
@example
(let ((s (socket PF_INET SOCK_STREAM 0)))
- (connect s AF_INET (inet-aton "127.0.0.1") 80)
+ (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)))
(let ((s (socket PF_INET SOCK_STREAM 0)))
(setsockopt s SOL_SOCKET SO_REUSEADDR 1)
;; @r{Specific address?}
- ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
+ ;; @r{(bind s AF_INET (inet-pton AF_INET "127.0.0.1") 2904)}
(bind s AF_INET INADDR_ANY 2904)
(listen s 5)
(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))))
+ (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
system the program is running on.
The following procedures accept an object as returned by @code{uname}
-and return a selected component.
+and return a selected component (all of which are strings).
@deffn {Scheme Procedure} utsname:sysname un
The name of the operating system.
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
+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
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
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.
+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} using @var{salt} as the salt value to the
-crypt(3) library call.
+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
HCoop / bpt / guile.git / blobdiff