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:
|
| [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