Deprecate htons, htonl, ntohs, ntohl

[bpt/guile.git] / doc / ref / posix.texi

diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 468eaea..7ca2fb0 100644 (file)
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @c -*-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
 @c See the file guile.texi for copying conditions.
 
 @node POSIX


@@ -211,8 +211,8 @@ initialized to zero.  The @var{modes} string is the same as that
 accepted by @code{open-file} (@pxref{File Ports, open-file}).
 @end deffn
 
 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.
 Return a list of existing ports which have @var{fdes} as an
 underlying file descriptor, without changing their revealed
 counts.


@@ -230,8 +230,8 @@ descriptor, if one exists, and increments its revealed count.
 Otherwise, returns a new output port with a revealed count of 1.
 @end deffn
 
 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
 Moves the underlying file descriptor for @var{port} to the integer
 value @var{fdes} without changing the revealed count of @var{port}.
 Any other ports already using this descriptor will be automatically


@@ -252,10 +252,10 @@ The return value is unspecified.
 Decrements the revealed count for a port.
 @end deffn
 
 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.
 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
 file descriptor is fsync'd.
 The return value is unspecified.
 @end deffn


@@ -402,11 +402,11 @@ port.
 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
 @end deffn
 
 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
 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.
 
 After the redirection the two ports will share a file position
 and file status flags.
 


@@ -470,6 +470,9 @@ line buffered
 block buffered, using a newly allocated buffer of @var{size} bytes.
 If @var{size} is omitted, a default size will be used.
 @end defvar
 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]
 @end deffn
 
 @deffn {Scheme Procedure} fcntl port/fd cmd [value]


@@ -648,7 +651,7 @@ The GNU C Library Reference Manual}.
 @deffn {Scheme Procedure} stat object
 @deffnx {C Function} scm_stat (object)
 Return an object containing various information about the file
 @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).
 a file name or a port or integer file descriptor which is open
 on a file (in which case @code{fstat} is used as the underlying
 system call).


@@ -728,8 +731,8 @@ An integer representing the access permission bits.
 @end deffn
 @end deffn
 
 @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.
 Similar to @code{stat}, but does not follow symbolic links, i.e.,
 it will return information about a symbolic link itself, not the
 file it points to.  @var{path} must be a string.


@@ -762,8 +765,8 @@ as @code{-1}, then that ID is not changed.
 @findex fchmod
 @deffn {Scheme Procedure} chmod object mode
 @deffnx {C Function} scm_chmod (object, mode)
 @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
 descriptor which is open on a file (in which case @code{fchmod} is used
 as the underlying system call).
 @var{mode} specifies


@@ -774,7 +777,7 @@ The return value is unspecified.
 @deffn {Scheme Procedure} utime pathname [actime [modtime [actimens [modtimens [flags]]]]]
 @deffnx {C Function} scm_utime (pathname, actime, modtime, actimens, modtimens, flags)
 @code{utime} sets the access and modification times for the
 @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.
 not supplied, then the current time is used.  @var{actime} and
 @var{modtime} must be integer time values as returned by the
 @code{current-time} procedure.


@@ -803,6 +806,36 @@ Copy the file specified by @var{oldfile} to @var{newfile}.
 The return value is unspecified.
 @end deffn
 
 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)
 @findex rename
 @deffn {Scheme Procedure} rename-file oldname newname
 @deffnx {C Function} scm_rename (oldname, newname)


@@ -843,6 +876,10 @@ be empty for this to succeed.  The return value is unspecified.
 @cindex directory contents
 Open the directory specified by @var{dirname} and return a directory
 stream.
 @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} directory-stream? object


@@ -949,7 +986,7 @@ which is usual for ordinary file creation,
 @end deffn
 
 @deffn {Scheme Procedure} tmpfile
 @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}.
 Return an input/output port to a unique temporary file
 named using the path prefix @code{P_tmpdir} defined in
 @file{stdio.h}.


@@ -982,6 +1019,43 @@ Return @code{#t} if the file named @var{filename} exists, @code{#f} if
 not.
 @end deffn
 
 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
 
 @node User Information
 @subsection User Information


@@ -1051,7 +1125,7 @@ stream.  Otherwise, close the stream.  The @code{setpwent} and
 
 @deffn {Scheme Procedure} getpw [user]
 @deffnx {C Function} scm_getpwuid (user)
 
 @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
 a string, or omitted, giving the behaviour of getpwuid, getpwnam
 or getpwent respectively.
 @end deffn


@@ -1104,9 +1178,9 @@ stream.  Otherwise, close the stream.  The @code{setgrent} and
 @code{endgrent} procedures are implemented on top of this.
 @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
 a string, or omitted, giving the behaviour of getgrgid, getgrnam
 or getgrent respectively.
 @end deffn


@@ -1280,7 +1354,7 @@ names are from the current locale and in the locale character set.
 @cindex time parsing
 Performs the reverse action to @code{strftime}, parsing
 @var{string} according to the specification supplied in
 @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},
 dependent on the current locale.  The value returned is a pair.
 The @acronym{CAR} has an object with time components
 in the form returned by @code{localtime} or @code{gmtime},


@@ -1407,8 +1481,8 @@ The given strings are all copied, so the C data is not accessed again
 once @code{scm_set_program_arguments} returns.
 @end deftypefn
 
 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
 @cindex environment
 Looks up the string @var{name} in the current environment.  The return
 value is @code{#f} unless a string of the form @code{NAME=VALUE} is


@@ -1438,8 +1512,8 @@ If @var{env} is omitted, return the current environment (in the
 Unix sense) as a list of strings.  Otherwise set the current
 environment, which is also the default environment for child
 processes, to the supplied list of strings.  Each member of
 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
 
 then the return value is unspecified.
 @end deffn
 


@@ -1448,11 +1522,11 @@ then the return value is unspecified.
 Modifies the environment of the current process, which is
 also the default environment inherited by child processes.
 
 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
 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.
 be removed.
 
 The return value is unspecified.


@@ -1468,7 +1542,7 @@ The return value is unspecified.
 @deffn {Scheme Procedure} chdir str
 @deffnx {C Function} scm_chdir (str)
 @cindex current directory
 @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 unspecified.
 @end deffn
 


@@ -1694,12 +1768,12 @@ If @code{system} is called without arguments, return a boolean
 indicating whether the command processor is available.
 @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)
 @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}
 
 This function returns the exit status of the command as provided by
 @code{waitpid}.  This value can be handled with @code{status:exit-val}


@@ -1714,6 +1788,18 @@ interpretation is not required.
 Example: (system* "echo" "foo" "bar")
 @end deffn
 
 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)
 @deffn {Scheme Procedure} primitive-exit [status]
 @deffnx {Scheme Procedure} primitive-_exit [status]
 @deffnx {C Function} scm_primitive_exit (status)


@@ -1739,22 +1825,22 @@ in the child would upset the protocol in the parent, so
 @code{primitive-_exit} should be used to exit without that.
 @end deffn
 
 @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)
 @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}.
 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.
 
 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
 
 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
 @deffnx {C Function} scm_execlp (filename, args)
 Similar to @code{execl}, however if
 @var{filename} does not contain a slash


@@ -1765,7 +1851,7 @@ This procedure is currently implemented using the @code{execvp} system
 call, but we call it @code{execlp} because of its Scheme calling interface.
 @end deffn
 
 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
 @deffnx {C Function} scm_execle (filename, env, args)
 Similar to @code{execl}, but the environment of the new process is
 specified by @var{env}, which must be a list of strings as returned by the


@@ -1781,6 +1867,19 @@ Creates a new ``child'' process by duplicating the current ``parent'' process.
 In the child the return value is 0.  In the parent the return value is
 the integer process ID of the child.
 
 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
 This procedure has been renamed from @code{fork} to avoid a naming conflict
 with the scsh fork.
 @end deffn


@@ -2136,7 +2235,8 @@ controlling terminal.  The return value is unspecified.
 
 The following procedures are similar to the @code{popen} and
 @code{pclose} system routines.  The code is in a separate ``popen''
 
 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))
 
 @lisp
 (use-modules (ice-9 popen))


@@ -2456,7 +2556,7 @@ 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
 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
 as in calls to @code{socket}).
 
 On error, an exception with key @code{getaddrinfo-error} is


@@ -2497,6 +2597,12 @@ resolve the name.
 Either @var{name} does not resolve for the supplied parameters,
 or neither @var{name} nor @var{service} were supplied.
 
 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_SERVICE
 @var{service} was not recognized for the specified socket type.
 


@@ -2504,8 +2610,11 @@ or neither @var{name} nor @var{service} were supplied.
 @var{hint_socktype} was not recognized.
 
 @item EAI_SYSTEM
 @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
 @end table
 
 Users are encouraged to read the


@@ -2831,7 +2940,7 @@ created with,
 @deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port
 @deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
 @deffnx {Scheme Procedure} make-socket-address AF_UNIX path
 @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.
 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.


@@ -2857,7 +2966,7 @@ The following functions access the fields of a socket address object,
 
 @deffn {Scheme Procedure} sockaddr:fam sa
 Return the address family from socket address object @var{sa}.  This
 
 @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
 @end deffn
 
 @deffn {Scheme Procedure} sockaddr:path sa


@@ -3028,6 +3137,7 @@ Manual}, or @command{man 7 socket}.
 @defvarx SO_OOBINLINE
 @defvarx SO_NO_CHECK
 @defvarx SO_PRIORITY
 @defvarx SO_OOBINLINE
 @defvarx SO_NO_CHECK
 @defvarx SO_PRIORITY

+@defvarx SO_REUSEPORT

 The @var{value} taken or returned is an integer.
 @end defvar
 
 The @var{value} taken or returned is an integer.
 @end defvar
 


@@ -3116,7 +3226,7 @@ either a socket address object, or arguments the same as
 (@pxref{Network Socket Address}).  The return value is unspecified.
 
 Generally a socket is only explicitly bound to a particular address
 (@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.
 
 outgoing connection the system will assign a local address
 automatically, if not already bound.
 


@@ -3171,7 +3281,7 @@ Note that on many systems the address of a socket in the
 @deffn {Scheme Procedure} getpeername sock
 @deffnx {C Function} scm_getpeername (sock)
 Return a socket address object which is where @var{sock} is connected
 @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.
 
 Note that on many systems the address of a socket in the
 @code{AF_UNIX} namespace cannot be read.


@@ -3182,7 +3292,7 @@ Note that on many systems the address of a socket in the
 Receive data from a socket port.
 @var{sock} must already
 be bound to the address from which data is to be received.
 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
 the data will be written.  The size of @var{buf} limits
 the amount of
 data which can be received: in the case of packet


@@ -3209,7 +3319,7 @@ any unread buffered port data is ignored.
 @vindex MSG_OOB
 @vindex MSG_PEEK
 @vindex MSG_DONTROUTE
 @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
 @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


@@ -3221,17 +3331,18 @@ file descriptor:
 any unflushed buffered port data is ignored.
 @end deffn
 
 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.
 
 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
 
 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


@@ -3261,7 +3372,7 @@ application may need to use @code{select}, @code{O_NONBLOCK} or
 @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)
 @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
 @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


@@ -3281,55 +3392,6 @@ file descriptor:
 any unflushed buffered port data is ignored.
 @end deffn
 
 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
 
 @node Internet Socket Examples
 @subsubsection Network Socket Examples