givesocket()

The givesocket() call tells TCP⁄IP to make the specified socket available to a takesocket() call issued by another program. Any connected stream socket can be given. Typically, givesocket() is used by a master program that obtains sockets by means of accept() and gives them to slave programs that handle one socket at a time.

This call can be used only in the AF_INET domain.

#include <manifest.h>
#include <bsdtypes.h>
#include <socket.h>
 
int  givesocket(int d, struct clientid *clientid)

Parameter: Description
d: The descriptor of a socket to be given to another application.
clientid: Points to a client ID structure specifying the target program to which the socket is to be given.

To pass a socket, the master program first calls givesocket() with the client ID structure that is specified as follows:

Field: Description
domain: This call is supported only in the AF_INET domain.
name: The slave program address space name, left-justified and padded with blanks. The slave program can run in the same address space as the master program, in which case this field is set to the master program address space. If this field is set to blanks, any MVS™ address space can take the socket.
subtaskname: Specifies blanks.
reserved: Specifies binary zeros.

The master program then calls getclientid() to obtain its client ID, and passes its client ID, along with the descriptor of the socket to be given, to the slave program. One way to pass a socket is by passing the slave program startup parameter list.

The slave program calls takesocket(), specifying the master program client ID and socket descriptor.

Waiting for the slave program to take the socket, the master program uses select() to test the given socket for an exception condition. When select() reports that an exception condition is pending, the master program calls close() to free the given socket. If select() reports a timeout has occurred, that is, the socket has not been taken by slave program, the master program should take the socket that was given by calling takesocket(). The master program then owns the socket again and should call close() to close the socket.

If your program closes the socket before a pending exception condition is indicated, the TCP connection is immediately reset, and the target program call to takesocket() call is unsuccessful. Calls other than the close() call issued on a given socket return a value of -1, with errno set to EBADF.

Sockets that have been given and not taken for a period of four days will be closed and become unavailable. If a select for the socket is outstanding, it is posted.

Return values

The value 0 indicates success. The value -1 indicates an error. Errno identifies a specific error.

Errno: Description
EBADF: The d parameter is not a valid socket descriptor. The socket has already been given. The socket domain is not AF_INET.
EBUSY: Listen() has been called for the socket.
EFAULT: Using the clientid parameter as specified would result in an attempt to access storage outside the caller address space.
EINVAL: The clientid parameter does not specify a valid client identifier.
ENOTCONN: The socket is not connected.
EOPNOTSUPP: The socket type is not SOCK_STREAM.

Related calls

accept(), close(), getclientid(), listen(), select(), takesocket()