libsocket 0.8.0 Manual Copyright © 1999, 2000 by Richard Dawe and Alain Magloire
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License" (see GNU Free Documentation License).
libsocket:
Copyright © 1997, 1998 by Indrek Mandre
Copyright © 1997-2000 by Richard Dawe
Portions of libsocket:
libsocket is distributed under the terms of the GNU Library General Public License (the GNU LGPL) (see License). Please read the license before using libsocket.
libsocket is a BSD sockets library for DJGPP. It provides DJGPP programs with TCP/IP networking as well as Unix domain sockets, a form of Interprocess Communication (IPC). BSD sockets are the de facto programming interface for networking on Unix systems. Programs written to this interface can be ported to many platforms. The Windows network programming interface, Winsock, is derived from BSD sockets.
libsocket supports the following operating systems:
Please note that libsocket has not been tested under Windows 3.x for a long time. It should work, since it uses mostly the same methods as Windows '95. Any feedback would be appreciated here.
Please also note that libsocket has not been tested under Windows '98 during development, since the maintainer does not have Windows '98. It has been reported variously to work/not work.
demo/diag.exe and demo/httpget.exe. diag lists
libsocket's configuration (a diagnostic tool); httpget retrieves
the specified URL from the web and dumps it to the screen, e.g.:
httpget http://www.slashdot.org/
contrib/ls080/doc/beejng.
You can jump directly to functions in the alphabetical index:
info libsocket alpha socket
Firstly check that you haven't encountered one of the known bugs (see Known Bugs). You should also read the release notes (if any) that came with libsocket.
Secondly check that there isn't any news at the libsocket home page. More directly:
If this doesn't help, please ask a question in the DJGPP newsgroup
(mailto:djgpp@delorie.com or news:comp.os.msdos.djgpp)
and the libsocket mailing list.
Please include the output of demo/diag.exe and your libsocket
configuration files (see Configuration).
libsocket is maintained by Richard Dawe:
webmaster@phekda.gotadsl.co.uk
http://www.bigfoot.com/~richdawe/
#include <sys/types.h> #include <sys/socket.h> int accept (int s, struct sockaddr *address, size_t *addresslen);
The accept() function returns the first completed connection from the
the pending connection queue form a listening socket. The parameter s
is a socket descriptor that has been created with socket(), bound
to a local socket-address with bind() and is listening for connections
after listen(). The accept() will return a brand new socket
descriptor. If the socket is not marked non-blocking, accept()
blocks the caller until a connection is present. If marked non-blocking
and no pending connections are present it returns -1 and set errno to
EWOULDBLOCK. If address is not NULL it specifies a buffer
in which to return the socket address, the addresslen is a value-result
that specified the amount of space for address. On return
when addresslen will hold the size written to address.
On successful completion the function returns the descriptor of the accepted socket. Otherwise, a value of -1, and errno is set.
EBADF
ECONNABORTED
EINTR
EINVAL
EMFILE
ENFILE
ENOBUFS
ENOTSOCK
EOPNOTSUPP
accept()
EWOULDBLOCK
POSIX, Unix98
#include <sys/types.h> #include <sys/socket.h> int bind (int s, const struct sockaddr *address, size_t addresslen);
The bind() function assigns a local socket-address to socket s
that has no local socket-address assigned. When a socket is created with
socket() it is associated with a specific protocol from the protocol
and in the case of libsocket also an interface, but has no local socket-address
assigned. This function requests that the local socket-address
address be assigned to it. The format of the socket-address
dpends on the address family, for example AF_INET,
AF_UNIX (also known as AF_LOCAL).
On successful completion the function returns 0. Otherwise, a value of -1, and errno is set.
EACCESS
EADDRINUSE
EADDRNOTAVAIL
EBADF
EINVAL
ENOBUFS
ENOTSOCK
POSIX, Unix98
#include <sys/types.h> #include <sys/socket.h> int connect (int s, struct sockaddr *serv_addr, size_t *addrlen);
If s refers to a stream socket (SOCK_STREAM), connect()
will attempt to establish a connection to the specified destination address.
If s refers to a datagram socket (SOCK_DGRAM), connect()
associates a default destination address for use by send() and
sendto(). It also limits recv() calls to receiving from this
address, rather than the default of any. To remove the association, call
connect() with an invalid address, e.g. a null address (0.0.0.0).
On successful completion the function returns zero. Otherwise, a value of -1 is returned and errno is set appropriately.
EBADF
EFAULT
ENOTSOCK
EISCONN
ECONNREFUSED
ETIMEDOUT
ENETUNREACH
EADDRINUSE
EINTR
EOPNOTSUPP
connect().
EINPROGRESS
getsockopt() to read the option SO_ERROR at level
SOL_SOCKET to check if the call completed successfully -
SO_ERROR's value will be 0 on success, or an errno value
otherwise.
EALREADY
connect() request is
completing.
POSIX, Unix98
#include <resolv.h>
int dn_comp (unsigned char *exp_dn, unsigned char *comp_dn, int length,
unsigned char **dnptrs, unsigned char *exp_dn,
unsigned char **lastdnptr);
The dn_comp() function compresses the domain name exp_dn
and stores it in the buffer comp_dn of length length.
The compression uses an array of pointers dnptrs to previously
compressed names in the current message. The first pointer points
to the beginning of the message and the list ends with NULL. The limit
of the array is specified by lastdnptr. If dnptr is NULL,
domain names are not compressed. If lastdnptr is NULL, the list
of labels is not updated.
See dn_expand.
The dn_comp() function returns the length of the compressed name,
or -1 if an error occurs.
This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux.
#include <resolv.h>
int dn_expand (unsigned char *msg, unsigned char *eomorig,
unsigned char *comp_dn, unsigned char *exp_dn,
int length);
The dn_expand() function expands the compressed domain name
comp_dn to a full domain name, which is placed in the buffer
exp_dn of size length. The compressed name is contained
in a query or reply message, and msg points to the beginning of
the message.
See dn_comp.
The dn_expand() function returns the length of the compressed name,
or -1 if an error occurs.
This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux.
#include <netdb.h> void endhostent (void);
The endhostent() function ends the use of a TCP connection for name
server queries.
None
Unix98
#include <netdb.h> void endnetent (void);
The endnetent() function closes networks (see networks).
None
Unix98
#include <netdb.h> void endprotoent (void);
The endprotoent() function closes the protocols file
(see protocols).
None
Unix98
#include <netdb.h> void endservent (void);
The endservent() function closes services (see services).
None
Unix98
#include <lsck/domname.h> int getdomainname (char *name, size_t len);
This function is used to access the domain name. The domain name can be set
by setdomainname() (see setdomainname). The domain name is the
last component of the host name (see gethostname).
On success, zero is returned. On error, -1 is returned, and errno is set appropriately.
EINVAL
NULL or name is longer than len.
not POSIX, not Unix98
This function is defined in unistd.h on Linux.
#include <netdb.h> #include <sys/socket.h> extern int h_errno; struct hostent *gethostbyaddr (const char *addr, int len, int type);
The gethostbyaddr() function returns a structure of type hostent
for the given host address addr of length len and address type
type. The only valid address type is currently AF_INET.
The hostent structure is defined in the description of
gethostbyname() (see gethostbyname).
The gethostbyaddr() function return the hostent structure or
a NULL pointer if an error occurs. On error, the h_errno variable
holds an error number. h_errno can have the same values as for
gethostbyname() (see gethostbyname).
The herror() function will print an error message, based on the value
of h_errno (see herror).
Unix98
#include <netdb.h> extern int h_errno; struct hostent *gethostbyname (const char *name)
The gethostbyname() function returns a structure of type hostent
for the given host name. Here name is either a host name, or
an IPv4 address in standard dot notation, or an IPv6 address in colon
(and possibly dot) notation. (See RFC 1884 for the description of IPv6
addresses.) If name doesn't end in a dot
and the environment variable HOSTALIASES is set, the alias file
pointed to by HOSTALIASES will first be searched for name.
The current domain and its parents are searched unless name ends in a dot.
The domain name queries carried out by gethostbyname() use
a combination of any or all of:
named;
hosts (see hosts);
depending upon the contents of the order line in host.conf
(see host.conf). The default action is to query hosts
(see hosts).
The hostent structure is defined in <netdb.h> as follows:
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */
The members of the hostent structure are:
h_name
h_aliases
h_addrtype
h_length
h_addr_list
h_addr
h_addr_list for backward compatibility.
The gethostbyname() function returns a hostent structure or a
NULL pointer if an error occurs. On error, the h_errno variable holds
an error number.
The variable h_errno can have the following values:
HOST_NOT_FOUND
NO_ADDRESS
NO_RECOVERY
TRY_AGAIN
The herror() function will print an error message, based on the value
of h_errno (see herror).
Unix98
#include <netdb.h> struct hostent *gethostent (void);
The gethostent() function reads the next line from the file
hosts (see hosts) and returns a structure hostent
containing the broken out fields from the line. The hosts file
is opened if necessary.
The hostent structure is defined in the description of
gethostbyname() (see gethostbyname).
The gethostent() function return the hostent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <unistd.h> int gethostname (char *name, size_t len);
This function is used to access the host name of the current processor. The
host name is set using sethostname() (see sethostname). The
domain name component can be retrieved and set using getdomainname()
and setdomainname() respectively (see getdomainname,
see setdomainname).
libsocket's implementation of gethostname() overrides DJGPP's
implementation (see gethostname). libsocket will fall
back the DJGPP's implementation when it cannot find the host name from its
additional sources.
If a host name has not been set using sethostname(), then it is
determined in the following order:
HOSTNAME;
gethostname() implementation.
On success, zero is returned. On error, -1 is returned, and errno
is set appropriately.
EINVAL
EFAULT
not POSIX, not Unix98
#include <netdb.h> struct netent *getnetbyaddr (long net, int type);
The getnetbyaddr() function returns a netent structure
for the line from networks (see networks) that matches
the network number net of type type.
The netent structure is defined in the description of
getnetbyname() (see getnetbyname).
The getnetbyaddr() function return the netent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <netdb.h> struct netent *getnetbyname (const char *name);
The getnetbyname() function returns a netent structure
for the line from networks (see networks) that matches the network
name.
The netent structure is defined in <netdb.h> as follows:
struct netent {
char *n_name; /* official network name */
char **n_aliases; /* alias list */
int n_addrtype; /* net address type */
unsigned long int n_net; /* network number */
}
The members of the netent structure are:
n_name
n_aliases
n_addrtype
n_net
The getnetbyname() function return the netent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <netdb.h> struct netent *getnetent(void);
The getnetent() function reads the next line from the file
networks (see networks) and returns a structure netent
containing the broken out fields from the line. The networks file
is opened if necessary.
The netent structure is defined in the description of
getnetbyname() (see getnetbyname).
The getnetent() function return the netent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <sys/socket.h> int getpeername (int s, struct sockaddr *name, size_t *namelen);
getpeername() returns the name of the peer connected to the socket
s. namelen should be set to the size of the space pointed to by
name. On completion namelen will contain the length of the
address returned. If the buffer is too small, the address is truncated to
fit.
getsockname() returns the local name for the socket
(see getsockname).
On successful completion the function returns 0. Otherwise, a value of -1 is returned and errno is set appropriately.
EBADF
ENOTSOCK
ENOTCONN
ENOBUFS
EFAULT
POSIX, Unix98
#include <netdb.h> struct protoent *getprotobyname (const char *name);
The getprotobyname() function returns a protoent
structure for the line from protocols (see protocols) that matches
the protocol name name.
The protoent structure is defined in <netdb.h> as follows:
struct protoent {
char *p_name; /* official protocol name */
char **p_aliases; /* alias list */
int p_proto; /* protocol number */
}
The members of the protoent structure are:
p_name
p_aliases
p_proto
The getprotobyname() function returns the protoent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <netdb.h> struct protoent *getprotobynumber (int proto);
The getprotobynumber() function returns a protoent
structure for the line from protocols (see protocols) that matches
the protocol number number.
The protoent structure is defined in the description of
getprotobyname() (see getprotobyname).
The getprotobynumber() function return the protoent structure,
or a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <netdb.h> struct protoent *getprotoent (void);
The getprotoent() function reads the next line from the file
protocols (see protocols) and returns a structure
protoent containing the broken out fields from the line.
The protocols file is opened if necessary.
The protoent structure is defined in the description of
getprotobyname() (see getprotobyname).
On successful completion the function returns a protoent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <netdb.h> struct servent *getservbyname (const char *name, const char *proto);
The getservbyname() function returns a servent structure
for the line from services (see services) that matches the service
name using protocol proto.
The servent structure is defined in <netdb.h> as follows:
struct servent {
char *s_name; /* official service name */
char **s_aliases; /* alias list */
int s_port; /* port number */
char *s_proto; /* protocol to use */
}
The members of the servent structure are:
s_name
s_aliases
s_port
s_proto
The getservbyname() function return the servent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <netdb.h> struct servent *getservbyport (int port, const char *proto);
The getservbyport() function returns a servent structure
for the line from services (see services) that matches the port
port given in network byte order using protocol proto.
The servent structure is defined in the description of
getservbyname() (see getservbyname).
The getservbyport() function return the servent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <netdb.h> struct servent *getservent (void);
The getservent() function reads the next line from the file
services (see services) and returns a structure
servent containing the broken out fields from the line.
The services file is opened if necessary.
The servent structure is defined in the description of
getservbyname() (see getservbyname).
The getservent() function return the servent structure, or
a NULL pointer if an error occurs or the end of the file is reached.
Unix98
#include <sys/socket.h> int getsockname (int s, struct sockaddr *name, size_t *namelen);
getsockname() returns the local name of the socket s.
namelen should be set to the size of the space pointed to by
name. On completion namelen will contain the length of the
address returned. If the buffer is too small, the address is truncated to
fit.
getpeername() returns the peer name for the socket
(see getpeername).
On successful completion the function returns 0. Otherwise, a value of -1 is returned and errno is set appropriately.
EBADF
ENOTSOCK
ENOBUFS
EFAULT
POSIX, Unix98
#include <sys/types.h>
#include <sys/socket.h>
int getsockopt (int s, int level, int optname,
void *optval, int *optlen);
The getsockopt() function manipulates the options associated with a
socket. Options may exist at multiple protocol levels; they are always present
at the uppermost socket level.
When manipulating socket options the level at which the option resides and the
name of the option must be specified. To manipulate options at the socket
level, level is specified as SOL_SOCKET. To manipulate options at
any other level the protocol number of the appropriate protocol controlling
the option is supplied. For example, to indicate that an option is to be
interpreted by the TCP protocol, level should be set to the protocol
number of TCP, e.g. IPPROTO_TCP (see getprotoent).
The parameters optval and optlen are used to identify a buffer in which the value for the requested option(s) are to be returned. optlen is a value-result parameter, initially containing the size of the buffer pointed to by optval, and modified on return to indicate the actual size of the value returned. If no option value is to be supplied or returned, optval may be NULL.
optname and any specified options are passed uninterpreted to the
appropriate protocol module for interpretation. The include file
<sys/socket.h> contains definitions for socket level options, described
below. Options at other protocol levels vary in format and name.
Most socket-level options utilize an int parameter for optval.
SO_LINGER uses a struct linger parameter, defined in
<sys/socket.h>, which specifies the desired state of the option and the
linger interval (see below).
SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval
parameter, defined in <sys/time.h>.
The following options are recognized at the socket level:
SO_DEBUG
SO_REUSEADDR
SO_KEEPALIVE
SO_DONTROUTE
SO_LINGER
SO_BROADCAST
SO_OOBINLINE
SO_SNDBUF
SO_RCVBUF
SO_SNDLOWAT
SO_RCVLOWAT
SO_SNDTIMEO
SO_RCVTIMEO
SO_TYPE
SO_ERROR
SO_DEBUG enables debugging in the underlying protocol modules.
SO_REUSEADDR indicates that the rules used in validating addresses
supplied in a bind() call should allow reuse of local addresses
(see bind).
SO_KEEPALIVE
enables the periodic transmission of messages on a connected socket.
Should the connected party fail to respond to these messages, the
connection is considered broken and processes using the socket are notified
via a SIGPIPE signal when attempting to send data.
SO_DONTROUTE
indicates that outgoing messages should bypass the standard routing
facilities. Instead, messages are directed to the appropriate network
interface according to the network portion of the destination address.
SO_LINGER controls the action taken when unsent messages
are queued on socket and a close() is performed
(see close). If the socket promises reliable delivery of
data and SO_LINGER is set, the system will block the process on the
close() attempt until it is able to transmit the data or until it
decides it is unable to deliver the information (a timeout period, termed the
linger interval, is specified in the setsockopt() call when
SO_LINGER is requested). If SO_LINGER is disabled and a
close() is issued, the system will process the close in a manner that
allows the process to continue as quickly as possible.
The linger structure is defined in <sys/socket.h>
as follows:
struct linger {
int l_onoff; /* Linger active */
int l_linger; /* How long to linger for */
};
l_onoff indicates whether to linger or not. If it is set to 1 then
l_linger contains the time in hundredths of seconds how long the process
should linger to complete the close(). If l_onoff
is set to zero the process returns immediately.
The option SO_BROADCAST requests permission to send broadcast datagrams
on the socket. Broadcast was a privileged operation in earlier versions of
the system. With protocols that support out-of-band data, the
SO_OOBINLINE option requests that out-of-band data be placed in the
normal data input queue as received; it will then be accessible with
recv() or read() calls without the MSG_OOB
flag (see recv, see read). Some protocols behave
as if this option were always set.
SO_SNDBUF and SO_RCVBUF
are options to adjust the normal buffer sizes allocated for output and
input buffers, respectively. The buffer size may be increased for
high-volume connections, or may be decreased to limit the possible backlog
of incoming data. The system places an absolute limit on these values.
SO_SNDLOWAT
is an option to set the minimum count for output operations. Most output
operations process all of the data supplied by the call, delivering data to
the protocol for transmission and blocking as necessary for flow control.
Nonblocking output operations will process as much data as permitted
subject to flow control without blocking, but will process no data if flow
control does not allow the smaller of the low water mark value or the
entire request to be processed. A select()
(see select) operation testing the ability to write to a
socket will return true only if the low water mark amount could be processed.
The default value for SO_SNDLOWAT is set to a convenient size for
network efficiency, often 1024.
SO_RCVLOWAT
is an option to set the minimum count for input operations. In general,
receive calls (see recv, see recvfrom) will block until any (non-zero)
amount of data is received, then return with smaller of the amount available
or the amount requested. The default value for SO_RCVLOWAT is 1.
If SO_RCVLOWAT is set to a larger value, blocking receive calls
normally wait until they have received the smaller of the low water mark value
or the requested amount. Receive calls may still return less than the low
water mark if an error occurs, a signal is caught, or the type of data next in
the receive queue is different than that returned.
SO_SNDTIMEO is an option to get the timeout value for output operations.
It returns a struct timeval parameter with the number of seconds and
microseconds used to limit waits for output operations to complete. If a send
operation has blocked for this much time, it returns with a partial count or
with the error EWOULDBLOCK if no data were sent. In the current
implementation, this timer is restarted each time additional data are
delivered to the protocol, implying that the limit applies to output portions
ranging in size from the low water mark to the high water mark for output.
SO_RCVTIMEO is an option to get the timeout value for input operations.
It returns a struct timeval
parameter with the number of seconds and microseconds used to limit waits
for input operations to complete. In the current implementation, this
timer is restarted each time additional data are received by the protocol,
and thus the limit is in effect an inactivity timer. If a receive
operation has been blocked for this much time without receiving additional
data, it returns with a short count or with the error
EWOULDBLOCK if no data were received.
SO_TYPE returns the type of the socket, such as SOCK_STREAM;
it is useful for servers that inherit sockets on startup.
SO_ERROR returns any pending error on the socket and clears the error
status. It may be used to check for asynchronous errors on connected datagram
sockets or for other asynchronous errors.
On success, zero is returned. On error, -1 is returned, and errno
is set appropriately.
EBADF
ENOTSOCK
ENOPROTOOPT
EFAULT
POSIX, Unix98
#include <netdb.h> extern int h_errno; void herror (const char *s);
The herror() function prints the error message associated with the
current value of h_errno on stderr. The values for h_errno
are described with gethostbyname() (see gethostbyname).
None
not Unix98
While the herror() function is not portable to Unix98, the
h_errno variable is.
#include <net/if.h> void if_freenameindex (struct if_nameindex *ptr);
This function frees the memory used by the array returned by
See if_nameindex. The program should not use ptr after calling
if_freenameindex().
None. However, an error may occur. The error code will be stored in errno.
Possible errors for this function are:
EFAULT
Open Group XNS 5.2 Draft 1.0
#include <net/if.h> char *if_nametoindex (unsigned int ifindex, char *ifname);
This returns the interface name corresponding to ifindex in the buffer
ifname. The buffer pointed to ifname must be at least
IFNAMESIZE bytes in size.
The interface name will be placed into ifname, if ifindex is a
valid interface index. Otherwise NULL is returned and errno
contains the error code.
Possible errors for this function are:
EFAULT
ENXIO
Open Group XNS 5.2 Draft 1.0
#include <net/if.h> struct if_nameindex *if_nameindex (void);
This function returns an array of if_nameindex structures, one per
interface. The array is terminated with an entry with a if_index field
of 0 and a if_name field of NULL.
The function if_freenameindex() (see if_freenameindex) should be
called, passing the pointer returned by this function, in order to free memory.
A pointer to the array of if_nameindex structures or NULL on
error. On error, errno will contain the error code.
Possible errors for this function are:
ENOBUFS
Open Group XNS 5.2 Draft 1.0
#include <net/if.h> unsigned int if_nametoindex (const char *ifname);
This returns the interface index corresponding to ifname.
The interface index will be returned if ifname is an interface name, else 0. If an error occurs, -1 will be returned and the error will be stored in errno.
Possible errors for this function are:
EFAULT
Open Group XNS 5.2 Draft 1.0
#include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> unsigned long int inet_addr (const char *cp);
The inet_addr() function converts the Internet host address
cp from numbers-and-dots notation into binary data in network
byte order. If the input is invalid, -1 is returned. This is an
obsolete interface to inet_aton() (see inet_aton); it is
obsolete because -1 is a valid address (255.255.255.255),
and inet_aton() provides a cleaner way to indicate error return.
If the input is invalid, -1 is returned. Otherwise, the IP address is returned as a 32-bit unsigned integer in network order.
Unix98
#include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> int inet_aton (const char *cp, struct in_addr *inp);
inet_aton() converts the Internet host address cp from the
standard numbers-and-dots notation into binary data and stores it in
the structure that inp points to.
The structure in_addr is defined in the description of
inet_ntoa() (see inet_ntoa).
Non-zero is returned, if the address is valid; otherwise zero is returned.
Unix98
#include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> unsigned long int inet_lnaof (struct in_addr in);
The inet_lnaof() function returns the local host address part
of the Internet address in. The local host address is returned
in local host byte order.
The structure in_addr is defined in the description of
inet_ntoa() (see inet_ntoa).
The local host address portion is returned.
Unix98
#include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> struct in_addr inet_makeaddr (int net, int host);
The inet_makeaddr() function makes an Internet host address
in network byte order by combining the network number net
with the local address host in network net, both in
local host byte order.
The structure in_addr is defined in the description of
inet_ntoa() (see inet_ntoa).
An Internet host addess is returned.
Unix98
#include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> unsigned long int inet_netof (struct in_addr in);
The inet_netof() function returns the network number part of
the Internet Address in. The network number is returned in
local host byte order.
The structure in_addr is defined in the description of
inet_ntoa() (see inet_ntoa).
The network number portion is returned.
Unix98
#include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> unsigned long int inet_network (const char *cp);
The inet_network() function extracts the network number in
network byte order from the address cp in numbers-and-dots
notation.
If the input is invalid, -1 is returned.
Unix98
#include <sys/socket.h> #include <netinet/in.h> #include <arpa/inet.h> char *inet_ntoa (struct in_addr in);
The inet_ntoa() function converts the Internet host address
in given in network byte order to a string in standard
numbers-and-dots notation. The string is returned in a statically
allocated buffer, which subsequent calls will overwrite.
The structure in_addr is defined in netinet/in.h as:
struct in_addr {
unsigned long int s_addr;
}
Note that on the i80x86 the host byte order is Least Significant Byte first, whereas the network byte order, as used on the Internet, is Most Significant Byte first.
inet_ntoa() returns a pointer to the address in string form.
Unix98
#include <sys/socket.h> #include <arpa/inet.h> const char *inet_ntop (int af, const void *src, char *dst, size_t size);
This function converts network addresses from numeric format (i.e. binary)
into presentation format (i.e. strings). This is a replacement for
inet_ntoa (see inet_ntoa), which cannot cope with IPv6 addresses.
af specifies the address family of the numeric format, e.g.
AF_INET or AF_INET6. The numeric data in src will be
converted in presentation format and stored in dst.
size specifies the size of the buffer pointed to by dst - it must
be large enough to store the presentation format address. The constants
INET_ADDRSTRLEN and INET6_ADDRSTRLEN are defined in
netinet/in.h as the maximum presentation string lengths, including
terminating nuls.
On successful completion the function returns a pointer to the presentation format string. Otherwise, a value of NULL is returned and errno is set appropriately.
EFAULT
ENOSPC
EAFNOSUPPORT
POSIX
#include <sys/socket.h> #include <arpa/inet.h> int inet_pton (int af, const char *src, void *dst);
This function converts network addresses from presentation format
(i.e. strings) into numeric format (i.e. binary). This is a replacement for
inet_aton (see inet_aton), which cannot cope with IPv6 addresses.
af specifies the address family of the presentation format, e.g.
AF_INET or AF_INET6. The address string src will be
converted to the appropriate address format, e.g. struct in_addr or
struct in6_addr, and stored in dst.
On successful completion the function returns 1. If the presentation format
is not understood, 0 is returned. If the address family af is not
known or supported, -1 is returned and errno is set to
EAFNOSUPPORT.
POSIX
#include <sys/ioctl.h> #include <ioctls.h> #include <sys/socket.h> #include <net/if.h>
This page documents the ioctls that are supported by libsocket. These are
used with the ioctl() function (see ioctl). Many
BSD ioctls are not listed here, because libsocket does not support them.
Some BSD socket ioctls are supported.
FIONBIO
ioctl() should be passed
an integer - if this is non-zero, non-blocking I/O will be enabled,
otherwise blocking I/O will be used.
/* Flip into non-blocking mode */ int x = 1; ioctl(sock, FIONBIO, &x);
FIONBIO is like the O_NONBLOCK flag that can be set using
fcntl() (see fcntl):
/* Flip into non-blocking mode */ int flags = flags = fcntl(sock, F_GETFL); flags |= O_NONBLOCK; fcntl(sock, F_SETFL, flags);
FIONREAD
ioctl() should
be passed an integer - on return this will contain the maximum read size.
int maxsz = 0; ioctl(sock, FIONREAD, &maxsz)
SIOCATMARK
SOCK_STREAM type sockets that have been set with the option
SO_OOBINLINE (see getsockopt, see setsockopt).
It returns 1 (true) or 0 (false) in the ioctl parameter.
The sockatmark() function should be used instead (see sockatmark).
SIOCGIFNAME
IFNAMSIZ.
The pointer to the buffer is passed as the parameter to ioctl, e.g.
ioctl(sock, SIOCGIFNAME, (int *) name)
SIOCGIFADDR
struct ifreq. The pointer to the buffer is passed as the parameter to
ioctl, e.g.
ioctl(sock, SIOCGIFADDR, (int *) &ifr)
The socket address can then be accessed via the ifr_ifru.ifru_addr
member of struct ifreq.
SIOCGIFDSTADDR
struct ifreq. The pointer to the buffer is passed as the parameter to
ioctl, e.g.
ioctl(sock, SIOCGIFDSTADDR, (int *) &ifr)
The peer's socket address can then be accessed via the
ifr_ifru.ifru_dstaddr member of struct ifreq.
SIOCGIFNETMASK
struct ifreq. The pointer to the buffer is passed as the parameter to
ioctl, e.g.
ioctl(sock, SIOCGIFDSTADDR, (int *) &ifr)
The peer's socket address can then be accessed via the
ifr_ifru.ifru_netmask member of struct ifreq.
ioctls cannot be guaranteed to be portable. However, because of the ubiquity of BSD sockets, these ioctls should work on most Unices.
#include <sys/socket.h> int isfdtype (int fd, int fd_type);
The isfdtype() function determines whether the file descriptor fd
has the properties specified by fd_type.
Valid values of fd_type include:
S_IFSOCK
1 if the type matches, 0 otherwise. If an error occurs, -1 is returned and errno is set to:
EBADF
POSIX, not Unix98
isfdtype() is usually declared in sys/stat.h rather than
sys/socket.h.
#include <sys/socket.h> int listen (int s, int backlog);
To create a passive/listening (server) socket, a socket is created with
socket() (see socket), bound to a local address with bind()
(see bind) and then given a connection queue with listen().
Connections can then be accepted with accept() (see accept).
listen() sets the maximum number of connections, backlog, that
can be waiting for handling by accept(). Any further waiting
connections will be refused.
listen() is only a valid operation for sockets of type
SOCK_STREAM or SOCK_SEQPACKET.
On successful completion the function returns 0. Otherwise, a value of -1 is returned and errno is set appropriately.
EBADF
ENOTSOCK
EOPNOTSUPP
listen() is not a valid operation on this type of socket.
POSIX, Unix98
#include <lsck/copyrite.h> char *__lsck_get_copyright (void);
This function returns a string containing the copyright information for libsocket. If this is longer than one line, it will be formatted to fit on an 80-column terminal.
A pointer to the string is returned on success; on failure, NULL is
returned.
not ANSI, not POSIX, not Unix98
This function is specific to libsocket.
char *p = __lsck_get_copyright(); puts(p);
#include <lsck/copyrite.h> char *__lsck_get_version (void);
This function returns a string containing the version information for libsocket. If this is longer than one line, it will be formatted to fit on an 80-column terminal.
The version message is constructed from constants defined in
lsck/copyrite.h. The ones that should be used in user programs are
listed in the table below. As an example, consider the version number 0.8.0.
LSCK_VERSION_MAJOR
0 for the example.
LSCK_VERSION_MINOR
8 for the example.
LSCK_VERSION_SUBMINOR
0 for
the example.
A pointer to the string is returned on success; on failure, NULL is
returned.
not ANSI, not POSIX, not Unix98
This function is specific to libsocket.
char *p = __lsck_get_version(); puts(p);
#include <sys/socket.h>
#include <unistd.h>
int rcmd (char **ahost, int inport,
const char *locuser, const char *remuser,
const char *cmd, int *fd2p);
The rcmd() function is used by the super-user to execute a command on
a remote machine using an authentication scheme based on reserved port numbers.
The rcmd() function looks up the host *ahost using
gethostbyname() (see gethostbyname), returning -1 if the host
does not exist. Otherwise *ahost is set to the standard name of the host
and a connection is established to a server residing at the well-known
Internet port inport.
If the connection succeeds, a socket in the Internet domain of type
SOCK_STREAM is returned to the caller, and given to the remote command
as stdin and stdout.
If fd2p is non-zero, then an auxiliary channel to a control process will be set up, and a descriptor for it will be placed in *fd2p. The control process will return diagnostic output from the command (unit 2) on this channel, and will also accept bytes on this channel as being UNIX signal numbers, to be forwarded to the process group of the command.
If fd2p is 0, then the stderr (unit 2 of the remote command) will be made the same as the stdout and no provision is made for sending arbitrary signals to the remote process, although you may be able to get its attention by using out-of-band data.
The protocol is described in detail in the rshd documentation.
The rcmd() function returns a valid socket descriptor on success.
It returns -1 on error and prints a diagnostic message on the standard error.
libsocket declares this function in sys/socket.h, but it's usually
defined in unistd.h.
#include <sys/uio.h> ssize_t readv (int fd, const struct iovec *iov, int iovcnt);
readv() performs a scatter-gather read from the specified file
descriptor fd. The data is written into a group of buffers described
by the array iov with iovcnt entries in a similar way to
read() (see read).
struct iovec is described in the section on writev()
(see writev).
On successful completion the function returns the number of bytes read. Otherwise, a value of -1 is returned and errno is set appropriately.
EINVAL
ssize_t.
IOV_MAX.
POSIX, Unix98
#include <sys/types.h> #include <sys/socket.h> ssize_t recv (int s, void * buf, size_t len, int flags);
The recv() function is used on a connected socket and is identical
to recvfrom() (see recvfrom) with NULL from and
fromlen parameters.
On success the number of octets received is return, or -1 and errno is set. See recvfrom.
POSIX, Unix98
#include <sys/types.h>
#include <sys/socket.h>
ssize_t recvfrom (int s, void * buf, size_t len, unsigned int flags,
struct sockaddr *from, size_t *fromlen);
recvfrom() is used to receive messages from a socket.
If from is non-NULL, the source address of the message is stored in it.
fromlen is a value-result parameter, it indicates the size of from
on entry and the size of from stored. If fromlen was too small,
it is truncated to the initial size. flags may have the value zero or
be the bitwise OR of any combination of one or more of the values:
MSG_OOB
select() (see select) indicates
an exception condition.
MSG_PEEK
MSG_WAITALL
On success the number of octets received is return, or -1 and errno is set:
EWOULDBLOCK.
EBADF
ENOTCONN
ENOTSOCK
EINTR
EFAULT
POSIX, Unix98
#include <netinet/in.h> #include <arpa/nameser.h> #include <resolv.h> extern struct state _res; int res_init (void);
The res_init() function reads the configuration files
(see host.conf, see resolv.conf) to get the default domain name,
search order and name server address(es). If no server is given, the local
host is tried. If no domain is given, that associated with the local host is
used. It can be overridden with the environment variable LOCALDOMAIN.
res_init() is normally executed by the first call to one of the
other resolver functions, e.g. res_query(), gethostbyname()
(see res_query, see gethostbyname).
The res_init() function returns 0 on success, or -1 if an error
occurs.
This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux.
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_mkquery (int op, const char *dname, int class, int type,
char *data, int datalen, struct rrec *newrr,
char *buf, int buflen);
This function is a low-level routine used by res_query.
The res_mkquery() function constructs a query message in buf
of length buflen for the domain name dname. The query type
op is usually QUERY, but can be any of the types defined in
<arpa/nameser.h>. newrr is currently unused.
The resolver routines use global configuration and state information
contained in the structure _res, which is described with
res_query() (see res_query).
The res_mkquery() function returns the length of the response,
or -1 if an error occurs.
This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux.
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_query (const char *dname, int class, int type,
unsigned char *answer, int anslen);
The res_query() function queries the name server for the
fully-qualified domain name name of specified type and
class. The reply is left in the buffer answer of length
anslen supplied by the caller.
The resolver routines use global configuration and state information
contained in the structure _res, which is defined in
<resolv.h>. The only field that is normally manipulated by the
user is _res.options. This field can contain the bitwise OR
of the following options:
RES_INIT
res_init() has been called.
RES_DEBUG
RES_AAONLY
res_send() continues until
it fins an authoritative answer or returns an error. [Not currently
implemented].
RES_USEVC
RES_PRIMARY
RES_IGNTC
RES_RECURSE
res_send(). [Enabled by
default].
RES_DEFNAMES
res_search() will append the default domain name to
single component names, ie. those that do not contain a dot.
[Enabled by default].
RES_STAYOPEN
RES_DNSRCH
res_search() will search for host names in the current
domain and in parent domains. This option is used by gethostbyname()
(see gethostbyname). [Enabled by default].
res_query() returns the length of the response, or -1 if an error
occurs.
This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux.
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_querydomain (const char *name, const char *domain,
int class, int type,
unsigned char *answer, int anslen);
The res_querydomain() function makes a query using res_query()
(see res_query) on the concatenation of name and domain.
The resolver routines use global configuration and state information
contained in the structure _res, which is described in
res_query() (see res_query).
The res_querydomain() function returns the length of the response,
or -1 if an error occurs.
This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux.
#include <netinet/in.h>
#include <arpa/nameser.h>
#include <resolv.h>
extern struct state _res;
int res_search(const char *dname, int class, int type,
unsigned char *answer, int anslen);
The res_search() function makes a query and waits for the response
like res_query() (see res_query, but in addition implements the
default and search rules controlled by RES_DEFNAMES and
RES_DNSRCH (see description of _res with res_query()
(see res_query)).
The res_search() function returns the length of the response,
or -1 if an error occurs.
This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux.
#include <netinet/in.h> #include <arpa/nameser.h> #include <resolv.h> extern struct state _res; int res_send (const char *msg, int msglen, char *answer, int anslen);
This function is a low-level routine used by res_query()
(see res_query).
The res_send() function sends a pre-formatted query given in
msg of length msglen and returns the answer in answer
which is of length anslen. It will call res_init()
(see res_init), if it has not already been called.
The resolver routines use global configuration and state information
contained in the structure _res, which is described with
res_query() (see res_query).
The res_send() function returns the length of the response,
or -1 if an error occurs.
This function is not portable. It is taken from Linux's libc 5 and so may be portable to Linux.
#include <netdb.h>
int rexec (char **ahost, int rport, const char *name, const char *pass,
const char *cmd, int *fd2p);
Under construction - if you have a good description, please inform the libsocket maintainer.
#include <sys/socket.h> #include <unistd.h> int rresvport (int *port);
The rresvport() function is used to obtain a socket with a privileged
address bound to it. This socket is suitable for use by
rcmd() (see rcmd) and several other functions. Privileged Internet
ports are those in the range 0 to 1023. Only the super-user is allowed to
bind an address of this sort to a socket.
The rresvport() function returns a valid, bound socket descriptor on
success. It returns -1 on error with errno set according to the reason
for failure. The error code EAGAIN is overloaded to mean
"All network ports in use".
libsocket declares this function in sys/socket.h, but it's usually
defined in unistd.h.
#include <sys/socket.h>
#include <unistd.h>
int ruserok (const char *rhost, int superuser,
const char *ruser, const char *luser);
The ruserok() function is used by servers to authenticate clients
requesting service with rcmd() (see rcmd).
The ruserok() function takes a remote host's name, two user names
and a flag indicating whether the local user's name is that of the
super-user. Then, if the user is *NOT* the super-user, it checks the
/etc/hosts.equiv file. If that lookup is not done, or is unsuccessful,
the .rhosts in the local user's home directory is checked to see if
the request for service is allowed.
If this file does not exist, is not a regular file, is owned by anyone other than the user or the super-user, or is writeable by anyone other than the owner, the check automatically fails.
If the local domain (as obtained from gethostname()
(see gethostname) is the same as the remote domain, only the machine name
need be specified.
Zero is returned if the machine name is listed in the hosts.equiv
file, or the host and remote user name are found in the .rhosts
file; otherwise -1 is returned.
libsocket declares this function in sys/socket.h, whereas it's usually
defined in unistd.h.
#include <sys/types.h> #include <sys/socket.h> int send (int s, const void * msg, size_t len, int flags);
The send() function is used to transmit data to a peer via socket,
send() is equivalent to sendto() (see sendto) call with a
NULL to parameter to and tolen.
The function return the number of octets accepted for transmission, Otherwise -1 with errno set. See See sendto.
POSIX, Unix98
#include <sys/types.h>
#include <sys/socket.h>
ssize_t sendto (int s, const void * msg, size_t len,
int flags, const struct sockaddr *to, size_t tolen);
The function sendto() is used to transmit a message to another socket.
The address of the target is given by to with tolen specifying
its size. A NULL value fo to indicats that no socket-address is
specifiend and the socket is in the CONNECTED state, the corresponding
tolen is then ignored. The length of the message is given by len.
If the message is too long to pass atomically through the underlying protocol,
the error EMSGSIZE is returned, and the message is not transmitted.
If no messages space is available at the socket to hold the message to be
transmitted, then sendto normally blocks, unless the socket has been
placed in non-blocking I/O mode. The select()
(see select)
call may be used to determine when it is possible to send more data.
The flags parameter may include one or more of the following:
MSG_OOB
out-of-band data on sockets that support this notion.
MSG_DONTROUTE
MSG_EOR
The call returns the number of characters sent, or -1 and errno set, if an error occurred.
EBADF
ENOTSOCK
s is not a socket.
EFAULT
EMSGSIZE
EWOULDBLOCK
EPIPE
ENOBUFS
POSIX, Unix98
#include <lsck/domname.h> int setdomainname (const char *name, size_t len);
This function is used to change the domain name. The domain name can be
accessed using getdomainname() (see getdomainname).
On success, zero is returned. On error, -1 is returned, and errno is set appropriately.
EPERM
EINVAL
not POSIX, not Unix98
This function is defined in unistd.h on Linux.
#include <netdb.h> extern int h_errno; void sethostent (int stayopen);
The sethostent() function specifies, if stayopen is true (1),
that a connected TCP socket should be used for the name server queries and
that the connection should remain open during successive queries. Otherwise,
name server queries will use UDP datagrams.
None
Unix98
#include <unistd.h> #include <lsck/hostname.h> int sethostname (const char *name, size_t len);
This function is used to change the host name of the current processor. The
host name is retrieved using gethostname() (see gethostname). The
domain name component can be retrieved and set using getdomainname()
and setdomainname() respectively (see getdomainname,
see setdomainname).
On success, zero is returned. On error, -1 is returned, and
errno is set appropriately.
EINVAL
EPERM
EFAULT
not POSIX, not Unix98
lsck/hostname.h is particular to libsocket. On Linux it is defined
in unistd.h.
#include <netdb.h> void setnetent (int stayopen);
The setnetent() function opens and rewinds the
networks file (see networks). If stayopen is true
(1), then the file will not be closed between calls to
getnetbyname() or getnetbyaddr()
(see getnetbyname, see getnetbyaddr).
None
Unix98
#include <netdb.h> void setprotoent (int stayopen);
The setprotoent() function opens and rewinds the
protocols file (see protocols). If stayopen is true
(1), then the file will not be closed between calls to
getprotobyname() or getprotobynumber()
(see getprotobyname, see getprotobynumber).
None
Unix98
#include <netdb.h> void setservent (int stayopen);
The setservent() function opens and rewinds the
services file (see services). If stayopen is true
(1), then the file will not be closed between calls to
getservbyname() or getservbyport()
(see getservbyname, see getservbyport).
None
Unix98
#include <sys/types.h>
#include <sys/socket.h>
int setsockopt (int s, int level, int optname,
const void *optval, int optlen);
setsockopt() manipulates the options associated with a socket.
Options may exist at multiple protocol levels; they are always present at the
uppermost socket level.
When manipulating socket options the level at which the option resides and the
name of the option must be specified. To manipulate options at the socket
level, level is specified as SOL_SOCKET. To manipulate options at
any other level the protocol number of the appropriate protocol controlling
the option is supplied. For example, to indicate that an option is to be
interpreted by the TCP protocol, level should be set to the protocol
number of TCP (see getprotoent).
The parameters optval and optlen are used to access option values
for setsockopt().
optname and any specified options are passed uninterpreted to the
appropriate protocol module for interpretation. The include file
<sys/socket.h> contains definitions for socket level options, described
below. Options at other protocol levels vary in format and name.
Most socket-level options utilize an int parameter for optval.
The parameter should be non-zero to enable a boolean option, or zero if the
option is to be disabled.
SO_LINGER uses a struct linger parameter, defined in
<sys/socket.h>, which specifies the desired state of the option and
the linger interval (see below).
SO_SNDTIMEO and SO_RCVTIMEO use a struct timeval
parameter, defined in <sys/time.h>.
The following options are recognized at the socket level.
SO_DEBUG
SO_REUSEADDR
SO_KEEPALIVE
SO_DONTROUTE
SO_LINGER
SO_BROADCAST
SO_OOBINLINE
SO_SNDBUF
SO_RCVBUF
SO_SNDLOWAT
SO_RCVLOWAT
SO_DEBUG enables debugging in the underlying protocol modules.
SO_REUSEADDR indicates that the rules used in validating addresses
supplied in bind() (see bind) call should allow reuse of local
addresses.
SO_KEEPALIVE enables the periodic transmission of messages on a
connected socket. Should the connected party fail to respond to these
messages, the connection is considered broken and processes using the socket
are notified via a SIGPIPE signal when attempting to send data.
SO_DONTROUTE indicates that outgoing messages should bypass the standard
routing facilities. Instead, messages are directed to the appropriate network
interface according to the network portion of the destination address.
SO_LINGER controls the action taken when unsent messages are queued on
socket and a close() is performed (see close).
If the socket promises reliable delivery of data and SO_LINGER is set,
the system will block the process on the close() attempt until it is
able to transmit the data or until it decides it is unable to deliver the
information (a timeout period, termed the linger interval, is specified in the
setsockopt() call when SO_LINGER is requested).
If SO_LINGER is disabled and a close() is issued, the system will
process the close in a manner that allows the process to continue as quickly
as possible.
The linger structure is defined in <sys/socket.h> as follows:
struct linger {
int l_onoff; /* Linger active */
int l_linger; /* How long to linger for */
};
l_onoff indicates whether to linger or not. If it is set to 1 then
l_linger contains the time in hundredths of seconds how long the
process should linger to complete the close(). If l_onoff
is set to zero the process returns immediately.
The option SO_BROADCAST requests permission to send broadcast datagrams
on the socket. Broadcast was a privileged operation in earlier versions of the
system.
With protocols that support out-of-band data, the SO_OOBINLINE
option requests that out-of-band data be placed in the normal data input
queue as received; it will then be accessible with recv or
read calls without the MSG_OOB flag. Some protocols always
behave as if this option is set.
SO_SNDBUF and SO_RCVBUF are options to adjust the normal buffer
sizes allocated for output and input buffers, respectively. The buffer size
may be increased for high-volume connections, or may be decreased to limit the
possible backlog of incoming data. The system places an absolute limit on
these values.
SO_SNDLOWAT is an option to set the minimum count for output
operations. Most output operations process all of the data supplied by the
call, delivering data to the protocol for transmission and blocking as
necessary for flow control. Nonblocking output operations will process as
much data as permitted subject to flow control without blocking, but will
process no data if flow control does not allow the smaller of the low water
mark value or the entire request to be processed. A select()
(see select) operation testing the ability to write to a
socket will return true only if the low water mark amount could be processed.
The default value for SO_SNDLOWAT is set to a convenient size for
network efficiency, often 1024.
SO_RCVLOWAT is an option to set the minimum count for input operations.
In general, receive calls will block until any (non-zero) amount of data is
received, then return with smaller of the amount available or the amount
requested. The default value for SO_RCVLOWAT is 1. If
SO_RCVLOWAT is set to a larger value, blocking receive calls normally
wait until they have received the smaller of the low water mark value or the
requested amount. Receive calls may still return less than the low water mark
if an error occurs, a signal is caught, or the type of data next in the
receive queue is different than that returned.
On success, zero is returned. On error, -1 is returned, and errno is set appropriately.
Possible errors from this function are:
EBADF
ENOTSOCK
ENOPROTOOPT
EFAULT
Unix98
#include <sys/socket.h> int shutdown (int s, int how);
shutdown() stops communication in one or both directions of a
full-duplex connection on socket s. how is one of the following:
SHUT_RD
SHUT_WR
SHUT_RDWR
These correspond to the values 0, 1 and 2 respectively.
If sends are disabled for a stream socket (SOCK_STREAM), any further
writes on the socket will return EPIPE and raise the signal
SIGPIPE (see sendto).
On successful completion the function returns 0. Otherwise, a value of -1 is returned and errno is set appropriately.
EBADF
ENOTSOCK
ENOTCONN
POSIX, Unix98
#include <sys/socket.h> int sockatmark (int s);
The sockatmark() function determines whether the socket descriptor
s is at the out-of-band data mark. If the libsocket interface supports
it, sockatmark() will return 1 when all data preceding the mark have
been read and the out-of-band data mark is the first element in the receive
queue. sockatmark() does not remove the mark from the stream.
On successful initialization the function returns 1, if the protocol has marked the data stream and all data preceeding the mark have been read. It returns 0, if there is no mark, or if data preceeds the mark in the receive queue. Otherwise, -1 is return and errno is set:
EBADF
ENOSYS
sockatmark() operation.
not ANSI, POSIX
#include <sys/socket.h> int socket (int domain, int type, int protocol);
socket() creates a communication end-point and returns its file
descriptor.
domain refers to a communication domain, e.g. Internet domain, Unix
domain. These are specified by the AF_* constants, e.g. AF_INET,
AF_UNIX, as defined in sys/socket.h.
type specifies how the communication takes place, e.g. streams,
datagrams. These are specified by the SOCK_ constants, e.g.
SOCK_STREAM, SOCK_DGRAM, as defined in sys/socket.h.
SOCK_STREAM supports reliable, sequenced, bidirectional streams of
binary data. SOCK_DGRAM supports unreliable connectionless packets.
These packets may have a maximum size.
protocol specifies the communications protocol to use, e.g. TCP, UDP.
For the Internet domain (i.e. IP), these are defined by the IPPROTO_
constants in netinet/in.h, e.g. IPPROTO_TCP, IPPROTO_UDP.
If protocol is zero, the default protocol for the socket's domain &
type is used, e.g.
fd = socket(AF_INET, SOCK_STREAM, 0); would create a TCP/IP socket.
fd = socket(AF_INET, SOCK_DGRAM, 0); would create a UDP/IP socket.
libsocket supports the following triplets:
-1 is returned and errno set on error. Otherwise, a positive non-zero integer number is returned, a file descriptor.
Possible errors are:
EMFILE
ENFILE
ENODEV
ENOAFSUPPORT
EPROTONOSUPPORT
POSIX, Unix98
#include <sys/socket.h> int socketpair (int domain, int type, int protocol, int sv[2]);
socketpair() creates a pair of unbound connected sockets. The sockets
are identical. sv contains two file descriptors, one for each socket.
domain, type and protocol are described in the section
on socket() (see socket). Using a protocol of 0 will give a
default protocol.
0 is returned on success. Otherwise -1 is returned and the error code is stored in errno.
Possible errors for this function are:
EOPNOTSUPP
EAFNOTSUPP
ENOPROTOSUPPORT
POSIX, Unix98
#include <sys/uio.h> ssize_t writev (int fd, const struct iovec *iov, int iovcnt);
writev() performs a scatter-gather write to the specified file
descriptor fd. A group of buffers described by the array iov,
with iovcnt entries, is written to fd in a similar
way to write() (see write).
struct iovec is defined as follows:
struct iovec {
void *iov_base; /* Base address of a memory region for I/O */
size_t iov_len; /* Size of memory region */
};
On successful completion the function returns the number of bytes written. Otherwise, a value of -1 is returned and errno is set appropriately.
EINVAL
ssize_t.
IOV_MAX.
POSIX, Unix98
Installing the binary distribution (ready-to-run) version of libsocket is
fairly straightforward. Firstly, back up the DJGPP header file
include/netinet/in.h, because this is overwritten by one of libsocket's
header files. Then extract the ZIP file into the DJGPP directory
(e.g. c:\djgpp), preserving directory names - e.g. use PKUNZIP's
-d option. The distribution documentation files (e.g. readme files)
can then be found off the c:\djgpp\contrib directory.
To install the info files properly, you will need GNU texinfo 4.02. Run the following commands:
install-info --info-file=c:/djgpp/info/lsck.inf --info-dir=c:/djgpp/info install-info --info-file=c:/djgpp/info/netsetup.inf --info-dir=c:/djgpp/info
Now install the Winsock 2 support virtual device driver (see the section below). libsocket should now be installed correctly and ready to use (see Getting Started).
libsocket's binary distribution is built with debugging information, because it is still in development. Programs built with libsocket may be larger than expected, because of the debugging information. Debugging information can be removed using strip (see strip).
Installing the documentation distribution (ready-to-run) version of libsocket
is fairly straightforward. Extract the ZIP file into the DJGPP directory
(e.g. c:\djgpp), preserving directory names - e.g. use PKUNZIP's
-d option. The distribution documentation files (e.g. readme files)
can then be found off the c:\djgpp\contrib directory.
Extract the ZIP into the DJGPP directory (e.g. c:\djgpp), preserving
directory names - e.g. use PKUNZIP's -d option. The sources can
then be found off the c:\djgpp\contrib directory.
To build libsocket requires the following packages: