givesocket (BPX1GIV, BPX4GIV) — Give a socket to another program

Function

The givesocket callable service makes a specified socket available to a takesocket call to be issued by another program.

Requirements

Parameters

Socket_descriptor

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the socket file descriptor for which the givesocket is to be done.

Clientid

Supplied and returned parameter

Type:

Structure

Length:

Length of BPXYCID

The name of a structure that contains Clientid information identifying the (slave) program to which the socket is to be given. This information is typically obtained with the getclientid service issued by the slave and passed to the server. Clientid input may be as follows:

• CIdDomain - domain of the socket being given. See BPXYSOCK — Map SOCKADDR structure and constants for more information about the values defined for this field.
• CIdName - one of the following:
  • Blanks - allows any program to take the socket using the takesocket service.
  • The slave program's address space name, left-justified, and padded with blanks.
  • A fullword of binary zeroes followed by the slave program's process id.
• CIdTask - used only if an address space name was supplied in the CIdName field. One of the following:
  • Blanks - allows any subtask in the address space to take the socket.
  • The slave program's subtask identifier.
• CIdReserved - one of the following:
  • The CIdType field of the CIdReserved area set to CId#Close. This results in the givesocket service doing a close of the input socket and returning a unique socket token in the CIdSockToken field of the CIdReserved area.
  • The CIdType field of the CIdReserved area set to CId#Select. This indicates that the application intends to block on select() for exceptions, waiting for the takesocket call to occur before closing the socket. It allows a select call to return exception status even if that call is made after the takesocket call, as long as the socket was not closed. It also results in the connection being severed if the giver closes the socket before it has been taken.
  • The CIdType field of the CIdReserved area set to zeros. The program will not be calling select() to coordinate with the taker of the socket. Either the socket is not going to be closed or the giver and taker have some other method of coordination for the giver to know when the taker has called takesocket().
    Note: If select() for exception is called before takesocket() the select will return when takesocket() is called but if select() is called after takesocket() it will hang. CidType of Cid#Select should be used if select() is going to be called by the giver.
    If the given socket is closed before the takesocket() is issued it is possible for that socket descriptor number to be reused in the giver's process so a sequence of accept(), givesocket(), and close() calls issued several times before any takesocket() calls can result in several sockets with the same descriptor number waiting to be taken. In this case the oldest given socket will be taken and first in first out order is used.

    Note: If select() is called when there are several given sockets with the same descriptor number waiting to be taken then select() will operate on the current active socket for that descriptor so it effectively waits for the last (newest) given socket to be taken and the order becomes last in first out.

The Clientid is a returned parameter only if the CIdType field in the CIdReserved area is set to CId#Close. A unique token for the given socket is then returned in the CIdToken field of the CIdReserved area. This token, instead of the socket descriptor, is to be passed to the slave program to be used on the takesocket service. The token must be used, rather than the socket descriptor, because the socket being given will be closed, and the socket descriptor may be reused. See BPXYCID — Map the returning structure for getclientid() for more information about the format of this field.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the givesocket service returns one of the following:

• 0 if successful.
• -1 if the request is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the givesocket service stores the return code. The givesocket service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The givesocket service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EBADF	The Socket_descriptor is not valid, or the socket has already been given.
EFAULT	Using the Clientid parameter as specified would result in an attempt to access storage that is outside the caller's address space.
EINVAL	The Clientid parameter does not specify a valid client identifier; or the CIdDomain in the Clientid parameter does not match the actual domain of the input Socket_descriptor.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the givesocket service stores the reason code. The givesocket service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. The program that does the givesocket will always be able to do a takesocket for the given socket, even if its identity does not match that of the Clientid input of the givesocket.
2. The Clientid output of the getclientid service (issued by the slave program and passed to the server) is intended to be used as the input Clientid of the givesocket service. If you use a FunctionCode of 2 on the getclientid service to obtain Clientid information that will then be used as the Clientid input of the givesocket service, you will ensure the best performance of the givesocket service, and the most secure identification of the validity of the taker.
3. Setting the CIdType field of the CIdReserved area in the Clientid structure to CId#Close improves performance, by allowing the givesocket service to automatically close the socket, rather than requiring the application to do a select and a close.
4. If the given socket is not closed, it can still be used, even after the takesocket() has been done. The socket can be shared between the giver and taker in the same way that an inherited socket can be shared between parent and child after a fork() has been issued.

Related services

• getclientid (BPX1GCL, BPX4GCL) — Obtain the calling program's identifier
• takesocket (BPX1TAK, BPX4TAK) — Acquire a socket from another program

Characteristics and restrictions

There are no restrictions on the use of the givesocket service.