ConnectDupFd(), ConnectDupFd_r()

QNX SDP8.0C Library ReferenceAPIDeveloper

Support file descriptor duplication

Note:
Don't use the ConnectDupFd() or ConnectDupFd_r() kernel call directly; instead, use dupfd(), dupfd_getinfo(), dupfd_register(), or dupfd_unregister().

Synopsis:

#include <sys/neutrino.h>

int ConnectDupFd( int op,
                  pid64_t  * pid,
                  dupfd_handle_t * handle,
                  pid_t * srvpid,
                  struct _msg_info_hdr * info );

int ConnectDupFd_r( int op,
                    pid64_t  * pid,
                    dupfd_handle_t * handle,
                    pid_t * srvpid,
                    struct _msg_info_hdr * info );

Arguments:

op
The operation to perform; one of:
pid
The PID (process ID) of the process, which can be a 32- or 64-bit input parameter or a 64-bit output parameter.
  • When using the _NTO_DUPFD_LOOKUP operation, the pid receives the peer PID as an output parameter. This means that the process that sends the file descriptor receives the PID of the recipient, whereas the process that receives the file descriptor receives the sender's PID.
  • For the operations, _NTO_DUPFD_REGISTER, and _NTO_DUPFD_REGISTER_DISC, it is the PID of the process that receives the file descriptor.
  • For the operation, _NTO_DUPFD_VERIFY, it is the PID of the process making the request to the server to duplicate the file descriptor.
handle
The handle is an identifier that authorizes the transfer of a file descriptor. There is a limit of 200 handles per process. If this limit is reached, the kernel's default behaviour is to replace the oldest entry.
Note:
For the operations, _NTO_DUPFD_REGISTER and _NTO_DUPFD_REGISTER_DISC, the handle argument is updated with the handle output parameter. Whereas, for any other operation, handle is used as an input parameter.
srvpid
A pointer to pid_t that is updated with the PID of the server process associated with the handle.
Note:
Only the _NTO_DUPFD_LOOKUP operation uses this parameter.
info
A pointer to a structure that contains information about the file descriptor to duplicate.
Note:
  • The operation _NTO_DUPFD_LOOKUP uses this as an output parameter and the kernel provides the information about the file descriptor to duplicate.
  • The _NTO_DUPFD_REGISTER and the _NTO_DUPFD_REGISTER_DISC use this as an input parameter. The coid (connection ID) of the info structure must be set to the file descriptor to be duplicated.
  • The _NTO_DUPFD_VERIFY operation also uses this as an input parameter. However, the parameter is set to match the contents of the info member of an _IO_DUP message.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The ConnectDupFd() and ConnectDupFd_r() kernel calls duplicate file descriptors.

The section that follows describes the possible operations.

_NTO_DUPFD_REGISTER

The sender registers and retrieves a handle for a file descriptor. If the maximum number of file descriptors are registered, the system searches for an entry that was associated with a process that has exited. If no entry is found, the function returns an error of EAGAIN. Otherwise, it returns a handle.

_NTO_DUPFD_REGISTER_DISC

This operation is similar to _NTO_DUPFD_REGISTER. The only difference is that if the maximum number of file descriptors are already registered, and no stale entries are found, the oldest entry is identified and replaced with the new registration.

Note:
In both _NTO_DUPFD_REGISTER and _NTO_DUPFD_REGISTER_DISC, the following are applicable:
  • The coid (connection ID) of the info structure should be set to the file descriptor to be duplicated.
  • The srvpid argument isn't used.
  • The handle is used as an output parameter.

_NTO_DUPFD_UNREGISTER

The sender uses this operation to unregister a handle. This operation only uses the handle parameter.

_NTO_DUPFD_LOOKUP

The process that receives a duped file descriptor uses it to lookup the required information for an _IO_DUP message. The call succeeds only if the caller is one of the two processes associated with the file descriptor. When a call succeeds, the _msg_info_hdr structure is filled with the necessary information for performing a duplication operation.

Note:
In _NTO_DUPFD_LOOKUP, the following is applicable:
  • You provide the handle as an input parameter when using this function. The function returns the values of pid (set to the process to receive the file descriptor) and srvpid (set to the resmgr that supports the file descriptor as output parameters).

_NTO_DUPFD_VERIFY

The server that provides the file descriptor being transferred verifies that the _IO_DUP request comes with approval from the sending process. Only the server can make the call, as all other calls are rejected.

Note:
In _NTO_DUPFD_VERIFY, the following is applicable:
  • The process duplicates the file descriptor using the handle as an input parameter. The pid parameter is the PID of the process that is making the request (the process that sends the _IO_DUP message).
  • The info parameter is also used and contains the info member of the _IO_DUP message that the server received.
  • The process doesn't use srvpid.

Returns:

0 on success, or -1 if an error occurred (errno is set).

Errors:

EAGAIN
The flag _NTO_DUPFD_REGISTER was specified and the limit on the number of handles has been reached.
EBADF
The file descriptor isn't valid.
EFAULT
The pid, handle, srvcpid, or info pointers are invalid.
EINVAL
The file descriptor is invalid or is a side channel.
ENOENT
One of the following errors occurred:
  • The handle is invalid.
  • The handle's associated file descriptor is closed.
  • The handle is unregistered
  • The pid you provided does not match the one associated with the handle for a verify operation.
  • The process that services the file descriptor didn't make the call for a verify operation.
  • The process that registered the file descriptor or the process that the handle is for didn't make the call for the lookup operation.
ENOMEM
Insufficient memory available to register.
ESRCH
The process ID doesn't represent an existing process.

Classification:

QNX OS

Safety:
Cancellation pointNo
Signal handlerYes
ThreadYes
Page updated: