diff options
Diffstat (limited to 'upstream/archlinux/man3p/ioctl.3p')
| -rw-r--r-- | upstream/archlinux/man3p/ioctl.3p | 1216 |
1 files changed, 1216 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/ioctl.3p b/upstream/archlinux/man3p/ioctl.3p new file mode 100644 index 00000000..aedf5a2f --- /dev/null +++ b/upstream/archlinux/man3p/ioctl.3p @@ -0,0 +1,1216 @@ +'\" et +.TH IOCTL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ioctl +\(em control a STREAMS device (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include <stropts.h> +.P +int ioctl(int \fIfildes\fP, int \fIrequest\fP, ... /* arg */); +.fi +.SH DESCRIPTION +The +\fIioctl\fR() +function shall perform a variety of control functions on STREAMS +devices. For non-STREAMS devices, the functions performed by this call +are unspecified. The +.IR request +argument and an optional third argument (with varying type) shall be +passed to and interpreted by the appropriate part of the STREAM +associated with +.IR fildes . +.P +The +.IR fildes +argument is an open file descriptor that refers to a device. +.P +The +.IR request +argument selects the control function to be performed and shall +depend on the STREAMS device being addressed. +.P +The +.IR arg +argument represents additional information that is needed by this +specific STREAMS device to perform the requested function. The type of +.IR arg +depends upon the particular control request, but it shall be either an +integer or a pointer to a device-specific data structure. +.P +The +\fIioctl\fR() +commands applicable to STREAMS, their arguments, and error conditions +that apply to each individual command are described below. +.P +The following +\fIioctl\fR() +commands, with error values indicated, are applicable to all STREAMS +files: +.IP I_PUSH 12 +Pushes the module whose name is pointed to by +.IR arg +onto the top of the current STREAM, just below the STREAM head. It then +calls the +\fIopen\fR() +function of the newly-pushed module. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PUSH command shall fail if: +.TP +.BR EINVAL +Invalid module name. +.TP +.BR ENXIO +Open function of new module failed. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_POP 12 +Removes the module just below the STREAM head of the STREAM pointed to +by +.IR fildes . +The +.IR arg +argument should be 0 in an I_POP request. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_POP command shall fail if: +.TP +.BR EINVAL +No module present in the STREAM. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_LOOK 12 +Retrieves the name of the module just below the STREAM head of the +STREAM pointed to by +.IR fildes , +and places it in a character string pointed to by +.IR arg . +The buffer pointed to by +.IR arg +should be at least FMNAMESZ+1 +bytes long, where FMNAMESZ is defined in +.IR <stropts.h> . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_LOOK command shall fail if: +.TP +.BR EINVAL +No module present in the STREAM. +.RE +.IP I_FLUSH 12 +Flushes read and/or write queues, depending on the value of +.IR arg . +Valid +.IR arg +values are: +.RS 12 +.IP FLUSHR 12 +Flush all read queues. +.IP FLUSHW 12 +Flush all write queues. +.IP FLUSHRW 12 +Flush all read and all write queues. +.P +The +\fIioctl\fR() +function with the I_FLUSH command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for flush message. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_FLUSHBAND 12 +Flushes a particular band of messages. The +.IR arg +argument points to a +.BR bandinfo +structure. The +.IR bi_flag +member may be one of FLUSHR, FLUSHW, or FLUSHRW as described above. The +.IR bi_pri +member determines the priority band to be flushed. +.IP I_SETSIG 12 +Requests that the STREAMS implementation send the SIGPOLL signal to the +calling process when a particular event has occurred on +the STREAM associated with +.IR fildes . +I_SETSIG supports an asynchronous processing capability in STREAMS. The +value of +.IR arg +is a bitmask that specifies the events for which the process should be +signaled. It is the bitwise-inclusive OR of any combination of the +following constants: +.RS 12 +.IP S_RDNORM 12 +A normal (priority band set to 0) message has arrived at the head of a +STREAM head read queue. A signal shall be generated even if the message +is of zero length. +.IP S_RDBAND 12 +A message with a non-zero priority band has arrived at the head of a +STREAM head read queue. A signal shall be generated even if the message +is of zero length. +.IP S_INPUT 12 +A message, other than a high-priority message, has arrived at the head +of a STREAM head read queue. A signal shall be generated even if the +message is of zero length. +.IP S_HIPRI 12 +A high-priority message is present on a STREAM head read queue. A +signal shall be generated even if the message is of zero length. +.IP S_OUTPUT 12 +The write queue for normal data (priority band 0) just below the STREAM +head is no longer full. This notifies the process that there is room +on the queue for sending (or writing) normal data downstream. +.IP S_WRNORM 12 +Equivalent to S_OUTPUT. +.IP S_WRBAND 12 +The write queue for a non-zero priority band just below the STREAM head +is no longer full. This notifies the process that there is room on the +queue for sending (or writing) priority data downstream. +.IP S_MSG 12 +A STREAMS signal message that contains the SIGPOLL signal has reached +the front of the STREAM head read queue. +.IP S_ERROR 12 +Notification of an error condition has reached the STREAM head. +.IP S_HANGUP 12 +Notification of a hangup has reached the STREAM head. +.IP S_BANDURG 12 +When used in conjunction with S_RDBAND, SIGURG is generated instead of +SIGPOLL when a priority message reaches the front of the STREAM head +read queue. +.P +If +.IR arg +is 0, the calling process shall be unregistered and shall not receive +further SIGPOLL signals for the stream associated with +.IR fildes . +.P +Processes that wish to receive SIGPOLL signals shall ensure that they +explicitly register to receive them using I_SETSIG. If several +processes register to receive this +signal for the same event on the same STREAM, each process shall be +signaled when the event occurs. +.P +The +\fIioctl\fR() +function with the I_SETSIG command shall fail if: +.TP +.BR EINVAL +The value of +.IR arg +is invalid. +.TP +.BR EINVAL +The value of +.IR arg +is 0 and the calling process is not registered to receive +the SIGPOLL signal. +.TP +.BR EAGAIN +There were insufficient resources to store the signal request. +.RE +.IP I_GETSIG 12 +Returns the events for which the calling process is currently +registered to be sent a SIGPOLL signal. The events are returned as a +bitmask in an +.BR int +pointed to by +.IR arg , +where the events are those specified in the description of +I_SETSIG above. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_GETSIG command shall fail if: +.TP +.BR EINVAL +Process is not registered to receive the SIGPOLL signal. +.RE +.IP I_FIND 12 +Compares the names of all modules currently present in the STREAM to +the name pointed to by +.IR arg , +and returns 1 if the named module is present in the STREAM, or returns +0 if the named module is not present. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_FIND command shall fail if: +.TP +.BR EINVAL +.IR arg +does not contain a valid module name. +.RE +.IP I_PEEK 12 +Retrieves the information in the first message on the STREAM head read +queue without taking the message off the queue. It is analogous to +\fIgetmsg\fR() +except that this command does not remove the message from the queue. +The +.IR arg +argument points to a +.BR strpeek +structure. +.RS 12 +.P +The application shall ensure that the +.IR maxlen +member in the +.BR ctlbuf +and +.BR "databuf strbuf" +structures is set to the number of bytes of control information and/or +data information, respectively, to retrieve. The +.IR flags +member may be marked RS_HIPRI or 0, as described by +\fIgetmsg\fR(). +If the process sets +.IR flags +to RS_HIPRI, for example, I_PEEK shall only look for a high-priority +message on the STREAM head read queue. +.P +I_PEEK returns 1 if a message was retrieved, and returns 0 if no +message was found on the STREAM head read queue, or if the RS_HIPRI +flag was set in +.IR flags +and a high-priority message was not present on the STREAM head read +queue. It does not wait for a message to arrive. On return, +.BR ctlbuf +specifies information in the control buffer, +.BR databuf +specifies information in the data buffer, and +.IR flags +contains the value RS_HIPRI or 0. +.RE +.IP I_SRDOPT 12 +Sets the read mode using the value of the argument +.IR arg . +Read modes are described in +\fIread\fR(). +Valid +.IR arg +flags are: +.RS 12 +.IP RNORM 12 +Byte-stream mode, the default. +.IP RMSGD 12 +Message-discard mode. +.IP RMSGN 12 +Message-nondiscard mode. +.P +The bitwise-inclusive OR of RMSGD and RMSGN shall return +.BR [EINVAL] . +The bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall +result in the other flag overriding RNORM which is the default. +.P +In addition, treatment of control messages by the STREAM head may be +changed by setting any of the following flags in +.IR arg : +.IP RPROTNORM 12 +Fail +\fIread\fR() +with +.BR [EBADMSG] +if a message containing a control part is at the front of the +STREAM head read queue. +.IP RPROTDAT 12 +Deliver the control part of a message as data when a process issues a +\fIread\fR(). +.IP RPROTDIS 12 +Discard the control part of a message, delivering any data portion, +when a process issues a +\fIread\fR(). +.P +The +\fIioctl\fR() +function with the I_SRDOPT command shall fail if: +.TP +.BR EINVAL +The +.IR arg +argument is not valid. +.RE +.IP I_GRDOPT 12 +Returns the current read mode setting, as described above, in an +.BR int +pointed to by the argument +.IR arg . +Read modes are described in +\fIread\fR(). +.IP I_NREAD 12 +Counts the number of data bytes in the data part of the first message +on the STREAM head read queue and places this value in the +.BR int +pointed to by +.IR arg . +The return value for the command shall be the number of messages on the +STREAM head read queue. For example, if 0 is returned in +.IR arg , +but the +\fIioctl\fR() +return value is greater than 0, this indicates that a zero-length +message is next on the queue. +.IP I_FDINSERT 12 +Creates a message from specified buffer(s), adds information about +another STREAM, and sends the message downstream. The message contains +a control part and an optional data part. The data and control parts to +be sent are distinguished by placement in separate buffers, as +described below. The +.IR arg +argument points to a +.BR strfdinsert +structure. +.RS 12 +.P +The application shall ensure that the +.IR len +member in the +.BR "ctlbuf strbuf" +structure is set to the size of a +.BR t_uscalar_t +plus the number of bytes of control information to be sent with the +message. The +.IR fildes +member specifies the file descriptor of the other STREAM, and the +.IR offset +member, which must be suitably aligned for use as a +.BR t_uscalar_t , +specifies the offset from the start of the control buffer where +I_FDINSERT shall store a +.BR t_uscalar_t +whose interpretation is specific to the STREAM end. The application +shall ensure that the +.IR len +member in the +.BR "databuf strbuf" +structure is set to the number of bytes of data information to be sent +with the message, or to 0 if no data part is to be sent. +.P +The +.IR flags +member specifies the type of message to be created. A normal message is +created if +.IR flags +is set to 0, and a high-priority message is created if +.IR flags +is set to RS_HIPRI. For non-priority messages, I_FDINSERT shall block if +the STREAM write queue is full due to internal flow control conditions. +For priority messages, I_FDINSERT does not block on this condition. For +non-priority messages, I_FDINSERT does not block when the write queue +is full and O_NONBLOCK is set. Instead, it fails and sets +.IR errno +to +.BR [EAGAIN] . +.P +I_FDINSERT also blocks, unless prevented by lack of internal resources, +waiting for the availability of message blocks in the STREAM, +regardless of priority or whether O_NONBLOCK has been specified. No +partial message is sent. +.P +The +\fIioctl\fR() +function with the I_FDINSERT command shall fail if: +.TP +.BR EAGAIN +A non-priority message is specified, the O_NONBLOCK flag is set, and +the STREAM write queue is full due to internal flow control +conditions. +.TP +.BR EAGAIN " or " ENOSR +.br +Buffers cannot be allocated for the message that is to be created. +.TP +.BR EINVAL +One of the following: +.RS 12 +.IP -- 4 +The +.IR fildes +member of the +.BR strfdinsert +structure is not a valid, open STREAM file descriptor. +.IP -- 4 +The size of a +.BR t_uscalar_t +plus +.IR offset +is greater than the +.IR len +member for the buffer specified through +.BR ctlbuf . +.IP -- 4 +The +.IR offset +member does not specify a properly-aligned location in the data buffer. +.IP -- 4 +An undefined value is stored in +.IR flags . +.RE +.TP +.BR ENXIO +Hangup received on the STREAM identified by either the +.IR fildes +argument or the +.IR fildes +member of the +.BR strfdinsert +structure. +.TP +.BR ERANGE +The +.IR len +member for the buffer specified through +.BR databuf +does not fall within the range specified by the maximum and minimum +packet sizes of the topmost STREAM module; or the +.IR len +member for the buffer specified through +.BR databuf +is larger than the maximum configured size of the data part of a +message; or the +.IR len +member for the buffer specified through +.BR ctlbuf +is larger than the maximum configured size of the control part of a +message. +.RE +.IP I_STR 12 +Constructs an internal STREAMS +\fIioctl\fR() +message from the data pointed to by +.IR arg , +and sends that message downstream. +.RS 12 +.P +This mechanism is provided to send +\fIioctl\fR() +requests to downstream modules and drivers. It allows information to be +sent with +\fIioctl\fR(), +and returns to the process any information sent upstream by the +downstream recipient. I_STR shall block until the system responds with +either a positive or negative acknowledgement message, or until the +request times out after some period of time. If the request times out, +it shall fail with +.IR errno +set to +.BR [ETIME] . +.P +At most, one I_STR can be active on a STREAM. Further I_STR calls shall +block until the active I_STR completes at the STREAM head. The default +timeout interval for these requests is 15 seconds. The O_NONBLOCK flag +has no effect on this call. +.P +To send requests downstream, the application shall ensure that +.IR arg +points to a +.BR strioctl +structure. +.P +The +.IR ic_cmd +member is the internal +\fIioctl\fR() +command intended for a downstream module or driver and +.IR ic_timout +is the number of seconds (\-1=infinite, 0=use +implementation-defined timeout interval, >0=as specified) an I_STR +request shall wait for acknowledgement before timing out. +.IR ic_len +is the number of bytes in the data argument, and +.IR ic_dp +is a pointer to the data argument. The +.IR ic_len +member has two uses: on input, it contains the length of the data +argument passed in, and on return from the command, it contains the +number of bytes being returned to the process (the buffer pointed to by +.IR ic_dp +should be large enough to contain the maximum amount of data that any +module or the driver in the STREAM can return). +.P +The STREAM head shall convert the information pointed to by the +.BR strioctl +structure to an internal +\fIioctl\fR() +command message and send it downstream. +.P +The +\fIioctl\fR() +function with the I_STR command shall fail if: +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the +\fIioctl\fR() +message. +.TP +.BR EINVAL +The +.IR ic_len +member is less than 0 or larger than the maximum configured size of the +data part of a message, or +.IR ic_timout +is less than \-1. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +A downstream +\fIioctl\fR() +timed out before acknowledgement was received. +.P +An I_STR can also fail while waiting for an acknowledgement if a +message indicating an error or a hangup is received at the STREAM head. +In addition, an error code can be returned in the positive or negative +acknowledgement message, in the event the +\fIioctl\fR() +command sent downstream fails. For these cases, I_STR shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_SWROPT 12 +Sets the write mode using the value of the argument +.IR arg . +Valid bit settings for +.IR arg +are: +.RS 12 +.IP SNDZERO 12 +Send a zero-length message downstream when a +\fIwrite\fR() +of 0 bytes occurs. To not send a zero-length message when a +\fIwrite\fR() +of 0 bytes occurs, the application shall ensure that this bit is not +set in +.IR arg +(for example, +.IR arg +would be set to 0). +.P +The +\fIioctl\fR() +function with the I_SWROPT command shall fail if: +.TP +.BR EINVAL +.IR arg +is not the above value. +.RE +.IP I_GWROPT 12 +Returns the current write mode setting, as described above, in the +.BR int +that is pointed to by the argument +.IR arg . +.IP I_SENDFD 12 +Creates a new reference to the open file description associated with +the file descriptor +.IR arg , +and writes a message on the STREAMS-based pipe +.IR fildes +containing this reference, together with the user ID and group ID of +the calling process. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_SENDFD command shall fail if: +.TP +.BR EAGAIN +The sending STREAM is unable to allocate a message block to contain the +file pointer; or the read queue of the receiving STREAM head is full +and cannot accept the message sent by I_SENDFD. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument is not connected to a STREAM pipe. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.P +The +\fIioctl\fR() +function with the I_SENDFD command may fail if: +.TP +.BR EINVAL +The +.IR arg +argument is equal to the +.IR fildes +argument. +.RE +.IP I_RECVFD 12 +Retrieves the reference to an open file description from a message +written to a STREAMS-based pipe using the I_SENDFD command, and +allocates a new file descriptor in the calling process that refers to +this open file description. The +.IR arg +argument is a pointer to a +.BR strrecvfd +data structure as defined in +.IR <stropts.h> . +.RS 12 +.P +The +.IR fd +member is a file descriptor. The +.IR uid +and +.IR gid +members are the effective user ID and effective group ID, respectively, +of the sending process. +.P +If O_NONBLOCK is not set, I_RECVFD shall block until a message is +present at the STREAM head. If O_NONBLOCK is set, I_RECVFD shall fail +with +.IR errno +set to +.BR [EAGAIN] +if no message is present at the STREAM head. +.P +If the message at the STREAM head is a message sent by an I_SENDFD, a +new file +descriptor shall be allocated for the open file descriptor referenced +in the message. The new file descriptor is placed in the +.IR fd +member of the +.BR strrecvfd +structure pointed to by +.IR arg . +.P +The +\fIioctl\fR() +function with the I_RECVFD command shall fail if: +.TP +.BR EAGAIN +A message is not present at the STREAM head read queue and the +O_NONBLOCK flag is set. +.TP +.BR EBADMSG +The message at the STREAM head read queue is not a message containing a +passed file descriptor. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_LIST 12 +Allows the process to list all the module names on the STREAM, up to +and including the topmost driver name. If +.IR arg +is a null pointer, the return value shall be the number of modules, +including the driver, that are on the STREAM pointed to by +.IR fildes . +This lets the process allocate enough space for the module names. +Otherwise, it should point to a +.BR str_list +structure. +.RS 12 +.P +The +.IR sl_nmods +member indicates the number of entries the process has allocated in the +array. Upon return, the +.IR sl_modlist +member of the +.BR str_list +structure shall contain the list of module names, and the number of +entries that have been filled into the +.IR sl_modlist +array is found in the +.IR sl_nmods +member (the number includes the number of modules including the +driver). The return value from +\fIioctl\fR() +shall be 0. The entries are filled in starting at the top of the STREAM +and continuing downstream until either the end of the STREAM is +reached, or the number of requested modules (\c +.IR sl_nmods ) +is satisfied. +.P +The +\fIioctl\fR() +function with the I_LIST command shall fail if: +.TP +.BR EINVAL +The +.IR sl_nmods +member is less than 1. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers. +.RE +.IP I_ATMARK 12 +Allows the process to see if the message at the head of the STREAM head +read queue is marked by some module downstream. The +.IR arg +argument determines how the checking is done when there may be multiple +marked messages on the STREAM head read queue. It may take on the +following values: +.RS 12 +.IP ANYMARK 12 +Check if the message is marked. +.IP LASTMARK 12 +Check if the message is the last one marked on the queue. +.P +The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted. +.P +The return value shall be 1 if the mark condition is satisfied; +otherwise, the value shall be 0. +.P +The +\fIioctl\fR() +function with the I_ATMARK command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_CKBAND 12 +Checks if the message of a given priority band exists on the STREAM +head read queue. This shall return 1 if a message of the given priority +exists, 0 if no such message exists, or \-1 on error. +.IR arg +should be of type +.BR int . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_CKBAND command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_GETBAND 12 +Returns the priority band of the first message on the STREAM head read +queue in the integer referenced by +.IR arg . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_GETBAND command shall fail if: +.TP +.BR ENODATA +No message on the STREAM head read queue. +.RE +.IP I_CANPUT 12 +Checks if a certain band is writable. +.IR arg +is set to the priority band in question. The return value shall be 0 if +the band is flow-controlled, 1 if the band is writable, or \-1 on +error. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_CANPUT command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_SETCLTIME 12 +This request allows the process to set the time the STREAM head shall +delay when a STREAM is closing and there is data on the write queues. +Before closing each module or driver, if there is data on its write +queue, the STREAM head shall delay for the specified amount of time to +allow the data to drain. If, after the delay, data is still present, it +shall be flushed. The +.IR arg +argument is a pointer to an integer specifying the number of +milliseconds to delay, rounded up to the nearest valid value. If +I_SETCLTIME is not performed on a STREAM, an implementation-defined +default timeout interval is used. +.br +.RS 12 +.P +The +\fIioctl\fR() +function with the I_SETCLTIME command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_GETCLTIME 12 +Returns the close time delay in the integer pointed to by +.IR arg . +.SS "Multiplexed STREAMS Configurations" +.P +The following commands are used for connecting and disconnecting +multiplexed STREAMS configurations. These commands use an +implementation-defined default timeout interval. +.IP I_LINK 12 +Connects two STREAMs, where +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver, and +.IR arg +is the file descriptor of the STREAM connected to another driver. The +STREAM designated by +.IR arg +is connected below the multiplexing driver. I_LINK requires the +multiplexing driver to send an acknowledgement message to the STREAM +head regarding the connection. This call shall return a multiplexer ID +number (an identifier used to disconnect the multiplexer; see I_UNLINK) +on success, and \-1 on failure. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_LINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate STREAMS storage to perform the I_LINK. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument does not support multiplexing; or +.IR arg +is not a STREAM or is already connected downstream from a multiplexer; +or the specified I_LINK operation would connect the STREAM head in more +than one place in the multiplexed STREAM. +.P +An I_LINK can also fail while waiting for the multiplexing driver to +acknowledge the request, if a message indicating an error or a hangup +is received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_LINK fails with +.IR errno +set to the value in the message. +.RE +.IP I_UNLINK 12 +Disconnects the two STREAMs specified by +.IR fildes +and +.IR arg . +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver. The +.IR arg +argument is the multiplexer ID number that was returned by the I_LINK +\fIioctl\fR() +command when a STREAM was connected downstream from the multiplexing +driver. If +.IR arg +is MUXID_ALL, then all STREAMs that were connected to +.IR fildes +shall be disconnected. As in I_LINK, this command requires +acknowledgement. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_UNLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the acknowledgement message. +.TP +.BR EINVAL +Invalid multiplexer ID number. +.P +An I_UNLINK can also fail while waiting for the multiplexing driver to +acknowledge the request if a message indicating an error or a hangup is +received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_UNLINK shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_PLINK 12 +Creates a +.IR "persistent connection" +between two STREAMs, where +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver, and +.IR arg +is the file descriptor of the STREAM connected to another driver. This +call shall create a persistent connection which can exist even if the +file descriptor +.IR fildes +associated with the upper STREAM to the multiplexing driver is closed. +The STREAM designated by +.IR arg +gets connected via a persistent connection below the multiplexing +driver. I_PLINK requires the multiplexing driver to send an +acknowledgement message to the STREAM head. This call shall return a +multiplexer ID number (an identifier that may be used to disconnect the +multiplexer; see I_PUNLINK) on success, and \-1 on failure. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate STREAMS storage to perform the I_PLINK. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument does not support multiplexing; or +.IR arg +is not a STREAM or is already connected downstream from a multiplexer; +or the specified I_PLINK operation would connect the STREAM head in +more than one place in the multiplexed STREAM. +.P +An I_PLINK can also fail while waiting for the multiplexing driver to +acknowledge the request, if a message indicating an error or a hangup +is received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_PLINK shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_PUNLINK 12 +Disconnects the two STREAMs specified by +.IR fildes +and +.IR arg +from a persistent connection. The +.IR fildes +argument is the file descriptor of the STREAM connected to the +multiplexing driver. The +.IR arg +argument is the multiplexer ID number that was returned by the I_PLINK +\fIioctl\fR() +command when a STREAM was connected downstream from the multiplexing +driver. If +.IR arg +is MUXID_ALL, then all STREAMs which are persistent connections +to +.IR fildes +shall be disconnected. As in I_PLINK, this command requires the +multiplexing driver to acknowledge the request. +.br +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PUNLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the acknowledgement message. +.TP +.BR EINVAL +Invalid multiplexer ID number. +.P +An I_PUNLINK can also fail while waiting for the multiplexing driver to +acknowledge the request if a message indicating an error or a hangup is +received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_PUNLINK shall fail with +.IR errno +set to the value in the message. +.RE +.SH "RETURN VALUE" +Upon successful completion, +\fIioctl\fR() +shall return a value other than \-1 that depends upon the STREAMS device +control function. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +Under the following general conditions, +\fIioctl\fR() +shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EINTR +A signal was caught during the +\fIioctl\fR() +operation. +.TP +.BR EINVAL +The STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.P +If an underlying device driver detects an error, then +\fIioctl\fR() +shall fail if: +.TP +.BR EINVAL +The +.IR request +or +.IR arg +argument is not valid for this device. +.TP +.BR EIO +Some physical I/O error has occurred. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a STREAMS device that accepts control functions. +.TP +.BR ENXIO +The +.IR request +and +.IR arg +arguments are valid for this device driver, but the service requested +cannot be performed on this particular sub-device. +.TP +.BR ENODEV +The +.IR fildes +argument refers to a valid STREAMS device, but the corresponding device +driver does not support the +\fIioctl\fR() +function. +.P +If a STREAM is connected downstream from a multiplexer, any +\fIioctl\fR() +command except I_UNLINK and I_PUNLINK shall set +.IR errno +to +.BR [EINVAL] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The implementation-defined timeout interval for STREAMS has +historically been 15 seconds. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIioctl\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIclose\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<stropts.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |