Sockets accept() API Exit Program

Required Parameter Group:

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

  QSYSINC Member Name: ESOEXTPT

  Exit Point Name: QIBM_QSO_ACCEPT

  Exit Point Format Name: ACPT0100

A user-defined exit program enables a custom program to allow or deny accepted connections based on a program's restrictions. The sockets accept() API will permit or reject an incoming connection from being accepted based on the return indicator from the exit program.

Authorities and Locks

None.

Required Parameter Group

Accept exit information

INPUT; CHAR(*)

Used by the user-written program to help determine if the incoming connection should be accepted. Refer to Format of Accept Exit Information for details about this parameter.

Return indicator

OUTPUT; CHAR(1)

Indicates whether the connection should be accepted or rejected.

'0'	Allow the incoming connection to be accepted.
'1'	Reject the incoming connection.
'9'	Allow the incoming connection to be accepted 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 incoming connection should be rejected.

Format of Accept Exit Information

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

ACPT0100 Format

Offset		Type	Field
Dec	Hex	Type	Field
0	0	Binary(4)	Local bound address length
4	4	Char(28)	Local bound address
32	20	Binary(4)	Local incoming address length
36	24	Char(28)	Local incoming address
64	40	Binary(4)	Remote address length
68	44	Char(28)	Remote address

Field Descriptions

Local bound address. The address the accepting 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 bound address length field.

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

Local incoming address. The address the connection came in on. 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 incoming address length field.

Local incoming address length. The length of the address structure the connection came in on.

Remote address. The address from which the incoming connection to be accepted came. 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 Remote address length field.

Remote address length. The length of the address structure from which the incoming connection to be accepted came.

Usage Notes

Special consideration needs to be given when a user exit program is registered for accept and Fast Response Cache Accelerator, FRCA, is enabled. If a user exit program is registered for QIBM_QSO_ACCEPT and FRCA is enabled, the exit program will have no effect on the connections being accepted through FRCA.
All IPv4-mapped IPv6 addresses will be returned as IPv4 addresses.
Use caution when configuring user exit programs for the sockets accept APIs. An unhandled exception in a user exit program will be treated the same as a return indicator of '1'. The exception could cause all incoming connections to be rejected and thereby block access to the system. The user exit program would need to be removed via the console in order to restore normal connectivity.
There will be no auditing done when a user exit program rejects an incoming connection; it is the user exit program's responsibility to create any desired auditing.
For an accept API involving client SOCKS support, the peer remote address provided from the SOCKS server via the connection that happened as part of Rbind() processing will be provided as the remote address to the registered accept exit programs. The local incoming address and local bound address will contain all zeros since these values technically do not exist.
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 incoming connection will not be permitted.
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_ACCEPT user exit programs in the registration facility.

Related Information

See the following for more information:

accept()--Wait for Connection Request and Make Connection
accept_and_recv()--Wait for Connection Request and Receive the First Message That Was Sent
QsoStartAccept()--Start Asynchronous Accept Operation

Exit program introduced: IBM^® i 7.1

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