givedescriptor()--Pass Descriptor Access to Another Job

Syntax

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

 int givedescriptor(int descriptor,
                    char *target_job)

  Service Program Name: QSOSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

The givedescriptor() function is used to pass a descriptor from one IBM^® i job to another IBM i job.

Parameters

descriptor: (Input) The descriptor that is to be passed to the target job.
target_job: (Input) A pointer to the internal job identifier of the target job that is to receive the descriptor referenced by the descriptor parameter.

Authorities

To give a descriptor, the source thread must be running under one of the following user profiles:

A user profile that is the same as the job user identity of the target job
A user profile that has all object (*ALLOBJ) special authority

The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work management topic collection.

Return Value

givedescriptor() returns an integer. Possible values are:

-1 (unsuccessful)
0 (successful)

Error Conditions

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

[EACCES]	Permission denied. The job does not have the appropriate privileges required to give the descriptor.
[EBADF]	Descriptor not valid.
[EFAULT]	Bad address. The system detected an address which was not valid while attempting to access the target_job parameter.
[EINVAL]	Parameter not valid. This error code indicates one of the following: The target_job parameter points to data that is not valid. The target_job parameter refers to a job that is not active.
[EIO]	Input/output error.
[EOPNOTSUPP]	Operation not supported. The underlying instance represented by the descriptor does not support passing access rights.
[EUNKNOWN]	Unknown system state.

Error Messages

Message ID	Error Message Text
CPE3418 E	Possible APAR condition or hardware failure.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFA081 E	Unable to set return value or error code.

Usage Notes

The information to specify in the target_job parameter can be obtained in the actual target job by using a work management API (for example, QUSRJOBI) to retrieve the internal job identifier.
It is the responsibility of the application programmer to privately pass this information from the target job to the job that issues the givedescriptor(). One possible method that could be used to exchange this information is to use data queues.
The target_job does not have to be waiting on a takedescriptor() for the givedescriptor() to complete successfully.
If both the job in which the givedescriptor() is issued and the target_job end while a descriptor is in transit, the descriptor is reclaimed by the system, and the resource that it represents is closed.
For files and directories, givedescriptor() is only supported for objects in the Root, QOpenSys, User-defined file systems (UDFS), and Network File System (NFS).

Related Information

takedescriptor()--Receive Socket Access from Another Job
sendmsg()--Send Data or Descriptors or Both
recvmsg()--Receive Data or Descriptors or Both
spawn()--Spawn Process

API introduced: V3R1

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