Sockets listen() API Exit Program

Required Parameter Group:

1	Listen exit information	Input	Char(*)
2	Return indicator	Output	Char(1)

  QSYSINC Member Name: ESOEXTPT

  Exit Point Name: QIBM_QSO_LISTEN

  Exit Point Format Name: LSTN0100

A user-defined exit program enables a custom program to allow or deny a socket to listen for connections based on a program's restrictions. The sockets listen() API will allow or deny a socket to listen for incoming connections based on the return indicator from the exit program.

Authorities and Locks

None.

Required Parameter Group

Listen exit information

INPUT; CHAR(*)

Used by the user-written program to help determine if a socket should be allowed to listen for incoming connections. Refer to Format of Listen Exit Information for details about this parameter.

Return indicator

OUTPUT; CHAR(1)

Indicates whether the socked should be allowed to listen for incoming connections.

'0'	Allow the socket to listen for incoming connections.
'1'	Deny the socket the ability to listen for incoming connections and force listen() to fail with errno set to EPERM.
'9'	Allow the socket the ability to listen for incoming connections and indicate this user exit program should not be called again for this process.

Note: Any value other than '0' or '9' indicates that the socket should be denied the ability to listen for incoming connections.

Format of Listen Exit Information

The following table shows the structure of the listen exit information for format LSTN0100. For detailed descriptions of the fields in this table, see Field Descriptions.

LSTN0100 Format

Offset		Type	Field
Dec	Hex	Type	Field
0	0	Binary(4)	Backlog
4	4	Binary(4)	Local address length
8	8	Char(28)	Local address

Field Descriptions

Backlog. The maximum number of connection requests that can be queued before the system starts rejecting incoming requests for the socket.

Local address. The address the listening socket is bound to. This field is large enough to hold either a sockaddr_in or sockaddr_in6 structure. In order to determine the format of this field refer to the Local address length field.

Local address length. The length of the address structure the listening socket is bound to.

Usage Notes

If more than one exit program is called by this exit point, all of the exit programs must have a return indicator of '0' or '9' otherwise the socket will not be able to listen for incoming connections.
For a listen API involving client SOCKS support, the registered listen exit programs will not be called since there is no useful address information to provide to the exit program.
A return indicator of '9' will prevent a particular user exit program from being called in a process until a change is made to the QIBM_QSO_LISTEN user exit programs in the registration facility.

Related Information

See the following for more information:

listen()--Invite Incoming Connections Requests

Exit program introduced: IBM^® i 7.1

[ Back to top | Communications APIs | APIs by category ]