STREAMS-UX Programmer's Guide (February 2007)

STREAMS IOCTL Commands
Overview
Appendix A
147
I_RECVFD
Retrieves the file descriptor associated with the message sent by an I_SENDFD IOCTL over a stream pipe. The
arg is a pointer to a data buffer large enough to hold a strrecvfd data structure containing the following
members:
int fd;
uid_t uid;
gid_t gid;
char fill[8];
The fd is an integer file descriptor, uid and gid are the user ID and group ID, respectively, of the sending
stream.
If O_NONBLOCK is clear, I_RECVFD will block until a message is present at the stream head. If O_NONBLOCK is
set, I_RECVFD will fail with errno set to EAGAIN if no message is present at the stream head.
If the message at the stream head is a message sent by a I_SENDFD, a new user file descriptor is allocated for
the file pointer contained in the message. The new file descriptor is placed in the fd field of the strrecvfd
structure. The structure is copied into the user data buffer pointed to by arg.
On failure, errno is set to one of the following values:
[EAGAIN] The O_NONBLOCK option was set, and a message was not present on the stream head read
queue.
[EFAULT] The arg parameter points outside the allocated address space.
[EBADMSG] The message present on the stream head read queue did not contain a passed file descriptor.
[EMFILE] Too many open files. No more file descriptors are permitted to be opened.
[ENXIO] A hangup was received on fildes.
I_SENDFD
Requests the stream associated with fildes to send a message, containing a file pointer, to the stream head
at the other end of a stream pipe. The file pointer corresponds to arg, which must be an open file descriptor.
The I_SENDFD command converts arg into the corresponding system file pointer. It allocates a message block
and inserts the file pointer in the block. The user ID and group ID associated with the sending process are
also inserted. This message is placed directly on the read queue of the stream head at the other end of the
stream pipe to which it is connected.
On failure, errno is set to one of the following values:
[EAGAIN] The sending stream head could not allocate a message block for the file pointer.
[EAGAIN] The read queue of the receiving stream head was full and could not accept the message.
[EBADF] The arg parameter is not a valid open file descriptor.
[EINVAL] The fildes parameter does not refer to a stream.
[ENXIO] A hangup was received on fildes.