VxWorks Reference Manual : Libraries
sockLib - generic socket library
socket( ) - open a socket
bind( ) - bind a name to a socket
listen( ) - enable connections to a socket
accept( ) - accept a connection from a socket
connect( ) - initiate a connection to a socket
connectWithTimeout( ) - try to connect over a socket for a specified duration
sendto( ) - send a message to a socket
send( ) - send data to a socket
sendmsg( ) - send a message to a socket
recvfrom( ) - receive a message from a socket
recv( ) - receive data from a socket
recvmsg( ) - receive a message from a socket
setsockopt( ) - set socket options
getsockopt( ) - get socket options
getsockname( ) - get a socket name
getpeername( ) - get the name of a connected peer
shutdown( ) - shut down a network connection
This library provides UNIX BSD 4.4 compatible socket calls. Use these calls to open, close, read, and write sockets. These sockets can join processes on the same CPU or on different CPUs between which there is a network connection. The calling sequences of these routines are identical to their equivalents under UNIX BSD 4.4.
VxWorks sockets support only the Internet Domain address family. Use AF_INET for the domain argument in subroutines that require it. There is no support for the UNIX Domain address family.
Sockets respond to the following ioctl( ) functions. These functions are defined in the header files ioLib.h and ioctl.h.
- FIONBIO
- Turns on/off non-blocking I/O.
on = TRUE; status = ioctl (sFd, FIONBIO, &on);- FIONREAD
- Reports the number of read-ready bytes available on the socket. On the return of ioctl( ), bytesAvailable has the number of bytes available to read from the socket.
status = ioctl (sFd, FIONREAD, &bytesAvailable);- SIOCATMARK
- Reports whether there is out-of-band data to be read from the socket. On the return of ioctl( ), atMark is TRUE (1) if there is out-of-band data. Otherwise, it is FALSE (0).
status = ioctl (sFd, SIOCATMARK, &atMark);
types.h, mbuf.h, socket.h, socketvar.h
sockLib, netLib, VxWorks Programmer's Guide: Network, UNIX Network Programming , by W. Richard Stevens
socket( ) - open a socket
int socket ( int domain, /* address family (for example, AF_INET) */ int type, /* SOCK_STREAM, SOCK_DGRAM, or SOCK_RAW */ int protocol /* socket protocol (usually 0) */ )
This routine opens a socket and returns a socket descriptor. The socket descriptor is passed to the other socket routines to identify the socket. The socket descriptor is a standard I/O system file descriptor (fd) and can be used with the close( ), read( ), write( ), and ioctl( ) routines.
Available socket types include:
- SOCK_STREAM
- Specifies a connection-based (stream) socket.
- SOCK_DGRAM
- Specifies a datagram (UDP) socket.
- SOCK_RAW
- Specifies a raw socket.
A socket descriptor, or ERROR.
bind( ) - bind a name to a socket
STATUS bind ( int s, /* socket descriptor */ struct sockaddr * name, /* name to be bound */ int namelen /* length of name */ )
This routine associates a network address (also referred to as its "name") with a specified socket so that other processes can connect or send to it. When a socket is created with socket( ), it belongs to an address family but has no assigned name.
OK, or ERROR if there is an invalid socket, the address is either unavailable or in use, or the socket is already bound.
listen( ) - enable connections to a socket
STATUS listen ( int s, /* socket descriptor */ int backlog /* number of connections to queue */ )
This routine enables connections to a socket. It also specifies the maximum number of unaccepted connections that can be pending at one time (backlog). After enabling connections with listen( ), connections are actually accepted by accept( ).
OK, or ERROR if the socket is invalid or unable to listen.
accept( ) - accept a connection from a socket
int accept ( int s, /* socket descriptor */ struct sockaddr * addr, /* peer address */ int * addrlen /* peer address length */ )
This routine accepts a connection on a socket, and returns a new socket created for the connection. The socket must be bound to an address with bind( ), and enabled for connections by a call to listen( ). The accept( ) routine dequeues the first connection and creates a new socket with the same properties as s. It blocks the caller until a connection is present, unless the socket is marked as non-blocking.
The parameter addrlen should be initialized to the size of the available buffer pointed to by addr. Upon return, addrlen contains the size in bytes of the peer's address stored in addr.
A socket descriptor, or ERROR if the call fails.
connect( ) - initiate a connection to a socket
STATUS connect ( int s, /* socket descriptor */ struct sockaddr * name, /* addr of socket to connect */ int namelen /* length of name, in bytes */ )
If s is a socket of type SOCK_STREAM, this routine establishes a virtual circuit between s and another socket specified by name. If s is of type SOCK_DGRAM, it permanently specifies the peer to which messages are sent. If s is of type SOCK_RAW, it specifies the raw socket upon which data is to be sent and received. The name parameter specifies the address of the other socket.
OK, or ERROR if the call fails.
connectWithTimeout( ) - try to connect over a socket for a specified duration
STATUS connectWithTimeout ( int sock, /* socket descriptor */ struct sockaddr * adrs, /* addr of the socket to connect */ int adrsLen, /* length of the socket, in bytes */ struct timeval * timeVal /* time-out value */ )
This routine basically the same as connect( ), except that it lets users specify how long to keep trying to make the new connection.
If the timeVal is a NULL pointer, this routine acts exactly like connect( ). If timeVal is not NULL, it tries to establish a new connection for the duration of the time specified in timeVal. After that time, this routine reports a time-out error if the connection is not established.
OK, or ERROR if a connection cannot be established.
sendto( ) - send a message to a socket
int sendto ( int s, /* socket to send data to */ caddr_t buf, /* pointer to data buffer */ int bufLen, /* length of buffer */ int flags, /* flags to underlying protocols */ struct sockaddr * to, /* recipient's address */ int tolen /* length of to sockaddr */ )
This routine sends a message to the datagram socket named by to. The socket s is received by the receiver as the sending socket.
The maximum length of buf is subject to the limits on UDP buffer size. See the discussion of SO_SNDBUF in the setsockopt( ) manual entry.
You can OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_DONTROUTE (0x4)
- Send without using routing tables.
The number of bytes sent, or ERROR if the call fails.
sockLib, setsockopt( )
send( ) - send data to a socket
int send ( int s, /* socket to send to */ const char * buf, /* pointer to buffer to transmit */ int bufLen, /* length of buffer */ int flags /* flags to underlying protocols */ )
This routine transmits data to a previously established connection-based (stream) socket.
The maximum length of buf is subject to the limits on TCP buffer size; see the discussion of SO_SNDBUF in the setsockopt( ) manual entry.
You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_DONTROUTE (0x4)
- Send without using routing tables.
The number of bytes sent, or ERROR if the call fails.
sockLib, setsockopt( ), sendmsg( )
sendmsg( ) - send a message to a socket
int sendmsg ( int sd, /* socket to send to */ struct msghdr * mp, /* scatter-gather message header */ int flags /* flags to underlying protocols */ )
This routine sends a message to a datagram socket. It may be used in place of sendto( ) to decrease the overhead of reconstructing the message-header structure (msghdr) for each message.
For BSD 4.4 sockets a copy of the mp->msg_iov array will be made. This requires a cluster from the network stack system pool of size mp->msg_iovlen * sizeof (struct iovec) or 8 bytes.
The number of bytes sent, or ERROR if the call fails.
recvfrom( ) - receive a message from a socket
int recvfrom ( int s, /* socket to receive from */ char * buf, /* pointer to data buffer */ int bufLen, /* length of buffer */ int flags, /* flags to underlying protocols */ struct sockaddr * from, /* where to copy sender's addr */ int * pFromLen /* value/result length of from */ )
This routine receives a message from a datagram socket regardless of whether it is connected. If from is non-zero, the address of the sender's socket is copied to it. The value-result parameter pFromLen should be initialized to the size of the from buffer. On return, pFromLen contains the actual size of the address stored in from.
The maximum length of buf is subject to the limits on UDP buffer size; see the discussion of SO_RCVBUF in the setsockopt( ) manual entry.
You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_PEEK (0x2)
- Return data without removing it from socket.
The number of number of bytes received, or ERROR if the call fails.
sockLib, setsockopt( )
recv( ) - receive data from a socket
int recv ( int s, /* socket to receive data from */ char * buf, /* buffer to write data to */ int bufLen, /* length of buffer */ int flags /* flags to underlying protocols */ )
This routine receives data from a connection-based (stream) socket.
The maximum length of buf is subject to the limits on TCP buffer size; see the discussion of SO_RCVBUF in the setsockopt( ) manual entry.
You may OR the following values into the flags parameter with this operation:
- MSG_OOB (0x1)
- Out-of-band data.
- MSG_PEEK (0x2)
- Return data without removing it from socket.
The number of bytes received, or ERROR if the call fails.
sockLib, setsockopt( )
recvmsg( ) - receive a message from a socket
int recvmsg ( int sd, /* socket to receive from */ struct msghdr * mp, /* scatter-gather message header */ int flags /* flags to underlying protocols */ )
This routine receives a message from a datagram socket. It may be used in place of recvfrom( ) to decrease the overhead of breaking down the message-header structure msghdr for each message.
For BSD 4.4 sockets a copy of the mp->msg_iov array will be made. This requires a cluster from the network stack system pool of size mp->msg_iovlen * sizeof (struct iovec) or 8 bytes.
The number of bytes received, or ERROR if the call fails.
setsockopt( ) - set socket options
STATUS setsockopt ( int s, /* target socket */ int level, /* protocol level of option */ int optname, /* option name */ char * optval, /* pointer to option value */ int optlen /* option length */ )
This routine sets the options associated with a socket. To manipulate options at the "socket" level, level should be SOL_SOCKET. Any other levels should use the appropriate protocol number.
The following sections discuss the socket options available for stream (TCP) sockets.
Specify the SO_KEEPALIVE option to make the transport protocol (TCP) initiate a timer to detect a dead connection:setsockopt (sock, SOL_SOCKET, SO_KEEPALIVE, &optval, sizeof (optval));This prevents an application from hanging on an invalid connection. The value at optval for this option is an integer (type int), either 1 (on) or 0 (off).The integrity of a connection is verified by transmitting zero-length TCP segments triggered by a timer, to force a response from a peer node. If the peer does not respond after repeated transmissions of the KEEPALIVE segments, the connection is dropped, all protocol data structures are reclaimed, and processes sleeping on the connection are awakened with an ETIMEDOUT error.
The ETIMEDOUT timeout can happen in two ways. If the connection is not yet established, the KEEPALIVE timer expires after idling for TCPTV_KEEP_INIT. If the connection is established, the KEEPALIVE timer starts up when there is no traffic for TCPTV_KEEP_IDLE. If no response is received from the peer after sending the KEEPALIVE segment TCPTV_KEEPCNT times with interval TCPTV_KEEPINTVL, TCP assumes that the connection is invalid. The parameters TCPTV_KEEP_INIT, TCPTV_KEEP_IDLE, TCPTV_KEEPCNT, and TCPTV_KEEPINTVL are defined in the file target/h/net/tcp_timer.h.
Specify the SO_LINGER option to determine whether TCP should perform a "graceful" close:setsockopt (sock, SOL_SOCKET, SO_LINGER, &optval, sizeof (optval));For a "graceful" close in response to the shutdown of a connection, TCP tries to make sure that all the unacknowledged data in transmission channel are acknowledged, and the peer is shut down properly, by going through an elaborate set of state transitions.The value at optval indicates the amount of time to linger if there is unacknowledged data, using struct linger in target/h/sys/socket.h. The linger structure has two members: l_onoff and l_linger. l_onoff can be set to 1 to turn on the SO_LINGER option, or set to 0 to turn off the SO_LINGER option. l_linger indicates the amount of time to linger. If l_onoff is turned on and l_linger is set to 0, a default value TCP_LINGERTIME (specified in netinet/tcp_timer.h) is used for incoming connections accepted on the socket.
When SO_LINGER is turned on and the l_linger field is set to 0, TCP simply drops the connection by sending out an RST if a connection is already established; frees up the space for the TCP protocol control block; and wakes up all tasks sleeping on the socket.
For the client side socket, the value of l_linger is not changed if it is set to 0. To make sure that the value of l_linger is 0 on a newly accepted socket connection, issue another setsockopt( ) after the accept( ) call.
Currently the exact value of l_linger time is actually ignored (other than checking for 0); that is, TCP performs the state transitions if l_linger is not 0, but does not explicitly use its value.
Specify the TCP_NODELAY option for real-time protocols, such as the X Window System Protocol, that require immediate delivery of many small messages:setsockopt (sock, IPPROTO_TCP, TCP_NODELAY, &optval, sizeof (optval));The value at optval is an integer (type int) set to either 1 (on) or 0 (off).By default, the VxWorks TCP implementation employs an algorithm that attempts to avoid the congestion that can be produced by a large number of small TCP segments. This typically arises with virtual terminal applications (such as telnet or rlogin) across networks that have low bandwidth and long delays. The algorithm attempts to have no more than one outstanding unacknowledged segment in the transmission channel while queueing up the rest of the smaller segments for later transmission. Another segment is sent only if enough new data is available to make up a maximum sized segment, or if the outstanding data is acknowledged.
This congestion-avoidance algorithm works well for virtual terminal protocols and bulk data transfer protocols such as FTP without any noticeable side effects. However, real-time protocols that require immediate delivery of many small messages, such as the X Window System Protocol, need to defeat this facility to guarantee proper responsiveness in their operation.
TCP_NODELAY is a mechanism to turn off the use of this algorithm. If this option is turned on and there is data to be sent out, TCP bypasses the congestion-avoidance algorithm: any available data segments are sent out if there is enough space in the send window.
Specify the SO_DEBUG option to let the underlying protocol module record debug information.setsockopt (sock, SOL_SOCKET, SO_DEBUG, &optval, sizeof (optval));The value at optval for this option is an integer (type int), either 1 (on) or 0 (off).
The following section discusses an option for datagram (UDP) sockets.
Specify the SO_BROADCAST option when an application needs to send data to more than one destination:setsockopt (sock, SOL_SOCKET, SO_BROADCAST, &optval, sizeof (optval));The value at optval is an integer (type int), either 1 (on) or 0 (off).
The following section discusses options for multicasting on UDP and RAW sockets.
Specify the IP_ADD_MEMBERSHIP option when a process needs to join multicast group:setsockopt (sock, IPPROTO_IP, IP_ADD_MEMBERSHIP, (char *)&ipMreq, sizeof (ipMreq));The value of ipMreq is an ip_mreq structure. ipMreq.imr_multiaddr.s_addr is the internet multicast address ipMreq.imr_interface.s_addr is the internet unicast address of the interface through which the multicast packet needs to pass.
Specify the IP_DROP_MEMBERSHIP option when a process needs to leave a previously joined multicast group:setsockopt (sock, IPPROTO_IP, IP_DROP_MEMBERSHIP, (char *)&ipMreq, sizeof (ipMreq));The value of ipMreq is an ip_mreq structure. ipMreq.imr_multiaddr.s_addr is the internet multicast address. ipMreq.imr_interface.s_addr is the internet unicast address of the interface to which the multicast address was bound.
Specify the IP_MULTICAST_IF option when an application needs to specify an outgoing network interface through which all multicast packets are sent:setsockopt (sock, IPPROTO_IP, IP_MULTICAST_IF, (char *)&ifAddr, sizeof (mCastAddr));The value of ifAddr is an in_addr structure. ifAddr.s_addr is the internet network interface address.
Specify the IP_MULTICAST_TTL option when an application needs to select a default TTL (time to live) for outgoing multicast packets:
setsockopt (sock, IPPROTO_IP, IP_MULTICAST_TTL, &optval, sizeof(optval));The value at optval is an integer (type int), time to live value.
optval(TTL) Application Scope 0 same interface 1 same subnet 31 local event video 32 same site 63 local event audio 64 same region 95 IETF channel 2 video 127 IETF channel 1 video 128 same continent 159 IETF channel 2 audio 191 IETF channel 1 audio 223 IETF channel 2 low-rate audio 255 IETF channel 1 low-rate audio unrestricted in scope
Enable or disable loopback of outgoing multicasts.setsockopt (sock, IPPROTO_IP, IP_MULTICAST_LOOP, &optval, sizeof(optval));The value at optval is an integer (type int), either 1(on) or 0 (off).
The following section discusses options for RAW, DGRAM or STREAM sockets.
Sets the IP options sent from this socket with every packet.setsockopt (sock, IPPROTO_IP, IP_OPTIONS, optbuf, optbuflen);Here optbuf is a buffer containing the options.
Sets the Type-Of-Service field for each packet sent from this socket.setsockopt (sock, IPPROTO_IP, IP_TOS, &optval, sizeof(optval));Here optval is an integer (type int). This integer can be set to IPTOS_LOWDELAY, IPTOS_THROUGHPUT, IPTOS_RELIABILITY, or IPTOS_MINCOST, to indicate how the packets sent on this socket should be prioritized.
Sets the Time-To-Live field for each packet sent from this socket.setsockopt (sock, IPPROTO_IP, IP_TTL, &optval, sizeof(optval));Here optval is an integer (type int), indicating the number of hops a packet can take before it is discarded.
Sets whether or not reversed source route queueing will be enabled for incoming datagrams. (Not implemented)setsockopt (sock, IPPROTO_IP, IP_RECVRETOPTS, &optval, sizeof(optval));Here optval is a boolean (type int). However, this option is currently not implemented, so setting it will not change the behavior of the system.
Sets whether or not the socket will receive the IP address of the destination of an incoming datagram in control data.setsockopt (sock, IPPROTO_IP, IP_RECVDSTADDR, &optval, sizeof(optval));Here optval is a boolean (type int).
The following sections describe options that can be used with either stream or datagram sockets.
Specify the SO_REUSEADDR option to bind a stream socket to a local port that may be still bound to another stream socket:setsockopt (sock, SOL_SOCKET, SO_REUSEADDR, &optval, sizeof (optval));The value at optval is an integer (type int), either 1 (on) or 0 (off).When the SO_REUSEADDR option is turned on, applications may bind a stream socket to a local port even if it is still bound to another stream socket, if that other socket is associated with a "zombie" protocol control block context not yet freed from previous sessions. The uniqueness of port number combinations for each connection is still preserved through sanity checks performed at actual connection setup time. If this option is not turned on and an application attempts to bind to a port which is being used by a zombie protocol control block, the bind( ) call fails.
Specify the SO_SNDBUF option to adjust the maximum size of the socket-level send buffer:setsockopt (sock, SOL_SOCKET, SO_SNDBUF, &optval, sizeof (optval));The value at optval is an integer (type int) that specifies the size of the socket-level send buffer to be allocated.When stream or datagram sockets are created, each transport protocol reserves a set amount of space at the socket level for use when the sockets are attached to a protocol. For TCP, the default size of the send buffer is 8192 bytes. For UDP, the default size of the send buffer is 9216 bytes. Socket-level buffers are allocated dynamically from the mbuf pool.
The effect of setting the maximum size of buffers (for both SO_SNDBUF and SO_RCVBUF, described below) is not actually to allocate the mbufs from the mbuf pool, but to set the high-water mark in the protocol data structure which is used later to limit the amount of mbuf allocation. Thus, the maximum size specified for the socket level send and receive buffers can affect the performance of bulk data transfers. For example, the size of the TCP receive windows is limited by the remaining socket-level buffer space. These parameters must be adjusted to produce the optimal result for a given application.
Specify the SO_RCVBUF option to adjust the maximum size of the socket-level receive buffer:setsockopt (sock, SOL_SOCKET, SO_RCVBUF, &optval, sizeof (optval));The value at optval is an integer (type int) that specifies the size of the socket-level receive buffer to be allocated.When stream or datagram sockets are created, each transport protocol reserves a set amount of space at the socket level for use when the sockets are attached to a protocol. For TCP, the default size is 8192 bytes. UDP reserves 41600 bytes, enough space for up to forty incoming datagrams (1 Kbyte each).
See the SO_SNDBUF discussion above for a discussion of the impact of buffer size on application performance.
Specify the SO_OOBINLINE option to place urgent data within the normal receive data stream:setsockopt (sock, SOL_SOCKET, SO_OOBINLINE, &optval, sizeof (optval));TCP provides an expedited data service which does not conform to the normal constraints of sequencing and flow control of data streams. The expedited service delivers "out-of-band" (urgent) data ahead of other "normal" data to provide interrupt-like services (for example, when you hit a CTRL-C during telnet or rlogin session while data is being displayed on the screen.)TCP does not actually maintain a separate stream to support the urgent data. Instead, urgent data delivery is implemented as a pointer (in the TCP header) which points to the sequence number of the octet following the urgent data. If more than one transmission of urgent data is received from the peer, they are all put into the normal stream. This is intended for applications that cannot afford to miss out on any urgent data but are usually too slow to respond to them promptly.
OK, or ERROR if there is an invalid socket, an unknown option, an option length greater than MLEN, insufficient mbufs, or the call is unable to set the specified option.
getsockopt( ) - get socket options
STATUS getsockopt ( int s, /* socket */ int level, /* protocol level for options */ int optname, /* name of option */ char * optval, /* where to put option */ int * optlen /* where to put option length */ )
This routine returns relevant option values associated with a socket. To manipulate options at the "socket" level, level should be SOL_SOCKET. Any other levels should use the appropriate protocol number. The parameter optlen should be initialized to indicate the amount of space referenced by optval. On return, the value of the option is copied to optval and the actual size of the option is copied to optlen.
Although optval is passed as a char *, the actual variable whose address gets passed in should be an integer or a structure, depending on which optname is being passed. Refer to setsockopt( ) to determine the correct type of the actual variable (whose address should then be cast to a char *).
OK, or ERROR if there is an invalid socket, an unknown option, or the call is unable to get the specified option.
Because SO_REUSEADDR has an integer parameter, the variable to be passed to getsockopt( ) should be declared as
int reuseVal;and passed in as(char *)&reuseVal.Otherwise the user might mistakenly declare reuseVal as a character, in which case getsockopt( ) will only return the first byte of the integer representing the state of this option. Then whether the return value is correct or always 0 depends on the endian-ness of the machine.
sockLib, setsockopt( )
getsockname( ) - get a socket name
STATUS getsockname ( int s, /* socket descriptor */ struct sockaddr * name, /* where to return name */ int * namelen /* space available in name, later filled in */ /* actual name size */ )
This routine gets the current name for the specified socket s. The parameter namelen should be initialized to indicate the amount of space referenced by name. On return, the name of the socket is copied to name and the actual size of the socket name is copied to namelen.
OK, or ERROR if the socket is invalid or not connected.
getpeername( ) - get the name of a connected peer
STATUS getpeername ( int s, /* socket descriptor */ struct sockaddr * name, /* where to put name */ int * namelen /* space available in name, later filled in */ /* actual name size */ )
This routine gets the name of the peer connected to socket s. The parameter namelen should be initialized to indicate the amount of space referenced by name. On return, the name of the socket is copied to name and the actual size of the socket name is copied to namelen.
OK, or ERROR if the socket is invalid or not connected.
shutdown( ) - shut down a network connection
STATUS shutdown ( int s, /* socket to shut down */ int how /* 0 = receives disallowed 1 = sends disallowed 2 = sends and */ /* disallowed */ )
This routine shuts down all, or part, of a connection-based socket s. If the value of how is 0, receives are disallowed. If how is 1, sends are disallowed. If how is 2, both sends and receives are disallowed.
ERROR if the socket is invalid or has no registered socket-specific routines; otherwise shutdown( ) returns the return value from the socket-specific shutdown routine (typically OK in the case of a successful shutdown or ERROR otherwise).