takedescriptor()--Receive Socket Access from Another Job

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

 int takedescriptor(char *source_job)

The takedescriptor() function is used to obtain a descriptor in one IBM^® i job which was passed from another IBM i job by a givedescriptor().

Parameters

source_job

(Input) A pointer to the internal job identifier that identifies the source job from which to receive a passed descriptor.

Authorities

No authorization is required.

Return Value

takedescriptor() returns an integer. Possible values are:

• -1 (unsuccessful)
  
  
• n (successful), where n is a descriptor.

Error Conditions

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

Error Messages

Usage Notes

1. This function can only obtain a descriptor if the sender of the descriptor referenced the job that this takedescriptor() is issued in by explicitly specifying this job's identification on the target_job parameter of the givedescriptor().
   
   
2. If the source_job parameter is a NULL pointer, then a descriptor can be received from any job which issues a givedescriptor() that references the job in which takedescriptor() is issued.
   
   
3. If no descriptor is available to be received, the takedescriptor() is blocked.
   
   
4. If both the job in which the givedescriptor() is issued and the job specified by the target_job parameter end while a descriptor is in transit, the descriptor is reclaimed by the system, and the resource that it represents is closed.
   
   
5. The information to specify in the target_job parameter of the givedescriptor() and in the source_job parameter of the takedescriptor() can be obtained in the actual target job by using a work management API (for example, QUSRJOBI) to retrieve the internal job identifier.
   
   
6. For files and directories, takedescriptor() is only supported for objects in the Root, QOpenSys, User-defined file systems (UDFS), and Network File System (NFS).
   
   
7. If this function is called by a thread executing one of the scan-related exit programs (or any of its created threads), it will fail with error code [ENOTSUP]. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.
   
   
8. When the descriptor is obtained using takedescriptor(), any information accessed using that descriptor with the various read and write interfaces will be in binary, even if the original descriptor's accesses would have had text conversions occur. See Using CCSIDs and code pages in the open()--Open file documentation for more information about text conversion.
   
   

Related Information

• givedescriptor()--Pass Descriptor Access to Another Job
  
  
• sendmsg()--Send Data or Descriptors or Both
  
  
• recvmsg()--Receive Data or Descriptors or Both

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