   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Signals
=======

   Procedures to raise, handle and wait for signals.

 - Scheme Procedure: kill pid sig
 - C Function: scm_kill (pid, sig)
     Sends a signal to the specified process or group of processes.

     PID specifies the processes to which the signal is sent:

    PID greater than 0
          The process whose identifier is PID.

    PID equal to 0
          All processes in the current process group.

    PID less than -1
          The process group whose identifier is -PID

    PID equal to -1
          If the process is privileged, all processes except for some
          special system processes.  Otherwise, all processes with the
          current effective user ID.

     SIG should be specified using a variable corresponding to the Unix
     symbolic name, e.g.,

      - Variable: SIGHUP
          Hang-up signal.

      - Variable: SIGINT
          Interrupt signal.

 - Scheme Procedure: raise sig
 - C Function: scm_raise (sig)
     Sends a specified signal SIG to the current process, where SIG is
     as described for the kill procedure.

 - Scheme Procedure: sigaction signum [handler [flags]]
 - C Function: scm_sigaction (signum, handler, flags)
     Install or report the signal handler for a specified signal.

     SIGNUM is the signal number, which can be specified using the value
     of variables such as `SIGINT'.

     If ACTION is omitted, `sigaction' returns a pair: the CAR is the
     current signal hander, which will be either an integer with the
     value `SIG_DFL' (default action) or `SIG_IGN' (ignore), or the
     Scheme procedure which handles the signal, or `#f' if a non-Scheme
     procedure handles the signal.  The CDR contains the current
     `sigaction' flags for the handler.

     If ACTION is provided, it is installed as the new handler for
     SIGNUM.  ACTION can be a Scheme procedure taking one argument, or
     the value of `SIG_DFL' (default action) or `SIG_IGN' (ignore), or
     `#f' to restore whatever signal handler was installed before
     `sigaction' was first used.  Flags can optionally be specified for
     the new handler (`SA_RESTART' will always be added if it's
     available and the system is using restartable system calls.)  The
     return value is a pair with information about the old handler as
     described above.

     This interface does not provide access to the "signal blocking"
     facility.  Maybe this is not needed, since the thread support may
     provide solutions to the problem of consistent access to data
     structures.

 - Scheme Procedure: restore-signals
 - C Function: scm_restore_signals ()
     Return all signal handlers to the values they had before any call
     to `sigaction' was made.  The return value is unspecified.

 - Scheme Procedure: alarm i
 - C Function: scm_alarm (i)
     Set a timer to raise a `SIGALRM' signal after the specified number
     of seconds (an integer).  It's advisable to install a signal
     handler for `SIGALRM' beforehand, since the default action is to
     terminate the process.

     The return value indicates the time remaining for the previous
     alarm, if any.  The new value replaces the previous alarm.  If
     there was no previous alarm, the return value is zero.

 - Scheme Procedure: pause
 - C Function: scm_pause ()
     Pause the current process (thread?) until a signal arrives whose
     action is to either terminate the current process or invoke a
     handler procedure.  The return value is unspecified.

 - Scheme Procedure: sleep i
 - 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.

 - Scheme Procedure: usleep i
 - C Function: scm_usleep (i)
     Sleep for I microseconds.  `usleep' is not available on all
     platforms.

 - Scheme Procedure: setitimer which_timer interval_seconds
          interval_microseconds value_seconds value_microseconds
 - C Function: scm_setitimer (which_timer, interval_seconds,
          interval_microseconds, value_seconds, value_microseconds)
     Set the timer specified by WHICH_TIMER according to the given
     INTERVAL_SECONDS, INTERVAL_MICROSECONDS, VALUE_SECONDS, and
     VALUE_MICROSECONDS values.

     Return information about the timer's previous setting.  Errors are
     handled as described in the guile info pages under "POSIX
     Interface Conventions".

     The timers available are: `ITIMER_REAL', `ITIMER_VIRTUAL', and
     `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 `it_interval', and the second pair is
     the seconds and microseconds of the timer `it_value'.

 - Scheme Procedure: getitimer which_timer
 - C Function: scm_getitimer (which_timer)
     Return information about the timer specified by WHICH_TIMER Errors
     are handled as described in the guile info pages under "POSIX
     Interface Conventions".

     The timers available are: `ITIMER_REAL', `ITIMER_VIRTUAL', and
     `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 `it_interval', and the second pair is
     the seconds and microseconds of the timer `it_value'.

Terminals and Ptys
==================

 - Scheme Procedure: isatty? port
 - C Function: scm_isatty_p (port)
     Return `#t' if PORT is using a serial non-file device, otherwise
     `#f'.

 - Scheme Procedure: ttyname port
 - C Function: scm_ttyname (port)
     Return a string with the name of the serial terminal device
     underlying PORT.

 - Scheme Procedure: ctermid
 - C Function: scm_ctermid ()
     Return a string containing the file name of the controlling
     terminal for the current process.

 - Scheme Procedure: tcgetpgrp port
 - C Function: scm_tcgetpgrp (port)
     Return the process group ID of the foreground process group
     associated with the terminal open on the file descriptor
     underlying PORT.

     If there is no foreground process group, the return value is a
     number greater than 1 that does not match the process group ID of
     any existing process group.  This can happen if all of the
     processes in the job that was formerly the foreground job have
     terminated, and no other job has yet been moved into the
     foreground.

 - Scheme Procedure: tcsetpgrp port pgid
 - C Function: scm_tcsetpgrp (port, pgid)
     Set the foreground process group ID for the terminal used by the
     file descriptor underlying PORT to the integer PGID.  The calling
     process must be a member of the same session as PGID and must have
     the same controlling terminal.  The return value is unspecified.

Pipes
=====

   The following procedures provide an interface to the `popen' and
`pclose' system routines.  The code is in a separate "popen" module:

     (use-modules (ice-9 popen))

 - Scheme Procedure: open-pipe command modes
     Executes the shell command COMMAND (a string) in a subprocess.  A
     pipe to the process is created and returned.  MODES specifies
     whether an input or output pipe to the process is created: it
     should be the value of `OPEN_READ' or `OPEN_WRITE'.

 - Scheme Procedure: open-input-pipe command
     Equivalent to `open-pipe' with mode `OPEN_READ'.

          (read-line (open-input-pipe "date"))
          => "Mon Mar 11 20:10:44 GMT 2002"

          (waitpid WAIT_ANY)
          => (24160 . 0)

 - Scheme Procedure: open-output-pipe command
     Equivalent to `open-pipe' with mode `OPEN_WRITE'.

 - Scheme Procedure: close-pipe port
     Closes the pipe created by `open-pipe', then waits for the process
     to terminate and returns its status value, see waitpid,
     for information on how to interpret this value.

     `close-port' (see close-port) can also be used to
     close a pipe, but doesn't return the status.

Networking
==========

Network Address Conversion
--------------------------

   This section describes procedures which convert internet addresses
between numeric and string formats.

IPv4 Address Conversion
.......................

 - Scheme Procedure: inet-aton address
 - C Function: scm_inet_aton (address)
     Convert an IPv4 Internet address from printable string (dotted
     decimal notation) to an integer.  E.g.,

          (inet-aton "127.0.0.1") => 2130706433

 - Scheme Procedure: inet-ntoa inetid
 - C Function: scm_inet_ntoa (inetid)
     Convert an IPv4 Internet address to a printable (dotted decimal
     notation) string.  E.g.,

          (inet-ntoa 2130706433) => "127.0.0.1"

 - Scheme Procedure: inet-netof address
 - C Function: scm_inet_netof (address)
     Return the network number part of the given IPv4 Internet address.
     E.g.,

          (inet-netof 2130706433) => 127

 - Scheme Procedure: inet-lnaof address
 - C Function: scm_lnaof (address)
     Return the local-address-with-network part of the given IPv4
     Internet address, using the obsolete class A/B/C system.  E.g.,

          (inet-lnaof 2130706433) => 1

 - Scheme Procedure: inet-makeaddr net lna
 - C Function: scm_inet_makeaddr (net, lna)
     Make an IPv4 Internet address by combining the network number NET
     with the local-address-within-network number LNA.  E.g.,

          (inet-makeaddr 127 1) => 2130706433

IPv6 Address Conversion
.......................

 - Scheme Procedure: inet-ntop family address
 - 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.  FAMILY can be `AF_INET' or
     `AF_INET6'.  E.g.,

          (inet-ntop AF_INET 2130706433) => "127.0.0.1"
          (inet-ntop AF_INET6 (- (expt 2 128) 1)) =>
          ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

 - Scheme Procedure: inet-pton family address
 - 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.  FAMILY
     can be `AF_INET' or `AF_INET6'.  E.g.,

          (inet-pton AF_INET "127.0.0.1") => 2130706433
          (inet-pton AF_INET6 "::1") => 1

Network Databases
-----------------

   This section describes procedures which query various network
databases.  Care should be taken when using the database routines since
they are not reentrant.

The Host Database
.................

   A "host object" is a structure that represents what is known about a
network host, and is the usual way of representing a system's network
identity inside software.

   The following functions accept a host object and return a selected
component:

 - Scheme Procedure: hostent:name host
     The "official" hostname for HOST.

 - Scheme Procedure: hostent:aliases host
     A list of aliases for HOST.

 - Scheme Procedure: hostent:addrtype host
     The host address type.  For hosts with Internet addresses, this
     will return `AF_INET'.

 - Scheme Procedure: hostent:length host
     The length of each address for HOST, in bytes.

 - Scheme Procedure: hostent:addr-list host
     The list of network addresses associated with HOST.

   The following procedures are used to search the host database:

 - Scheme Procedure: gethost [host]
 - Scheme Procedure: gethostbyname hostname
 - Scheme Procedure: gethostbyaddr address
 - C Function: scm_gethost (host)
     Look up a host by name or address, returning a host object.  The
     `gethost' procedure will accept either a string name or an integer
     address; if given no arguments, it behaves like `gethostent' (see
     below).  If a name or address is supplied but the address can not
     be found, an error will be thrown to one of the keys:
     `host-not-found', `try-again', `no-recovery' or `no-data',
     corresponding to the equivalent `h_error' values.  Unusual
     conditions may result in errors thrown to the `system-error' or
     `misc_error' keys.

          (gethost "www.gnu.org")
          => #("www.gnu.org" () 2 4 (3353880842))

          (gethostbyname "www.emacs.org")
          => #("emacs.org" ("www.emacs.org") 2 4 (1073448978))

   The following procedures may be used to step through the host
database from beginning to end.

 - Scheme Procedure: sethostent [stayopen]
     Initialize an internal stream from which host objects may be read.
     This procedure must be called before any calls to `gethostent',
     and may also be called afterward to reset the host entry stream.
     If STAYOPEN is supplied and is not `#f', the database is not
     closed by subsequent `gethostbyname' or `gethostbyaddr' calls,
     possibly giving an efficiency gain.

 - Scheme Procedure: gethostent
     Return the next host object from the host database, or `#f' if
     there are no more hosts to be found (or an error has been
     encountered).  This procedure may not be used before `sethostent'
     has been called.

 - Scheme Procedure: endhostent
     Close the stream used by `gethostent'.  The return value is
     unspecified.

 - Scheme Procedure: sethost [stayopen]
 - C Function: scm_sethost (stayopen)
     If STAYOPEN is omitted, this is equivalent to `endhostent'.
     Otherwise it is equivalent to `sethostent stayopen'.

The Network Database
....................

   The following functions accept an object representing a network and
return a selected component:

 - Scheme Procedure: netent:name net
     The "official" network name.

 - Scheme Procedure: netent:aliases net
     A list of aliases for the network.

 - Scheme Procedure: netent:addrtype net
     The type of the network number.  Currently, this returns only
     `AF_INET'.

 - Scheme Procedure: netent:net net
     The network number.

   The following procedures are used to search the network database:

 - Scheme Procedure: getnet [net]
 - Scheme Procedure: getnetbyname net-name
 - Scheme Procedure: getnetbyaddr net-number
 - C Function: scm_getnet (net)
     Look up a network by name or net number in the network database.
     The NET-NAME argument must be a string, and the NET-NUMBER
     argument must be an integer.  `getnet' will accept either type of
     argument, behaving like `getnetent' (see below) if no arguments are
     given.

   The following procedures may be used to step through the network
database from beginning to end.

 - Scheme Procedure: setnetent [stayopen]
     Initialize an internal stream from which network objects may be
     read.  This procedure must be called before any calls to
     `getnetent', and may also be called afterward to reset the net
     entry stream.  If STAYOPEN is supplied and is not `#f', the
     database is not closed by subsequent `getnetbyname' or
     `getnetbyaddr' calls, possibly giving an efficiency gain.

 - Scheme Procedure: getnetent
     Return the next entry from the network database.

 - Scheme Procedure: endnetent
     Close the stream used by `getnetent'.  The return value is
     unspecified.

 - Scheme Procedure: setnet [stayopen]
 - C Function: scm_setnet (stayopen)
     If STAYOPEN is omitted, this is equivalent to `endnetent'.
     Otherwise it is equivalent to `setnetent stayopen'.

The Protocol Database
.....................

   The following functions accept an object representing a protocol and
return a selected component:

 - Scheme Procedure: protoent:name protocol
     The "official" protocol name.

 - Scheme Procedure: protoent:aliases protocol
     A list of aliases for the protocol.

 - Scheme Procedure: protoent:proto protocol
     The protocol number.

   The following procedures are used to search the protocol database:

 - Scheme Procedure: getproto [protocol]
 - Scheme Procedure: getprotobyname name
 - Scheme Procedure: getprotobynumber number
 - C Function: scm_getproto (protocol)
     Look up a network protocol by name or by number.  `getprotobyname'
     takes a string argument, and `getprotobynumber' takes an integer
     argument.  `getproto' will accept either type, behaving like
     `getprotoent' (see below) if no arguments are supplied.

   The following procedures may be used to step through the protocol
database from beginning to end.

 - Scheme Procedure: setprotoent [stayopen]
     Initialize an internal stream from which protocol objects may be
     read.  This procedure must be called before any calls to
     `getprotoent', and may also be called afterward to reset the
     protocol entry stream.  If STAYOPEN is supplied and is not `#f',
     the database is not closed by subsequent `getprotobyname' or
     `getprotobynumber' calls, possibly giving an efficiency gain.

 - Scheme Procedure: getprotoent
     Return the next entry from the protocol database.

 - Scheme Procedure: endprotoent
     Close the stream used by `getprotoent'.  The return value is
     unspecified.

 - Scheme Procedure: setproto [stayopen]
 - C Function: scm_setproto (stayopen)
     If STAYOPEN is omitted, this is equivalent to `endprotoent'.
     Otherwise it is equivalent to `setprotoent stayopen'.

The Service Database
....................

   The following functions accept an object representing a service and
return a selected component:

 - Scheme Procedure: servent:name serv
     The "official" name of the network service.

 - Scheme Procedure: servent:aliases serv
     A list of aliases for the network service.

 - Scheme Procedure: servent:port serv
     The Internet port used by the service.

 - Scheme Procedure: servent:proto serv
     The protocol used by the service.  A service may be listed many
     times in the database under different protocol names.

   The following procedures are used to search the service database:

 - Scheme Procedure: getserv [name [protocol]]
 - Scheme Procedure: getservbyname name protocol
 - Scheme Procedure: getservbyport port protocol
 - C Function: scm_getserv (name, protocol)
     Look up a network service by name or by service number, and return
     a network service object.  The PROTOCOL argument specifies the name
     of the desired protocol; if the protocol found in the network
     service database does not match this name, a system error is
     signalled.

     The `getserv' procedure will take either a service name or number
     as its first argument; if given no arguments, it behaves like
     `getservent' (see below).

          (getserv "imap" "tcp")
          => #("imap2" ("imap") 143 "tcp")

          (getservbyport 88 "udp")
          => #("kerberos" ("kerberos5" "krb5") 88 "udp")

   The following procedures may be used to step through the service
database from beginning to end.

 - Scheme Procedure: setservent [stayopen]
     Initialize an internal stream from which service objects may be
     read.  This procedure must be called before any calls to
     `getservent', and may also be called afterward to reset the
     service entry stream.  If STAYOPEN is supplied and is not `#f',
     the database is not closed by subsequent `getservbyname' or
     `getservbyport' calls, possibly giving an efficiency gain.

 - Scheme Procedure: getservent
     Return the next entry from the services database.

 - Scheme Procedure: endservent
     Close the stream used by `getservent'.  The return value is
     unspecified.

 - Scheme Procedure: setserv [stayopen]
 - C Function: scm_setserv (stayopen)
     If STAYOPEN is omitted, this is equivalent to `endservent'.
     Otherwise it is equivalent to `setservent stayopen'.

Network Sockets and Communication
---------------------------------

   Socket ports can be created using `socket' and `socketpair'.  The
ports are initially unbuffered, to make reading and writing to the same
port more reliable.  A buffer can be added to the port using `setvbuf',
see Ports and File Descriptors.

   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.

 - Scheme Procedure: socket family style proto
 - C Function: scm_socket (family, style, proto)
     Return a new socket port of the type specified by FAMILY, STYLE
     and PROTO.  All three parameters are integers.  Supported values
     for FAMILY are `AF_UNIX', `AF_INET' and `AF_INET6'.  Typical
     values for STYLE are `SOCK_STREAM', `SOCK_DGRAM' and `SOCK_RAW'.

     PROTO can be obtained from a protocol name using `getprotobyname'.
     A value of zero specifies the default protocol, which is usually
     right.

     A single socket port cannot by used for communication until it has
     been connected to another socket.

 - Scheme Procedure: socketpair family style proto
 - C Function: scm_socketpair (family, style, proto)
     Return a pair of connected (but unnamed) socket ports of the type
     specified by FAMILY, STYLE and PROTO.  Many systems support only
     socket pairs of the `AF_UNIX' family.  Zero is likely to be the
     only meaningful value for PROTO.

 - Scheme Procedure: getsockopt sock level optname
 - C Function: scm_getsockopt (sock, level, optname)
     Return the value of a particular socket option for the socket port
     SOCK.  LEVEL is an integer code for type of option being
     requested, e.g., `SOL_SOCKET' for socket-level options.  OPTNAME
     is an integer code for the option required and should be specified
     using one of the symbols `SO_DEBUG', `SO_REUSEADDR' etc.

     The returned value is typically an integer but `SO_LINGER' returns
     a pair of integers.

 - Scheme Procedure: setsockopt sock level optname value
 - C Function: scm_setsockopt (sock, level, optname, value)
     Set the value of a particular socket option for the socket port
     SOCK.  LEVEL is an integer code for type of option being set,
     e.g., `SOL_SOCKET' for socket-level options.  OPTNAME is an
     integer code for the option to set and should be specified using
     one of the symbols `SO_DEBUG', `SO_REUSEADDR' etc.  VALUE is the
     value to which the option should be set.  For most options this
     must be an integer, but for `SO_LINGER' it must be a pair.

     The return value is unspecified.

 - Scheme Procedure: shutdown sock how
 - C Function: scm_shutdown (sock, how)
     Sockets can be closed simply by using `close-port'. The `shutdown'
     procedure allows reception or transmission on a connection to be
     shut down individually, according to the parameter HOW:

    0
          Stop receiving data for this socket.  If further data
          arrives,  reject it.

    1
          Stop trying to transmit data from this socket.  Discard any
          data waiting to be sent.  Stop looking for acknowledgement of
          data already sent; don't retransmit it if it is lost.

    2
          Stop both reception and transmission.

     The return value is unspecified.

 - Scheme Procedure: connect sock fam address . args
 - C Function: scm_connect (sock, fam, address, args)
     Initiate a connection from a socket using a specified address
     family to the address specified by ADDRESS and possibly ARGS.  The
     format required for ADDRESS and ARGS depends on the family of the
     socket.

     For a socket of family `AF_UNIX', only ADDRESS is specified and
     must be a string with the filename where the socket is to be
     created.

     For a socket of family `AF_INET', ADDRESS must be an integer IPv4
     host address and ARGS must be a single integer port number.

     For a socket of family `AF_INET6', ADDRESS must be an integer IPv6
     host address and ARGS may be up to three integers: port [flowinfo]
     [scope_id], where flowinfo and scope_id default to zero.

     The return value is unspecified.

 - Scheme Procedure: bind sock fam address . args
 - C Function: scm_bind (sock, fam, address, args)
     Assign an address to the socket port 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 ADDRESS and ARGS depends on the family of the socket.

     For a socket of family `AF_UNIX', only ADDRESS is specified and
     must be a string with the filename where the socket is to be
     created.

     For a socket of family `AF_INET', ADDRESS must be an integer IPv4
     address and ARGS must be a single integer port number.

     The values of the following variables can also be used for ADDRESS:

      - Variable: INADDR_ANY
          Allow connections from any address.

      - Variable: INADDR_LOOPBACK
          The address of the local host using the loopback device.

      - Variable: INADDR_BROADCAST
          The broadcast address on the local network.

      - Variable: INADDR_NONE
          No address.

     For a socket of family `AF_INET6', ADDRESS must be an integer IPv6
     address and ARGS may be up to three integers: port [flowinfo]
     [scope_id], where flowinfo and scope_id default to zero.

     The return value is unspecified.

 - Scheme Procedure: listen sock backlog
 - C Function: scm_listen (sock, backlog)
     Enable SOCK to accept connection requests.  BACKLOG is an integer
     specifying the maximum length of the queue for pending connections.
     If the queue fills, new clients will fail to connect until the
     server calls `accept' to accept a connection from the queue.

     The return value is unspecified.

 - Scheme Procedure: accept sock
 - 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.

     The return value is a pair in which the _car_ is a new socket port
     for the connection and the _cdr_ is an object with address
     information about the client which initiated the connection.

     SOCK does not become part of the connection and will continue to
     accept new requests.

   The following functions take a socket address object, as returned by
`accept' and other procedures, and return a selected component.

`sockaddr:fam'
     The socket family, typically equal to the value of `AF_UNIX' or
     `AF_INET'.

`sockaddr:path'
     If the socket family is `AF_UNIX', returns the path of the
     filename the socket is based on.

`sockaddr:addr'
     If the socket family is `AF_INET', returns the Internet host
     address.

`sockaddr:port'
     If the socket family is `AF_INET', returns the Internet port
     number.

 - Scheme Procedure: getsockname sock
 - C Function: scm_getsockname (sock)
     Return the address of SOCK, in the same form as the object
     returned by `accept'.  On many systems the address of a socket in
     the `AF_FILE' namespace cannot be read.

 - Scheme Procedure: getpeername sock
 - C Function: scm_getpeername (sock)
     Return the address that SOCK is connected to, in the same form as
     the object returned by `accept'.  On many systems the address of a
     socket in the `AF_FILE' namespace cannot be read.

 - Scheme Procedure: recv! sock buf [flags]
 - C Function: scm_recv (sock, buf, flags)
     Receive data from a socket port.  SOCK must already be bound to
     the address from which data is to be received.  BUF is a string
     into which the data will be written.  The size of BUF limits the
     amount of data which can be received: in the case of packet
     protocols, if a packet larger than this limit is encountered then
     some data will be irrevocably lost.

     The optional FLAGS argument is a value or bitwise OR of MSG_OOB,
     MSG_PEEK, MSG_DONTROUTE etc.

     The value returned is the number of bytes read from the socket.

     Note that the data is read directly from the socket file
     descriptor: any unread buffered port data is ignored.

 - Scheme Procedure: send sock message [flags]
 - C Function: scm_send (sock, message, flags)
     Transmit the string MESSAGE on a socket port SOCK.  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 MESSAGE if the socket is set to be
     non-blocking.  The optional FLAGS argument is a value or bitwise
     OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.

     Note that the data is written directly to the socket file
     descriptor: any unflushed buffered port data is ignored.

 - Scheme Procedure: recvfrom! sock str [flags [start [end]]]
 - C Function: scm_recvfrom (sock, str, flags, start, end)
     Return data from the socket port SOCK and also information about
     where the data was received from.  SOCK must already be bound to
     the address from which data is to be received.  `str', is a string
     into which the data will be written.  The size of 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.

     The optional FLAGS argument is a value or bitwise OR of `MSG_OOB',
     `MSG_PEEK', `MSG_DONTROUTE' etc.

     The value returned is a pair: the _car_ is the number of bytes
     read from the socket and the _cdr_ an address object in the same
     form as returned by `accept'.  The address will given as `#f' if
     not available, as is usually the case for stream sockets.

     The START and END arguments specify a substring of 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.

 - Scheme Procedure: sendto sock message fam address . args_and_flags
 - C Function: scm_sendto (sock, message, fam, address, args_and_flags)
     Transmit the string MESSAGE on the socket port SOCK.  The
     destination address is specified using the FAM, ADDRESS and
     ARGS_AND_FLAGS arguments, in a similar way to the `connect'
     procedure.  ARGS_AND_FLAGS contains the usual connection arguments
     optionally followed by a flags argument, which is a value or
     bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.

     The value returned is the number of bytes transmitted - it's
     possible for this to be less than the length of MESSAGE if the
     socket is set to be non-blocking.  Note that the data is written
     directly to the socket file descriptor: any unflushed buffered
     port data is ignored.

   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.

 - Scheme Procedure: htons value
 - C Function: scm_htons (value)
     Convert a 16 bit quantity from host to network byte ordering.
     VALUE is packed into 2 bytes, which are then converted and
     returned as a new integer.

 - Scheme Procedure: ntohs value
 - C Function: scm_ntohs (value)
     Convert a 16 bit quantity from network to host byte ordering.
     VALUE is packed into 2 bytes, which are then converted and
     returned as a new integer.

 - Scheme Procedure: htonl value
 - C Function: scm_htonl (value)
     Convert a 32 bit quantity from host to network byte ordering.
     VALUE is packed into 4 bytes, which are then converted and
     returned as a new integer.

 - Scheme Procedure: ntohl value
 - C Function: scm_ntohl (value)
     Convert a 32 bit quantity from network to host byte ordering.
     VALUE is packed into 4 bytes, which are then converted and
     returned as a new integer.

   These procedures are inconvenient to use at present, but consider:

     (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)))))

Network Socket Examples
-----------------------

   The following sections give examples of how to use network sockets.

Internet Socket Client Example
..............................

   The following example demonstrates an Internet socket client.  It
connects to the HTTP daemon running on the local machine and returns
the contents of the root index URL.

     (let ((s (socket AF_INET SOCK_STREAM 0)))
       (connect s AF_INET (inet-aton "127.0.0.1") 80)
       (display "GET / HTTP/1.0\r\n\r\n" s)

       (do ((line (read-line s) (read-line s)))
           ((eof-object? line))
         (display line)
         (newline)))

Internet Socket Server Example
..............................

   The following example shows a simple Internet server which listens on
port 2904 for incoming connections and sends a greeting back to the
client.

     (let ((s (socket AF_INET SOCK_STREAM 0)))
       (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
       ;; Specific address?
       ;; (bind s AF_INET (inet-aton "127.0.0.1") 2904)
       (bind s AF_INET INADDR_ANY 2904)
       (listen s 5)

       (simple-format #t "Listening for clients in pid: ~S" (getpid))
       (newline)

       (while #t
              (let* ((client-connection (accept s))
                     (client-details (cdr client-connection))
                     (client (car client-connection)))
                (simple-format #t "Got new client connection: ~S"
                               client-details)
                (newline)
                (simple-format #t "Client address: ~S"
                               (gethostbyaddr
                                (sockaddr:addr client-details)))
                (newline)
                ;; Send back the greeting to the client port
                (display "Hello client\r\n" client)
                (close client))))

System Identification
=====================

   This section lists the various procedures Guile provides for
accessing information about the system it runs on.

 - Scheme Procedure: uname
 - C Function: scm_uname ()
     Return an object with some information about the computer system
     the program is running on.

   The following procedures accept an object as returned by `uname' and
return a selected component.

`utsname:sysname'
     The name of the operating system.

`utsname:nodename'
     The network name of the computer.

`utsname:release'
     The current release level of the operating system implementation.

`utsname:version'
     The current version level within the release of the operating
     system.

`utsname:machine'
     A description of the hardware.

 - Scheme Procedure: gethostname
 - C Function: scm_gethostname ()
     Return the host name of the current processor.

 - Scheme Procedure: sethostname name
 - C Function: scm_sethostname (name)
     Set the host name of the current processor to NAME. May only be
     used by the superuser.  The return value is not specified.

 - Scheme Procedure: software-type
     Return a symbol describing the current platform's operating system.
     This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2,
     THINKC, AMIGA, ATARIST, MACH, or ACORN.

     Note that most varieties of Unix are considered to be simply
     "UNIX".  That is because when a program depends on features that
     are not present on every operating system, it is usually better to
     test for the presence or absence of that specific feature.  The
     return value of `software-type' should only be used for this
     purpose when there is no other easy or unambiguous way of
     detecting such features.

Locales
=======

 - Scheme Procedure: setlocale category [locale]
 - C Function: scm_setlocale (category, locale)
     If LOCALE is omitted, return the current value of the specified
     locale category as a system-dependent string.  CATEGORY should be
     specified using the values `LC_COLLATE', `LC_ALL' etc.

     Otherwise the specified locale category is set to the string
     LOCALE and the new value is returned as a system-dependent string.
     If LOCALE is an empty string, the locale will be set using
     environment variables.

Encryption
==========

   Please note that the procedures in this section are not suited for
strong encryption, they are only interfaces to the well-known and
common system library functions of the same name.  They are just as good
(or bad) as the underlying functions, so you should refer to your system
documentation before using them.

 - Scheme Procedure: crypt key salt
 - C Function: scm_crypt (key, salt)
     Encrypt KEY using SALT as the salt value to the crypt(3) library
     call.

   Although `getpass' is not an encryption procedure per se, it appears
here because it is often used in combination with `crypt':

 - Scheme Procedure: getpass prompt
 - C Function: scm_getpass (prompt)
     Display PROMPT to the standard error output and read a password
     from `/dev/tty'.  If this file is not accessible, it reads from
     standard input.  The password may be up to 127 characters in
     length.  Additional characters and the terminating newline
     character are discarded.  While reading the password, echoing and
     the generation of signals by special characters is disabled.

SRFI Support Modules
********************

   SRFI is an acronym for Scheme Request For Implementation.  The SRFI
documents define a lot of syntactic and procedure extensions to standard
Scheme as defined in R5RS.

   Guile has support for a number of SRFIs.  This chapter gives an
overview over the available SRFIs and some usage hints.  For complete
documentation, design rationales and further examples, we advise you to
get the relevant SRFI documents from the SRFI home page
<http://srfi.schemers.org>.

About SRFI Usage
================

   SRFI support in Guile is currently implemented partly in the core
library, and partly as add-on modules.  That means that some SRFIs are
automatically available when the interpreter is started, whereas the
other SRFIs require you to use the appropriate support module
explicitly.

   There are several reasons for this inconsistency.  First, the feature
checking syntactic form `cond-expand' (see SRFI-0) must be
available immediately, because it must be there when the user wants to
check for the Scheme implementation, that is, before she can know that
it is safe to use `use-modules' to load SRFI support modules.  The
second reason is that some features defined in SRFIs had been
implemented in Guile before the developers started to add SRFI
implementations as modules (for example SRFI-6 (see SRFI-6)).  In
the future, it is possible that SRFIs in the core library might be
factored out into separate modules, requiring explicit module loading
when they are needed.  So you should be prepared to have to use
`use-modules' someday in the future to access SRFI-6 bindings.  If you
want, you can do that already.  We have included the module `(srfi
srfi-6)' in the distribution, which currently does nothing, but ensures
that you can write future-safe code.

   Generally, support for a specific SRFI is made available by using
modules named `(srfi srfi-NUMBER)', where NUMBER is the number of the
SRFI needed.  Another possibility is to use the command line option
`--use-srfi', which will load the necessary modules automatically
(see Invoking Guile).

SRFI-0 - cond-expand
====================

   SRFI-0 defines a means for checking whether a Scheme implementation
has support for a specified feature.  The syntactic form `cond-expand',
which implements this means, has the following syntax.

     <cond-expand>
       --> (cond-expand <cond-expand-clause>+)
         | (cond-expand <cond-expand-clause>* (else <command-or-definition>))
     <cond-expand-clause>
       --> (<feature-requirement> <command-or-definition>*)
     <feature-requirement>
       --> <feature-identifier>
         | (and <feature-requirement>*)
         | (or <feature-requirement>*)
         | (not <feature-requirement>)
     <feature-identifier>
       --> <a symbol which is the name or alias of a SRFI>

   When evaluated, this form checks all clauses in order, until it finds
one whose feature requirement is satisfied.  Then the form expands into
the commands or definitions in the clause.  A requirement is tested as
follows:

   * If it is a symbol, it is satisfied if the feature identifier is
     supported.

   * If it is an `and' form, all requirements must be satisfied.  If no
     requirements are given, it is satisfied, too.

   * If it is an `or' form, at least one of the requirements must be
     satisfied.  If no requirements are given, it is not satisfied.

   * If it is a `not' form, the feature requirement must _not_ be
     satisfied.

   * If the feature requirement is the keyword `else' and it is the last
     clause, it is satisfied if no prior clause matched.

   If no clause is satisfied, an error is signalled.

   Since `cond-expand' is needed to tell what a Scheme implementation
provides, it must be accessible without using any
implementation-dependent operations, such as `use-modules' in Guile.
Thus, it is not necessary to use any module to get access to this form.

   Currently, the feature identifiers `guile', `r5rs' and `srfi-0' are
supported.  The other SRFIs are not in that list by default, because
the SRFI modules must be explicitly used before their exported bindings
can be used.

   So if a Scheme program wishes to use SRFI-8, it has two
possibilities: First, it can check whether the running Scheme
implementation is Guile, and if it is, it can use the appropriate
module:

     (cond-expand
       (guile
         (use-modules (srfi srfi-8)))
       (srfi-8
         #t))
       ;; otherwise fail.

   The other possibility is to use the `--use-srfi' command line option
when invoking Guile (see Invoking Guile).  When you do that, the
specified SRFI support modules will be loaded and add their feature
identifier to the list of symbols checked by `cond-expand'.

   So, if you invoke Guile like this:

     $ guile --use-srfi=8

   the following snippet will expand to `'hooray'.

     (cond-expand (srfi-8 'hooray))

SRFI-1 - List library
=====================

   The list library defined in SRFI-1 contains a lot of useful list
processing procedures for construction, examining, destructuring and
manipulating lists and pairs.

   Since SRFI-1 also defines some procedures which are already contained
in R5RS and thus are supported by the Guile core library, some list and
pair procedures which appear in the SRFI-1 document may not appear in
this section.  So when looking for a particular list/pair processing
procedure, you should also have a look at the sections Lists
and Pairs.

Constructors
------------

   New lists can be constructed by calling one of the following
procedures.

 - Scheme Procedure: xcons d a
     Like `cons', but with interchanged arguments.  Useful mostly when
     passed to higher-order procedures.

 - Scheme Procedure: list-tabulate n init-proc
     Return an N-element list, where each list element is produced by
     applying the procedure INIT-PROC to the corresponding list index.
     The order in which INIT-PROC is applied to the indices is not
     specified.

 - Scheme Procedure: circular-list elt1 elt2 ...
     Return a circular list containing the given arguments ELT1 ELT2
     ....

 - Scheme Procedure: iota count [start step]
     Return a list containing COUNT elements, where each element is
     calculated as follows:

     START + (COUNT - 1) * STEP

     START defaults to 0 and STEP defaults to 1.

Predicates
----------

   The procedures in this section test specific properties of lists.

 - Scheme Procedure: proper-list? obj
     Return `#t' if OBJ is a proper list, that is a finite list,
     terminated with the empty list.  Otherwise, return `#f'.

 - Scheme Procedure: circular-list? obj
     Return `#t' if OBJ is a circular list, otherwise return `#f'.

 - Scheme Procedure: dotted-list? obj
     Return `#t' if OBJ is a dotted list, return `#f' otherwise.  A
     dotted list is a finite list which is not terminated by the empty
     list, but some other value.

 - Scheme Procedure: null-list? lst
     Return `#t' if LST is the empty list `()', `#f' otherwise.  If
     something else than a proper or circular list is passed as LST, an
     error is signalled.  This procedure is recommended for checking
     for the end of a list in contexts where dotted lists are not
     allowed.

 - Scheme Procedure: not-pair? obj
     Return `#t' is OBJ is not a pair, `#f' otherwise.  This is
     shorthand notation `(not (pair? OBJ))' and is supposed to be used
     for end-of-list checking in contexts where dotted lists are
     allowed.

 - Scheme Procedure: list= elt= list1 ...
     Return `#t' if all argument lists are equal, `#f' otherwise.  List
     equality is determined by testing whether all lists have the same
     length and the corresponding elements are equal in the sense of the
     equality predicate ELT=.  If no or only one list is given, `#t' is
     returned.