The BSD UNIX Socket Library

Header Files

The SAS/C Socket Library provides header files to enable you to program with socket functions. A list of the header files, accompanied by a brief description of each one and an explanation of its structures, follows. Refer to Header Filenames for a discussion of header file naming conventions.

The header files in this section are listed in the following order:

<sys/types.h>
<sys/uio.h>
<errno.h>
<sys/ioctl.h>
<fcntl.h>
<sys/socket.h>
<netdb.h>
<netinet/in_systm.h>
<netinet/ip_icmp.h>
<netinet/udp.h>
<netinet/ip.h>
<netinet/in.h>
<arpa/inet.h>
<arpa/nameser.h>
<resolv.h>
<net/if.h>
<strings.h>

In many cases the contents of one header file depend on the prior inclusion of another header file. The description for each header file lists any other header files on which the header file may depend. Failure to adhere to these ordering dependencies usually results in compilation errors. The order that the header files follow in this chapter reflects the dependencies between header files.

Note: Sockets are not defined by the POSIX.1 and POSIX.1a standards. Therefore, if your program uses sockets, you should not define the symbol _POSIX_SOURCE , as this will exclude socket-related types from standard POSIX header files such as <sys/types.h> . [cautionend]

<sys/types.h>

This header file contains definitions to allow for the porting of BSD programs.

<sys/types.h> must usually be included before other socket-related header files; refer to the individual header file descriptions that follow for the specific dependency.

This header file declares the following typedef names for use as abbreviations for three commonly used types:

typedef unsigned u_char;
u_char;

typedef unsigned u_short;
u_short;

typedef unsigned u_long;
u_long; .

The following typedef name is commonly used for buffer pointers:

typedef char * caddr_t;

This header file also defines the FD_SET , FD_ZERO , FD_CLR , FD_ISSET , and FD_SETSIZE macros used by select to manipulate socket descriptors. Refer to Socket Function Reference for a description of these macros.

timeval

This structure is used by the select call to set the amount of time for a user process to wait.

struct timeval {
   long tv_sec;     /* seconds      */
   long tv_usec;    /* microseconds */
};

For more information on the inclusion of this structure in the <sys/types.h> header file, refer to Porting UNIX Socket Applications to the SAS/C Environment.

<sys/uio.h>

The structure in the <sys/uio.h> header file is described in the following section. <sys/types.h> must be included before this header file.

iovec

This structure is used by the readv , writev , sendmsg , and recvmsg calls. An array of iovec structures describes the pieces of a noncontiguous buffer.

struct iovec {
   void * iov_base;
   int    iov_len;
};

<errno.h>

This header file contains definitions for the macro identifiers that name system error status conditions. When a SAS/C Library function sets an error status by assigning a nonzero value to errno , the calling program can check for a particular value by using the name defined in <errno.h> . The following table lists all the errno values normally associated with the socket library functions:

Errno Value perror message Explanation

EACCES permission denied The program does not have access to this socket.

EADDRINUSE socket address is already being used The given address is already in use.

EADDRNOTAVAIL socket address not usable The given address is not available on the local host.

EAFNOSUPPORT unsupported socket addressing family The addressing family is not supported or is not consistent with socket type. The SAS/C Library supports only AF_INET (and AF_UNIX if integrated sockets are used).

EALREADY previous connecton not yet completed The socket is marked for non-blocking I/o, and and earlier connect call has not yet completed.

EBADF file or socket not open or unsuitable The descriptor value passed does not correspond to an open socket or file.

ECONNABORTED connection aborted by local network software The local communications software aborted the connection.

ECONNREFUSED destination host refused socket connection The destination host refused the socket connection.

ECONNRESET connection reset by peer The peer process has reset the connection.

EDESTADDRREQ socket operation requires destination address Supply a destination address for this socket.

EHOSTDOWN destination host is down The destination host is down.

EHOSTUNREACH destination host is unreachable The destination host is unreachable.

EINPROGRESS socket connection in progress The connection has begun, but control is returned so that the call will not block. The connection is complete when the select call indicates that the socket is ready for writing. This is not an error.

EISCONN socket is already connected The program called connect on a connected socket.

EMSGSIZE message too large for datagram socket A datagram socket could not accommodate a message as large as this one.

ENETDOWN local host's network down or inaccessible The program cannot talk to the networking software on this local machine, or the host's network is down.

ENETRESET remote host dropped network communications The remote host is not communicating over the network at this time.

ENETUNREACH destination network is unreachable This host cannot find a route to the destination network.

ENOBUFS insufficient buffers in network software The operating system did not have enough memory to perform the requested operation.

ENOPROTOOPT option not supported for protocol type The socket option or option level is invalid.

ENOTCONN socket is not connected The socket is not connected.

ENOTSOCK file descriptor not associated with a socket The given file descriptor is either assigned to a file or is completely unassigned.

EOPNOTSUPP operation not supported on socket The call does not support this type of socket.

EPFNOSUPPORT unsupported socket protocol family The given protocol family is unknown or unsupported by the TCP/IP network software.

EPIPE broken pipe or socket connection The peer process closed the socket before your process was finished with it.

EPROTONOSUPPORT unsupported socket protocol The given protocol is unknown or is not supported by the TCP/IP network software

EPROTOTYPE protocol inconsistent with socket type When calling the socket, the protocol was not 0 and not consistent with the socket type.

ESHUTDOWN connection has been shut down The connection has been shut down.

ESOCKTNOSUPPORT socket type not allowed The program specified a socket type that is not supported by the TCP/IP network software.

ESYS operating system interface failure The underlying operating system software or the TCP/IP software returned an abnormal failure condition. Contact TCP/IP vendor.

ETIMEDOUT socket connection attempt timed out The destination host did not respond to a connection request.

EWOULDBLOCK socket operation would block The socket is marked for non-blocking I/O, and the call would have been blocked. This is not an error.

Errno Value	perror message	Explanation
`EACCES`	permission denied	The program does not have access to this socket.
`EADDRINUSE`	socket address is already being used	The given address is already in use.
`EADDRNOTAVAIL`	socket address not usable	The given address is not available on the local host.
`EAFNOSUPPORT`	unsupported socket addressing family	The addressing family is not supported or is not consistent with socket type. The SAS/C Library supports only `AF_INET` (and `AF_UNIX` if integrated sockets are used).
`EALREADY`	previous connecton not yet completed	The socket is marked for non-blocking I/o, and and earlier `connect` call has not yet completed.
`EBADF`	file or socket not open or unsuitable	The descriptor value passed does not correspond to an open socket or file.
`ECONNABORTED`	connection aborted by local network software	The local communications software aborted the connection.
`ECONNREFUSED`	destination host refused socket connection	The destination host refused the socket connection.
`ECONNRESET`	connection reset by peer	The peer process has reset the connection.
`EDESTADDRREQ`	socket operation requires destination address	Supply a destination address for this socket.
`EHOSTDOWN`	destination host is down	The destination host is down.
`EHOSTUNREACH`	destination host is unreachable	The destination host is unreachable.
`EINPROGRESS`	socket connection in progress	The connection has begun, but control is returned so that the call will not block. The connection is complete when the `select` call indicates that the socket is ready for writing. This is not an error.
`EISCONN`	socket is already connected	The program called `connect` on a connected socket.
`EMSGSIZE`	message too large for datagram socket	A datagram socket could not accommodate a message as large as this one.
`ENETDOWN`	local host's network down or inaccessible	The program cannot talk to the networking software on this local machine, or the host's network is down.
`ENETRESET`	remote host dropped network communications	The remote host is not communicating over the network at this time.
`ENETUNREACH`	destination network is unreachable	This host cannot find a route to the destination network.
`ENOBUFS`	insufficient buffers in network software	The operating system did not have enough memory to perform the requested operation.
`ENOPROTOOPT`	option not supported for protocol type	The socket option or option level is invalid.
`ENOTCONN`	socket is not connected	The socket is not connected.
`ENOTSOCK`	file descriptor not associated with a socket	The given file descriptor is either assigned to a file or is completely unassigned.
`EOPNOTSUPP`	operation not supported on socket	The call does not support this type of socket.
`EPFNOSUPPORT`	unsupported socket protocol family	The given protocol family is unknown or unsupported by the TCP/IP network software.
`EPIPE`	broken pipe or socket connection	The peer process closed the socket before your process was finished with it.
`EPROTONOSUPPORT`	unsupported socket protocol	The given protocol is unknown or is not supported by the TCP/IP network software
`EPROTOTYPE`	protocol inconsistent with socket type	When calling the socket, the protocol was not `0` and not consistent with the socket type.
`ESHUTDOWN`	connection has been shut down	The connection has been shut down.
`ESOCKTNOSUPPORT`	socket type not allowed	The program specified a socket type that is not supported by the TCP/IP network software.
`ESYS`	operating system interface failure	The underlying operating system software or the TCP/IP software returned an abnormal failure condition. Contact TCP/IP vendor.
`ETIMEDOUT`	socket connection attempt timed out	The destination host did not respond to a connection request.
`EWOULDBLOCK`	socket operation would block	The socket is marked for non-blocking I/O, and the call would have been blocked. This is not an error.

Note: Socket library functions may occasionally set errno values not shown in the above table. In particular, when integrated sockets are used, UNIX System Services (USS) defined errno values may be stored to indicate conditions specific to the USS implementation. Common SAS/C errno values are listed in Chapter 1, "Introduction to the SAS/C Library," in SAS/C Library Reference, Volume 1. Also refer to POSIX and USS Error Numbers for USS related errno values. For a complete listing of all errno values, see the SAS/C Compiler and Library Quick Reference Guide. [cautionend]

<sys/ioctl.h>

This header file contains definitions for the symbols required by the ioctl function, as well as the declaration for ioctl .

<fcntl.h>

This header file contains definitions for the constants associated with the fcntl function, as well as declarations for UNIX style I/O functions. Failure to include the <sys/uio.h> header file before this header file may result in a warning message if readv or writev is called.

<sys/socket.h>

This header file contains macro definitions related to the creation of sockets, for example, the type of socket (stream, datagram, or raw), the options supported, and the address family. ( AF_UNIX is supported if integrated sockets are used.) The SAS/C Compiler only supports the TCP/IP and the AF_INET Internet address family. The <sys/socket.h> header file contains declarations for most of the functions that operate on sockets. You must include the <sys/types.h> header file before this header file. The structures in the <sys/socket.h> header file are described in the following sections.

linger

This structure is used for manipulating the amount of time that a socket waits for the transmission of unsent messages after the initiation of the close call.

struct linger {
   int     l_onoff;          /* option on/off                      */
   int     l_linger;         /* linger time, in seconds            */
};

sockaddr

This is a generic socket address structure. Because different underlying transport mechanisms address peer processes in different ways, the socket address format may vary.

struct sockaddr {
   u_short sa_family;        /* address family                     */
   char    sa_data[14] ;     /* up to 14 bytes of direct address   */
};

msghdr

This structure contains the message header for the recvmsg and sendmsg calls.

struct msghdr {
   caddr_t msg_name;               /* optional address             */
   int     msg_namelen;            /* size of address              */
   struct  iovec *msg_iov;         /* scatter/gather array         */
   int     msg_iovlen;             /* # elements in msg_iov        */
   caddr_t msg_accrights;          /* ignored for AF_INET          */
   int     msg_accrightslen;       /* ignored for AF_INET          */
};

clientid

This structure is used by the getclientid , givesocket , and takesocket routines. These routines allow OS/390 or CMS programs to pass socket descriptors. The routines compensate for the unavailablity of fork (except via USS) as a means of creating an independent process that shares file descriptors with its parent.

struct clientid {
   int domain;          /* Such as AF_INET.                        */
   char name[8];        /* Address space or virtual machine name.  */
   char subtaskname[8]; /* Can be set to blank or a subask ID.     */
   char reserved20[20]; /* Do not use the contents of this         */
                        /* structure.                              */
};

clientpid

This structure is used by the getclientpid, givesocket_pid, and takesocket_pid routines. These routines allow OS/390 programs to pass integrated socket descriptors to independent child processes.

struct clientpid {
   int domain;               /* addressing domain AF-INET */
   char reserve4[4];         /* unused - set to binary zeroes */
   pid_t pid;                /* client process ID number */
   char task[8];             /* unused - set to blanks (0x40) */
   unsigned char flag;       /* options flag */
   char reserve3[3];         /* unused - set to binary zeroes */
   int sid;                  /* socket identifier */
   char reserve12[12];       /* unused - set to binary zeroes */
};

<netdb.h>

This header file contains structures returned by the network database library. Internet addresses and port numbers are stored in network byte order, identical to IBM 370 byte order. Other quantities, including network numbers, are stored in host byte order. Despite the fact that network byte order and host byte order are identical on the IBM System/370, a portable program must distinguish between the two. The structures in the <netdb.h> header file are described in the following sections.

hostent

This structure contains host information.

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 from name server   */
 #define h_addr h_addr_list[0]  /* address, for backward           */
                                /* compatiblity                    */
};

netent

This structure contains network information.

struct  netent {
   char            *n_name;        /* official name of network     */
   char            **n_aliases;    /* alias list                   */
   int             n_addrtype;     /* net address type             */
                                   /* Only AF_INET is supported.   */
   unsigned long   n_net;          /* network number               */
};

servent

This structure contains service information.

struct  servent {
   char    *s_name;        /* official service name                */
   char    **s_aliases;    /* alias list                           */
   int     s_port;         /* port #                               */
   char    *s_proto;       /* protocol to use                      */
};

protoent

This structure contains protocol information.

struct  protoent {
   char    *p_name;        /* official protocol name               */
   char    **p_aliases;    /* alias list                           */
   int     p_proto;        /* protocol #                           */
};

rpcent

<netdb.h> also defines a structure used to store information about programs using the Sun RPC protocol. This structure is defined as follows:

struct rpcent {
   char    *r_name;        /* name of server for RPC program       */
   char    **r_aliases;    /* alias list                           */
   int     r_number;       /* RPC program number                   */
};

Sun RPC programs can be identified by name or by number. The getrpcbyname function returns rpcent structure.

herror

The <netdb.h> header file also contains macro definitions for the integer h_errno , which describes name server conditions. Refer to Socket Function Reference for more information on h_errno .

<netinet/in.h>

This header file contains constants and structures defined by the Internet system. Several macros are defined for manipulating Internet addresses. Among these are INADDR_ANY , which indicates that no specific local address is required, and INADDR_NONE , which generally indicates an error in address manipulation functions. Refer to bind for more information on binding a local address to the socket.

You must include the <sys/types.h> header file before this header file. The structures in the <netinet/in.h> header file are described in the following sections.

in_addr

This structure contains the Internet address in network byte order, which is the same as host byte order on the IBM System/370.

struct in_addr {
   u_long s_addr;
};

sockaddr_in

This structure contains the socket address, which includes the host's Internet address and a port number. This is the specific address structure used for a socket address when the transport mechanism is TCP/IP.

struct sockaddr_in {
   short   sin_family;
   u_short sin_port;
   struct  in_addr sin_addr;
   char    sin_zero[8];
};

<netinet/in_systm.h>

This header file contains definitions to facilitate the porting of low-level network control and query Internetwork Control and Message Protocol (ICMP), and Internetwork Protocol (IP) raw socket type applications. The Internet ping client utility is an example of such a program.

<netinet/in_systm.h> must usually be included before other ICMP or IP socket related header files such as <netinet/ip.h> and <netinet/ip_icmp.h> . Refer to the individual header file descriptions that follow for the specific dependency.

This header declares the following typedef names for use as abbreviations for three commonly used types for internetwork order, that is types with the bytes in high endian order.

typedef u_short n_short;: declares unsigned short integer as received from the network.
typedef u_long n_long;: declares an unsigned long integer as received from the network.
typedef u_long n_time;: declares an unsigned long integer representing minutes and seconds since 00:00 Greenwich mean time, in byte reverse order.

The following definition is also available to kernel functions that provide a network time definition for the iptime function.

#ifdef _KERNEL
n_time iptime();
#endif

<netinet/ip_icmp.h>

This header file contains definitions of constants and structures required for using the ICMP protocol as described in IBM's RFC 792. Prior inclusion of <netinet/in_systm.h> is required.

<netinet/ip.h>

This header file contains definitions of constants and structures required for using the IP protocol (Internet Protocol, Version 4) as described in IBM's RFC 791. Prior inclusion of <netinet/in_systm.h> is required.

<netinet/udp.h>

This header file contains definitions of the User Datagram Protocol (UDP) header for UDP datagrams. UDP datagrams consist of a fixed header section immediately followed by the data section. The length of entire datagram, including the header and data, is maintained in UDP length field as a count of the number of octets (an octet is 8 bits; on IBM S370/390 systems this is 1 byte) in the datagram. Thus, the mininum value is 8 (64 bits), which is the length of the header alone.

struct udphdr {
    u_short uh_sport;  /* source port      */
    u_short uh_dport;  /* destination port */
    short uh_ulen;     /* udp length       */
    u_short uh_sum;    /* udp checksum     */
};

<arpa/inet.h>

This header file contains declarations for the network address resolution functions. You must include the <netinet/in.h> header file before this header file.

<arpa/nameser.h>

This header file contains definitions that enable applications to communicate with Internet name servers. The contents of this header file are not of interest to most applications; however, this header file must be included before the <resolv.h> header file. Applications that manipulate resolver options must include this header file. You must include the <sys/types.h> header file before this header file.

<resolv.h>

This header file contains global definitions for the resolver. Definitions and structures in the <resolv.h> header file are discussed in the following sections. You must include the <sys/types.h> , <netinet/in.h> , and <arpa/nameser.h> header files before this header file.

state

_res refers to a state structure describing resolver operations. In the SAS/C implementation, _res is a macro. Because _res is not a variable, a program should not directly declare it. Inclusion of the <resolv.h> header file declares _res .

struct state {
   int     retrans;                /* retransmition time interval     */
   int     retry;                  /* number of times to              */
                                   /* retransmit                      */
   long    options;                /* option flags - See below.       */
   int     nscount;                /* number of name servers          */
   struct  sockaddr_in nsaddr_list[MAXNS];  /* address of name        */
                                            /* server                 */
 #define nsaddr  nsaddr_list[0]    /* for backward compatibility      */
   u_short id;                     /* current packet id               */
   char    defdname[MAXDNAME];     /* default domain                  */
   char    *dnsrch[MAXDNSRCH+1];   /* components of domain to search  */
};

Bitwise OR Options

The following bit masks are resolver options that can be specified. They are stored in _res.options .

RES_DEBUG: print resolver debugging messages.
RES_USEVC: use TCP connections rather than UDP datagrams for queries.
RES_STAYOPEN: when specified along with RES_USEVC , keep the TCP connection open between queries.
RES_RECURSE: for queries, set the recursion-desired bit. This is the default. res_send does not make queries iteratively. The name server handles recursion.
RES_DEFNAMES: have res_mkquery append the default domain name to single-component names. This is the default.
RES_DNSRCH: have gethostbyname search for host names in the current parent domains.
RES_IGNTC: ignore truncation errors; do not retry.

<net/if.h>

This header file contains structures that define the network interface and provide a packet transport mechanism. <net/if.h> is useful only for low-level programming of the network interface. You must include the <sys/types.h> and <sys/socket.h> header files before this header file.

<strings.h>

This header file provides compatibility with the BSD UNIX <strings.h> header file and the index , rindex , bzero , ffs , and bcmp functions. Refer to BSD Library Dependencies for more information on using these functions.

Chapter Contents
Previous
Next
Top of Page

	`typedef unsigned u_char;` `u_char;`
	`typedef unsigned u_short;` `u_short;`
	`typedef unsigned u_long;` `u_long;` .