accept()--Wait for Connection Request and Make Connection

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

  int accept(int socket_descriptor,
             struct sockaddr *address,
             int *address_length)

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

  int accept(int socket_descriptor,
             struct sockaddr *address,
             socklen_t *address_length)

The accept() function is used to wait for connection requests. accept() takes the first connection request on the queue of pending connection requests and creates a new socket to service the connection request.

accept() is used with connection-oriented socket types, such as SOCK_STREAM.

There are two versions of the API, as shown above. The base IBM^® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX^® 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

Parameters

socket_descriptor

(Input) The descriptor of the socket on which to wait.

address

(Output) A pointer to a buffer of type struct sockaddr in which the address from which the connection request was received is stored. The structure sockaddr is defined in <sys/socket.h>.

The BSD 4.3 structure is:

      struct sockaddr {
         u_short sa_family;
         char    sa_data[14];
      };

The BSD 4.4/UNIX 98 compatible structure is:

      typedef uchar   sa_family_t;

      struct sockaddr {
         uint8_t     sa_len;
         sa_family_t sa_family;
         char        sa_data[14];
      };

The BSD 4.4 sa_len field is the length of the address. The sa_family field identifies the address family to which the address belongs, and sa_data is the address whose format is dependent on the address family.

Note: See the usage notes about using different address families with sockaddr_storage.

address_length

(Input/output) This parameter is a value-result field. The caller passes a pointer to the length of the address parameter. On return from the call, address_length contains the actual length of the address from which the connection request was received.

Authorities

When the socket identified by the socket_descriptor is of type AF_INET and a connection indication request is received over an APPC device, the thread must have adequate authority. The thread must have retrieve, insert, delete, and update authority to the APPC device. When the thread does not have this level of authority, an errno of EACCES is returned.

Return Value

accept() returns an integer. Possible values are:

• -1 (unsuccessful)
  
  
• n (successful), where n is a socket descriptor.

Error Conditions

When accept() fails, errno can be set to one of the following:

Error condition	Additional information
[EACCES]	Permission denied. A connection indication request was received on the socket referenced by the socket_descriptor parameter, but the process that issued the accept() did not have the appropriate privileges required to handle the request. The connection indication request is reset by the system.
[EBADF]	Descriptor not valid.
[ECONNABORTED]	Connection ended abnormally. An accept() was issued on a socket for which receives have been disallowed (due to a shutdown() call). This also could be encountered if time elapsed since a successful Rbind() is greater than the margin allowed by the associated SOCKS server. An accept() was issued on a socket in blocking mode and one or more connections have been reset and there are no acceptable connections in the queue. This is only valid if socket option SO_ACCEPTECONNABORTED was enabled for the listening socket.
[EFAULT]	Bad address. System detected an address which was not valid while attempting to access the address or address_length parameters.
[EINTR]	Interrupted function call.
[EINVAL]	Parameter not valid. This error code indicates one of the following: The address_length parameter is set to a value that is less than zero, and the address parameter is set to a value other than a NULL pointer. A listen() has not been issued against the socket referenced by the socket_descriptor parameter.
[EIO]	Input/output error.
[EMFILE]	Too many descriptions for this process.
[ENFILE]	Too many descriptions in system.
[ENOBUFS]	There is not enough buffer space for the requested operation.
[ENOTSOCK]	The specified descriptor does not reference a socket.
[EOPNOTSUPP]	Operation not supported. The socket_descriptor parameter references a socket that does not support the accept(). The accept() is only valid on sockets that are connection-oriented (for example, type of SOCK_STREAM).
[EPERM]	The operation is not permitted. An accept() was issued on a socket and a user exit program registered for the exit point, QIBM_QSO_ACCEPT, has rejected the incoming connection being accepted. This is only valid if socket option SO_ACCEPTEPERM was enabled for the listening socket.
[EUNATCH]	The protocol required to support the specified address family is not available at this time.
[EUNKNOWN]	Unknown system state.
[EWOULDBLOCK]	Operation would have caused the thread to be suspended.

Error Messages

Usage Notes

1. If the address parameter is set to a NULL pointer or the address_length parameter points to an integer which has a value that is equal to zero, the address from which the connection request was received is not returned.
   
   
2. If the length of the address to be returned exceeds the length of the address parameter, the returned address is truncated.
   
   
3. The following are inherited by the descriptor returned by the accept() call:
   
   
   • All socket options with a level of SOL_SOCKET.
     
     
   • The status flags:
     
     
     • Blocking flag (set/reset either by the ioctl() call with the FIONBIO request or by the fcntl() call with the F_SETFL command and the status flag set to O_NONBLOCK).
       
       
     • Asynchronous flag (set/reset either by the ioctl() call with the FIOASYNC request or by the fcntl() call with the F_SETFL command and the status flag set to FASYNC).
       
       
   • The process ID or process group ID that is to receive SIGIO or SIGURG signals (set/reset by either the ioctl() call with the FIOSETOWN or the SIOCSPGRP request, or by the fcntl() call with the F_SETOWN command).
     
     
4. Closing a socket causes any queued but unaccepted connection requests to be reset.
   
   
5. The structure sockaddr is a generic structure used for any address family but it is only 16 bytes long. The actual address returned for some address families may be much larger. You should declare storage for the address with the structure sockaddr_storage. This structure is large enough and aligned for any protocol-specific structure. It may then be cast as sockaddr structure for use on the APIs. The ss_family field of the sockaddr_storage will always align with the family field of any protocol-specific structure. The BSD 4.3 structure is:
   
   

    #define _SS_MAXSIZE 304
    #define _SS_ALIGNSIZE (sizeof (char*))
    #define _SS_PAD1SIZE (_SS_ALIGNSIZE - sizeof(sa_family_t))
    #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(sa_family_t)+
                           _SS_PAD1SIZE + _SS_ALIGNSIZE))
   
    struct sockaddr_storage {
        sa_family_t   ss_family;
        char         _ss_pad1[_SS_PAD1SIZE];
        char*        _ss_align;
        char         _ss_pad2[_SS_PAD2SIZE];
    };
   

   The BSD 4.4/UNIX 98 compatible structure is:
   
   

    #define _SS_MAXSIZE 304
    #define _SS_ALIGNSIZE (sizeof (char*))
    #define _SS_PAD1SIZE (_SS_ALIGNSIZE - (sizeof(uint8_t) + sizeof(sa_family_t)))
    #define _SS_PAD2SIZE (_SS_MAXSIZE - (sizeof(uint8_t) + sizeof(sa_family_t)+
                           _SS_PAD1SIZE + _SS_ALIGNSIZE))
   
    struct sockaddr_storage {
        uint8_t       ss_len;
        sa_family_t   ss_family;
        char         _ss_pad1[_SS_PAD1SIZE];
        char*        _ss_align;
        char         _ss_pad2[_SS_PAD2SIZE];
    };
   

6. If the socket is using an address family of AF_UNIX, the address (which is a path name) is returned in the default coded character set identifier (CCSID) currently in effect for the job.
   
   
7. If the socket is using an address family of AF_UNIX_CCSID, the output structure sockaddr_unc defines the format and coded character set identifier (CCSID) of the address (which is a path name).
   
   
8. If a successful Rbind() has been performed on the listening socket, then a new connection is not returned, but rather an inbound connection occurs on the same listening socket. The descriptor number returned is different, but it actually refers to the same connection referred to by the listening socket.
   
   
9. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the accept() API is mapped to qso_accept98().
10. A user exit point, QIBM_QSO_ACCEPT, exists to optionally accept or reject incoming connections being accepted based on the return code from the registered user exit program. For more information refer to Sockets accept() API Exit Program.

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• bind()--Set Local Address for Socket
  
  
• fcntl()--Perform File Control Command
  
  
• ioctl()--Perform I/O Control Request
  
  
• listen()--Invite Incoming Connections Requests

[ Back to top | UNIX-Type APIs | APIs by category ]