DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(guile.info.gz) Network Sockets and Communication

Info Catalog (guile.info.gz) Network Databases (guile.info.gz) Networking (guile.info.gz) Internet Socket Examples
 
 38.11.3 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',
  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 `PF_UNIX', `PF_INET' and `PF_INET6'.  Typical
      values for STYLE are `SOCK_STREAM', `SOCK_DGRAM', `SOCK_RAW',
      `SOCK_RDM' and `SOCK_SEQPACKET'.
 
      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)))))
 
Info Catalog (guile.info.gz) Network Databases (guile.info.gz) Networking (guile.info.gz) Internet Socket Examples
automatically generated byinfo2html