gtpc1m42 | Transmission Control Protocol/Internet Protocol |
The listen function completes the binding necessary for a socket
and creates a connection request queue for incoming requests.
Format
#include <socket.h>
int listen(int s,
int backlog);
- s
- The socket descriptor.
- backlog
- Maximum length for the queue of pending connections. If
backlog is less than 0, its value is set to 0. For sockets
using TCP/IP offload support, if backlog is greater than SOMAXCONN
or 5, its value is set to SOMAXCONN. For sockets using TCP/IP native
stack support, the maximum value for backlog is
32 767. If the value passed is greater than 32 767,
the value is set to 32 767.
Normal Return
Return code 0 indicates that the function was successful.
Error Return
A return code equal to -1 indicates an error. You can get the
specific error code by calling sock_errno. See Appendix C, Socket Error Return Codes for more information about socket errors.
- Note:
- Unless otherwise stated in the description, the following error codes can be
returned for either TCP/IP offload support or TCP/IP native stack
support.
- Value
- Description
- SOCOPNOTSUP
- The s parameter is not a socket descriptor that supports the
listen function.
- SOCNOTSOCK
- The s parameter is not a valid socket descriptor.
- SOCINVAL
- The socket is not in the correct state for listening.
- EIBMIUCVERR
- An error occurred when the function call was sent to the offload
device. This error code is returned only for TCP/IP offload
support.
- E1052STATE
- The socket was closed because the system was in or cycling down to 1052
state.
- EINACT
- All offload devices associated with the socket descriptor have been
disconnected. The socket is closed. This error code is returned
only for TCP/IP offload support.
- EINACTWS
- An offload device associated with the socket descriptor has been
disconnected. The socket is still available. This error code is
returned only for TCP/IP offload support.
- ESYSTEMERROR
- A system error has occurred and closed the socket. This error code
is returned only for TCP/IP offload support.
- OFFLOADTIMEOUT
- The offload device did not respond to the function call in the requested
time period. This error code is returned only for TCP/IP offload
support.
Programming Considerations
- The listen function applies only to stream sockets. The
function performs the following tasks:
- It completes the binding necessary for socket s if
bind has not been called for s.
- It creates a connection request queue, which is the length of the
backlog parameter, to queue incoming connection requests.
After the queue is full, additional connection requests are ignored.
- The listen function indicates a readiness to accept client
connection requests. This function transforms an active socket into a
passive socket. Once called, s can never be used as an
active socket to start connection requests. Calling listen
is the third of four steps that a server performs to accept a
connection. This function is called after allocating a stream socket
with socket, and after binding a name to s with
bind. The listen function must be called before
calling accept.
Examples
The following example sets up itself to be a server and it also creates a
client request queue of size 5.
#include <socket.h>
·
·
·
int rc;
int server_sock;
·
·
·
rc = listen(server_sock, 5);
Related Information