qnx_fd_attach()

get or update a file descriptor

Synopsis:

#include <sys/fd.h>
int qnx_fd_attach( pid_t owner_pid,
                   int fd,
                   nid_t nid,
                   pid_t pid, vid,
                   unsigned flags,
                   unsigned handle );

The qnx_fd_attach() function is used to get a new file descriptor from the system or to update an existing descriptor. This function is invoked by open(), and shouldn't need to be called by most applications. This function is called twice to set up a file descriptor I/O channel:

once by the client, to obtain a free file descriptor
once by the manager, to set the handle when it receives an open request

When the client calls this function with owner_pid set to zero, the handle parameter is ignored. For example,

qnx_fd_attach( 0, 0, nid, pid, vid, flags, 0 );

The fd parameter is a starting value to be used in a search for a new file descriptor. A value of zero causes qnx_fd_attach() to find the first free descriptor. The nid and pid represent the logical node number and the process ID on that node of the server. If the nid is zero, the local node is assumed. If nid isn't zero and isn't the local node then a virtual circuit must be set up to the server on nid, pid. This virtual circuit is passed as the vid argument. In the local case vid must be set to be the same as pid.

The flags field is broken down into two 8-bit bytes. The lower 8 bits represent the maximum I/O request size (times 256) expected to be sent using this file descriptor. Therefore a value of 1 means 256 bytes. This is a best guess, and a value of zero is acceptable. It's typically the same size as any virtual circuit set up. The top 8 bits are reserved for flags, which are added with an OR operation (not shifted):

_FD_CLOSE_ON_EXEC: The file descriptor is closed (instead of inherited) if the process calls any of the exec... or spawn... (but not fork()) functions.

When a manager receives an open message, it calls this function with arguments for owner_pid,fd and handle. The owner_pid is the pid returned by the Receive() or Receivemx() call. All other arguments are ignored. The handle is a 16-bit value that's used only by the server to map a file descriptor into a pointer or index to its internal tables. Note that if you wish to pass a pointer for the handle, it must be a near 16-bit pointer. For example,

qnx_fd_attach( pid, fd, 0, 0, 0, 0, handle );

Returns:

A file descriptor on success. On error, -1 is returned, and errno is set.

Errors:

ESRCH: The owner_pid, pid or vid parameter refers to a process that doesn't exist.
EBADF: When owner_pid is nonzero, the fd argument refers to a file descriptor that doesn't exist.
EMFILE: The current process doesn't have any free file descriptors greater than or equal to fd.
EPERM: When owner_pid is nonzero, the current process doesn't have permission to update the file descriptor.

Examples:

A meaningful example is beyond the scope of the library documentation. Contact QNX Software Systems Ltd. for availability of a technical note on resource managers.

Classification:

QNX

Safety:
Interrupt handler	No
Signal handler	Yes, but modifies errno
Thread	Yes