mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-10 05:50:26 +02:00
Code Activity

(Network Address Conversion): Move INADDR_ANY to here.

Browse source 
(Network Socket Address): New section, move sockaddr bits to here, add
new make-socket-address.
(Network Sockets and Communication): In connect, bind, and sendto, now
take socket address object.  In bind, leave INADDR constants for
"Network Address Conversion" node.  In those plus accept, getsockname,
getpeername, reword a bit for clarity.
This commit is contained in:
Kevin Ryde 2005-10-27 01:05:43 +00:00
parent 64cdbfc7af
commit 13ed23db8e
1 changed files with 144 additions and 119 deletions
Download patch file Download diff file Expand all files Collapse all files

255
doc/ref/posix.texi
View file

@ -2040,6 +2040,7 @@ the garbage collector pick them up at some later time.
@menu @menu
* Network Address Conversion:: * Network Address Conversion::
* Network Databases:: * Network Databases::
* Network Socket Address::
* Network Sockets and Communication:: * Network Sockets and Communication::
* Internet Socket Examples:: * Internet Socket Examples::
@end menu @end menu
@ -2058,15 +2059,21 @@ An IPv4 Internet address is a 4-byte value, represented in Guile as an
integer in network byte order (meaning the first byte is the most integer in network byte order (meaning the first byte is the most
significant in the number). significant in the number).
@defvar INADDR_LOOPBACK @defvar INADDR_ANY
The address of the local host using the loopback device, ie.@: For a server, this can be used with @code{bind} (@pxref{Network
@samp{127.0.0.1}. Sockets and Communication}) to allow connections from any interface on
the machine.
@end defvar @end defvar
@defvar INADDR_BROADCAST @defvar INADDR_BROADCAST
The broadcast address on the local network. The broadcast address on the local network.
@end defvar @end defvar
@defvar INADDR_LOOPBACK
The address of the local host using the loopback device, ie.@:
@samp{127.0.0.1}.
@end defvar
@c INADDR_NONE is defined in the code, but serves no purpose. @c INADDR_NONE is defined in the code, but serves no purpose.
@c inet_addr() returns it as an error indication, but that function @c inet_addr() returns it as an error indication, but that function
@c isn't provided, for the good reason that inet_aton() does the same @c isn't provided, for the good reason that inet_aton() does the same
@ -2437,6 +2444,71 @@ If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
Otherwise it is equivalent to @code{setservent stayopen}. Otherwise it is equivalent to @code{setservent stayopen}.
@end deffn @end deffn
@node Network Socket Address
@subsubsection Network Socket Address
@cindex socket
@cindex network socket
A socket address object identifies a socket endpoint for
communication. In the case of @code{AF_INET} for instance, the host
address is only the machine (or interface on the machine), a port
number is also needed to specify a particular open socket in a running
client or server process.
A socket address object can be created with,
@defun {Scheme Procedure} make-socket-address AF_INET ipv4addr port
@defunx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
@defunx {Scheme Procedure} make-socket-address AF_UNIX path
Return a new socket address object. The first argument is the address
family, one of the @code{AF} constants, then the arguments vary
according to the family.
For @code{AF_INET} the arguments are an IPv4 network address number
and a port number.
For @code{AF_INET6} the arguments are an IPv6 network address number
and a port number. Optional @var{flowinfo} and @var{scopeid}
arguments may be given (both integers, default 0).
For @code{AF_UNIX} the argument is a filename (a string).
@end defun
@noindent
The following functions access the fields of a socket address object,
@deffn {Scheme Procedure} sockaddr:fam sa
Return the address family from socket address object @var{sa}. This
is one of the @code{AF} constants (eg. @code{AF_INET}).
@end deffn
@deffn {Scheme Procedure} sockaddr:path sa
For an @code{AF_UNIX} socket address object @var{sa}, return the
filename.
@end deffn
@deffn {Scheme Procedure} sockaddr:addr sa
For an @code{AF_INET} or @code{AF_INET6} socket address object
@var{sa}, return the network address number.
@end deffn
@deffn {Scheme Procedure} sockaddr:port sa
For an @code{AF_INET} or @code{AF_INET6} socket address object
@var{sa}, return the port number.
@end deffn
@deffn {Scheme Procedure} sockaddr:flowinfo sa
For an @code{AF_INET6} socket address object @var{sa}, return the
flowinfo value.
@end deffn
@deffn {Scheme Procedure} sockaddr:scopeid sa
For an @code{AF_INET6} socket address object @var{sa}, return the
scope ID value.
@end deffn
@node Network Sockets and Communication @node Network Sockets and Communication
@subsubsection Network Sockets and Communication @subsubsection Network Sockets and Communication
@cindex socket @cindex socket
@ -2590,76 +2662,41 @@ Stop both reception and transmission.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@deffn {Scheme Procedure} connect sock fam address . args @deffn {Scheme Procedure} connect sock sockaddr
@deffnx {Scheme Procedure} connect sock AF_INET ipv4addr port
@deffnx {Scheme Procedure} connect sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
@deffnx {Scheme Procedure} connect sock AF_UNIX path
@deffnx {C Function} scm_connect (sock, fam, address, args) @deffnx {C Function} scm_connect (sock, fam, address, args)
Initiate a connection from a socket using a specified address Initiate a connection on socket port @var{sock} to a given address.
family to the address The destination is either a socket address object, or arguments the
specified by @var{address} and possibly @var{args}. same as @code{make-socket-address} would take to make such an object
The format required for @var{address} (@pxref{Network Socket Address}). The return value is unspecified.
and @var{args} depends on the family of the socket.
For a socket of family @code{AF_UNIX}, @example
only @var{address} is specified and must be a string with the (connect sock AF_INET INADDR_LOCALHOST 23)
filename where the socket is to be created. (connect sock (make-socket-address AF_INET INADDR_LOCALHOST 23))
@end example
For a socket of family @code{AF_INET},
@var{address} must be an integer IPv4 host address and
@var{args} must be a single integer port number.
For a socket of family @code{AF_INET6},
@var{address} must be an integer IPv6 host address and
@var{args} may be up to three integers:
port [flowinfo] [scope_id],
where flowinfo and scope_id default to zero.
The return value is unspecified.
@end deffn @end deffn
@deffn {Scheme Procedure} bind sock fam address . args @deffn {Scheme Procedure} bind sock sockaddr
@deffnx {Scheme Procedure} bind sock AF_INET ipv4addr port
@deffnx {Scheme Procedure} bind sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
@deffnx {Scheme Procedure} bind sock AF_UNIX path
@deffnx {C Function} scm_bind (sock, fam, address, args) @deffnx {C Function} scm_bind (sock, fam, address, args)
Assign an address to the socket port @var{sock}. Bind socket port @var{sock} to the given address. The address is
Generally this only needs to be done for server sockets, either a socket address object, or arguments the same as
so they know where to look for incoming connections. A socket @code{make-socket-address} would take to make such an object
without an address will be assigned one automatically when it (@pxref{Network Socket Address}). The return value is unspecified.
starts communicating.
The format of @var{address} and @var{args} depends Generally a socket is only explicitly bound to a particular address
on the family of the socket. when making a server, ie. to listen on a particular port. For an
outgoing connection the system will assign a local address
automatically, if not already bound.
For a socket of family @code{AF_UNIX}, only @var{address} @example
is specified and must be a string with the filename where (bind sock AF_INET INADDR_ANY 12345)
the socket is to be created. (bind sock (make-socket-object AF_INET INADDR_ANY 12345))
@end example
For a socket of family @code{AF_INET}, @var{address}
must be an integer IPv4 address and @var{args}
must be a single integer port number.
The values of the following variables can also be used for
@var{address}:
@defvar INADDR_ANY
Allow connections from any address.
@end defvar
@defvar INADDR_LOOPBACK
The address of the local host using the loopback device.
@end defvar
@defvar INADDR_BROADCAST
The broadcast address on the local network.
@end defvar
@defvar INADDR_NONE
No address.
@end defvar
For a socket of family @code{AF_INET6}, @var{address}
must be an integer IPv6 address and @var{args}
may be up to three integers:
port [flowinfo] [scope_id],
where flowinfo and scope_id default to zero.
The return value is unspecified.
@end deffn @end deffn
@deffn {Scheme Procedure} listen sock backlog @deffn {Scheme Procedure} listen sock backlog
@ -2676,55 +2713,40 @@ The return value is unspecified.
@deffn {Scheme Procedure} accept sock @deffn {Scheme Procedure} accept sock
@deffnx {C Function} scm_accept (sock) @deffnx {C Function} scm_accept (sock)
Accept a connection on a bound, listening socket. Accept a connection from socket port @var{sock} which has been enabled
If there for listening with @code{listen} above. If there are no incoming
are no pending connections in the queue, wait until connections in the queue, wait until one is available (unless the
one is available unless the non-blocking option has been non-blocking option has been set on the socket).
set on the socket.
The return value is a The return value is a pair. The @code{car} is a new socket port,
pair in which the @acronym{CAR} is a new socket port for the connected and ready to communicate. The @code{cdr} is a socket
connection and address object (@pxref{Network Socket Address}) which is where the
the @acronym{CDR} is an object with address information about the remote connection is from (like @code{getpeername} below).
client which initiated the connection.
@var{sock} does not become part of the All communication takes place using the new socket returned. The
connection and will continue to accept new requests. given @var{sock} remains bound and listening, and @code{accept} may be
@end deffn called on it again to get another incoming connection when desired.
The following functions take a socket address object, as returned
by @code{accept} and other procedures, and return a selected component.
@deffn {Scheme Procedure} sockaddr:fam sa
The socket family, typically equal to the value of @code{AF_UNIX} or
@code{AF_INET}.
@end deffn
@deffn {Scheme Procedure} sockaddr:path sa
If the socket family is @code{AF_UNIX}, returns the path of the
filename the socket is based on.
@end deffn
@deffn {Scheme Procedure} sockaddr:addr sa
If the socket family is @code{AF_INET}, returns the Internet host
address.
@end deffn
@deffn {Scheme Procedure} sockaddr:port sa
If the socket family is @code{AF_INET}, returns the Internet port
number.
@end deffn @end deffn
@deffn {Scheme Procedure} getsockname sock @deffn {Scheme Procedure} getsockname sock
@deffnx {C Function} scm_getsockname (sock) @deffnx {C Function} scm_getsockname (sock)
Return the address of @var{sock}, in the same form as the Return a socket address object which is the where @var{sock} is bound
object returned by @code{accept}. On many systems the address locally. @var{sock} may have obtained its local address from
of a socket in the @code{AF_FILE} namespace cannot be read. @code{bind} (above), or if a @code{connect} is done with an otherwise
unbound socket (which is usual) then the system will have assigned an
address.
Note that on many systems the address of a socket in the
@code{AF_UNIX} namespace cannot be read.
@end deffn @end deffn
@deffn {Scheme Procedure} getpeername sock @deffn {Scheme Procedure} getpeername sock
@deffnx {C Function} scm_getpeername (sock) @deffnx {C Function} scm_getpeername (sock)
Return the address that @var{sock} Return a socket address object which is where @var{sock} is connected
is connected to, in the same form as the object returned by to, ie. the remote endpoint.
@code{accept}. On many systems the address of a socket in the
@code{AF_FILE} namespace cannot be read. Note that on many systems the address of a socket in the
@code{AF_UNIX} namespace cannot be read.
@end deffn @end deffn
@deffn {Scheme Procedure} recv! sock buf [flags] @deffn {Scheme Procedure} recv! sock buf [flags]
@ -2801,17 +2823,20 @@ Note that the data is read directly from the socket file
descriptor: any unread buffered port data is ignored. descriptor: any unread buffered port data is ignored.
@end deffn @end deffn
@deffn {Scheme Procedure} sendto sock message fam address . args_and_flags @deffn {Scheme Procedure} sendto sock message sockaddr [flags]
@deffnx {Scheme Procedure} sendto sock message AF_INET ipv4addr port [flags]
@deffnx {Scheme Procedure} sendto sock message AF_INET6 ipv6addr port [flowinfo [scopeid [flags]]]
@deffnx {Scheme Procedure} sendto sock message AF_UNIX path [flags]
@deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags) @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
Transmit the string @var{message} on the socket port Transmit the string @var{message} as a datagram on socket port
@var{sock}. The @var{sock}. The destination is specified either as a socket address
destination address is specified using the @var{fam}, object, or as arguments the same as would be taken by
@var{address} and @code{make-socket-address} to create such an object (@pxref{Network
@var{args_and_flags} arguments, in a similar way to the Socket Address}).
@code{connect} procedure. @var{args_and_flags} contains
the usual connection arguments optionally followed by The destination address may be followed by an optional @var{flags}
a flags argument, which is a value or argument which is a @code{logior} (@pxref{Bitwise Operations}) of
bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
The value returned is the number of bytes transmitted -- The value returned is the number of bytes transmitted --
it's possible for it's possible for