accept() — Accept a new connection on a socket

Standards

Standards / Extensions	C or C++	Dependencies
XPG4.2 Single UNIX Specification, Version 3	both

Format

X/Open:

#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/socket.h>

int accept(int socket, struct sockaddr *__restrict__ address,
           socklen_t *__restrict__address_len);

Berkeley sockets:

#define _OE_SOCKETS
#include <sys/types.h>
#include <sys/socket.h>

int accept(int socket, struct sockaddr *address, int *address_len);

General description

The accept() call is used by a server to accept a connection request from a client. When a connection is available, the socket created is ready for use to read data from the process that requested the connection. The call accepts the first connection on its queue of pending connections for the given socket socket. The accept() call creates a new socket descriptor with the same properties as socket and returns it to the caller. If the queue has no pending connection requests, accept() blocks the caller unless socket is in nonblocking mode. If no connection requests are queued and socket is in nonblocking mode, accept() returns -1 and sets the error code to EWOULDBLOCK. The new socket descriptor cannot be used to accept new connections. The original socket, socket, remains available to accept more connection requests.

Parameter: Description
socket: The socket descriptor.
address: The socket address of the connecting client that is filled in by accept() before it returns. The format of address is determined by the domain that the client resides in. This parameter can be NULL if the caller is not interested in the client address.
address_len: Must initially point to an integer that contains the size in bytes of the storage pointed to by address. On return, that integer contains the size required to represent the address of the connecting socket. If this value is larger than the size supplied on input, then the information contained in sockaddr is truncated to the length supplied on input. If address is NULL, address_len is ignored.

The socket parameter is a stream socket descriptor created with the socket() call. It is usually bound to an address with the bind() call. The listen() call marks the socket as one that accepts connections and allocates a queue to hold pending connection requests. The listen() call places an upper boundary on the size of the queue.

The address parameter is a pointer to a buffer into which the connection requester's address is placed. The address parameter is optional and can be set to be the NULL pointer. If set to NULL, the requester's address is not copied into the buffer. The exact format of address depends on the addressing domain from which the communication request originated. For example, if the connection request originated in the AF_INET domain, address points to a sockaddr_in structure, or if the connection request originated in the AF_INET6 domain, address points to a sockaddr_in6 structure. The sockaddr_in and sockaddr_in6 structures are defined in netinet/in.h. , The address_len parameter is used only if the address is not NULL. Before calling accept(), you must set the integer pointed to by address_len to the size of the buffer, in bytes, pointed to by address. On successful return, the integer pointed to by address_len contains the actual number of bytes copied into the buffer. If the buffer is not large enough to hold the address, up to address_len bytes of the requester's address are copied. If the actual length of the address is greater than the length of the supplied sockaddr, the stored address is truncated. The sa_len member of the store structure contains the length of the untruncated address.

Notes:

This call is used only with SOCK_STREAM sockets. There is no way to screen requesters without calling accept(). The application cannot tell the system the requesters from which it will accept connections. However, the caller can choose to close a connection immediately after discovering the identity of the requester.
The accept() function has a dependency on the level of the Enhanced ASCII Extensions. See Enhanced ASCII support for details.

A socket can be checked for incoming connection requests using the select() call.

Special behavior for C++: To use this function with C++, you must use the _XOPEN_SOURCE_EXTENDED 1 feature test macro.

Returned value

If successful, accept() returns a nonnegative socket descriptor.

If unsuccessful, accept() returns -1 and sets errno to one of the following values:

Error Code: Description
EAGAIN: If during an accept call that changes identity, the UID of the new identity is already at MAXPROCUID, the accept call fails.
EBADF: The socket parameter is not within the acceptable range for a socket descriptor.
EFAULT: Using address and address_len would result in an attempt to copy the address into a portion of the caller's address space into which information cannot be written.
EINTR: A signal interrupted the accept() call before any connections were available.
EINVAL: listen() was not called for socket descriptor socket.
EIO: There has been a network or transport failure.
EMFILE: An attempt was made to open more than the maximum number of file descriptors allowed for this process.
EMVSERR: Two consecutive accept calls that cause an identity change are not allowed. The original identity must be restored (close() the socket that caused the identity change) before any further accepts are allowed to change the identity
ENFILE: The maximum number of file descriptors in the system are already open.
ENOBUFS: Insufficient buffer space is available to create the new socket.
ENOTSOCK: The socket parameter does not refer to a valid socket descriptor.
EOPNOTSUPP: The socket type of the specified socket does not support accepting connections.
EWOULDBLOCK: The socket descriptor socket is in nonblocking mode, and no connections are in the queue.

Example

The following are two examples of the accept() call. In the first, the caller wishes to have the requester's address returned. In the second, the caller does not wish to have the requester's address returned.

int clientsocket;
int s;
struct sockaddr clientaddress;
int address_len;
int accept(int s, struct sockaddr *addr, int *address_len);
/* socket(), bind(), and listen() 
have been called */
/* EXAMPLE 1: I want the address now */
address_len = sizeof(clientaddress);
clientsocket = accept(s, &clientaddress, &address_len);
/* EXAMPLE 2: I can get the address later using getpeername() */
clientsocket = accept(s, (struct sockaddr *) 0, 
(int *) 0);