stroptions(9s) [sunos man page]
stroptions(9S) Data Structures for Drivers stroptions(9S) NAME
stroptions - options structure for M_SETOPTS message SYNOPSIS
#include <sys/stream.h> #include <sys/stropts.h> #include <sys/ddi.h> #include <sys/sunddi.h> INTERFACE LEVEL
Architecture independent level 1 (DDI/DKI) DESCRIPTION
The M_SETOPTS message contains a stroptions structure and is used to control options in the stream head. STRUCTURE MEMBERS
uint_t so_flags; /* options to set */ short so_readopt; /* read option */ ushort_t so_wroff; /* write offset */ ssize_t so_minpsz; /* minimum read packet size */ ssize_t so_maxpsz; /* maximum read packet size */ size_t so_hiwat; /* read queue high water mark */ size_t so_lowat; /* read queue low water mark */ unsigned char so_band; /* band for water marks */ ushort_t so_erropt; /* error option */ The following are the flags that can be set in the so_flags bit mask in the stroptions structure. Note that multiple flags can be set. SO_READOPT Set read option. SO_WROFF Set write offset. SO_MINPSZ Set minimum packet size SO_MAXPSZ Set maximum packet size. SO_HIWAT Set high water mark. SO_LOWAT Set low water mark. SO_MREADON Set read notification ON. SO_MREADOFF Set read notification OFF. SO_NDELON Old TTY semantics for NDELAY reads and writes. SO_NDELOFFSTREAMS Semantics for NDELAY reads and writes. SO_ISTTY The stream is acting as a terminal. SO_ISNTTY The stream is not acting as a terminal. SO_TOSTOP Stop on background writes to this stream. SO_TONSTOP Do not stop on background writes to this stream. SO_BAND Water marks affect band. SO_ERROPT Set error option. When SO_READOPT is set, the so_readopt field of the stroptions structure can take one of the following values. See read(2). RNORM Read message normal. RMSGD Read message discard. RMSGN Read message, no discard. When SO_BAND is set, so_band determines to which band so_hiwat and so_lowat apply. When SO_ERROPT is set, the so_erropt field of the stroptions structure can take a value that is either none or one of: RERRNORM Persistent read errors; default. RERRNONPERSIST Non-persistent read errors. OR'ed with either none or one of: WERRNORM Persistent write errors; default. WERRNONPERSIST Non-persistent write errors. SEE ALSO
read(2), streamio(7I) STREAMS Programming Guide SunOS 5.10 14 Nov 1996 stroptions(9S)
Check Out this Related Man Page
stream(2) System Calls Manual stream(2) NAME
stream: open(), close(), read(), readv(), write(), writev(), ioctl(), select(), signal() - STREAMS enhancements to standard system calls DESCRIPTION
The and system calls are enhanced to support STREAMS. The new functionality is described below for each system call. Open Enhancements When calling open for a STREAMS device, the oflag parameter can only be constructed from the flag values that are OR-ed with the or flag values. The values of the other flags are not applicable to STREAMS devices and have no effect on them. The values of the flags affect the operations of STREAMS-based device drivers, when the or functions are used. After the stream is open, these flags can be modified by calling (see the fcntl(2) man page). The effects of the flags are device specific. The open of a STREAMS device may fail for one or more of the following STREAMS-specific conditions: A hangup occurred while the function was attempting to open the stream. The system was unable to allocate a stream. The device has not been generated into the system as a STREAMS device. The open routine of one of the modules or drivers in the stream failed. Close Enhancements When all file descriptors associated with a STREAMS device have been closed, the stream is dismantled. If the file descriptor is associ- ated with a stream that is subject to persistent links, the function will succeed immediately, but the stream will remain open. See docu- mentation in streamio(7). Dismantling includes popping any modules on the stream and closing the driver. If flag is set, and there are no signals posted for the stream, the function waits for output to drain on each module's or driver's non-empty write queue. waits for each module or driver for the amount of time set by the (see the streamio(7) man page). The default is 15 seconds per module or driver. If the flag is set, or there are any pending signals, the function does not wait for output to drain and dismantles the stream immediately. If a STREAMS device is closed, and the calling process had previously registered to recieve a signal for events associated with that device (see "Signal Enhancements" below), unregisters the calling process for the events associated with the stream. Read and Readv Enhancements In this section, refers to both and For STREAMS devices, the function operates in accordance with the read mode of the file. STREAMS has three read modes: byte-stream mode, message-nondiscard mode, and message-discard mode. The default is byte-stream mode; however, the user can change this by issuing the call. The user can also test for the current read mode by issuing the call. See the streamio(7) man page for more information about these calls. The function's behavior in each of the read modes of a STREAMS device is as follows: o In byte-stream mode, the function retrieves data from the stream associated with the file descriptor until it has retrieved nbyte bytes, or until there is no more data to be retrieved. o In message-nondiscard mode, the function retrieves data until it reaches a message boundary. If it does not retrieve all of the data in the message, it places the remaining data back on the stream. This data can be retrieved by a subsequent or call. o In message-discard mode, the function retrieves data until it has retrieved nbytes, or until it has reached a message boundary. However, unread data remaining in the message is discarded and is not available for reading by a subsequent or call. When attempting to read a STREAMS device and encountering a zero-byte message: o If the read mode is byte-stream, the function returns the number of bytes of data read before encountering the zero-byte message. If data was read before receiving the zero-byte message, returns the zero-byte message to the stream so it can be processed by a subsequent or call. If no data was read, consumes the message. o If the read mode is message-discard or message-nondiscard, the function returns zero, and then consumes the message. The function reads the data at the front of the stream head read queue. It reads both priority band and normal data. The function processes control messages according to the STREAMS read flags: and The default is for to be set; however, the user can change this by issuing the call. The function's behavior for each read flag is described below: o If is set, a read from a stream can only process data messages. It cannot process any type of control message and fails if such a message is encountered at the stream head. o If is set, processes both data and control messages. The function delivers data in both data and control messages. o If is set, consumes any control messages and retrieves data from data messages only. The following is also true for reads to STREAMS devices. If the flag is clear, and no message is waiting to be read on the stream, the function blocks until a message arrives at the stream head. If the flag is set, and no message is waiting to be read on the stream, the function fails and returns A read from a STREAMS device may fail for one or more of the following STREAMS-specific conditions: No message is waiting to be read on the stream, and the flag is set. A message is waiting to be read, but it is not a data message and the flag is set. The stream is linked to a multiplexor. A read from a STREAMS device also fails if an error message is received at the stream head. In this case, is set to the value returned in the error message. If a hangup occurs on the stream being read, the function continues its operations until the stream read queues are empty. Thereafter, it returns a value of 0 (zero). Write and Writev Enhancements In this section, refers to both and When writing to a STREAMS device, the function sends ordinary, priority band zero, data. Other aspects of the function's behavior are determined by the packet size that the stream will accept. If nbytes is not within the top module's minimum and maximum packet size range, will return Two exceptions exist, however, in which does not return an error. The first exception is if nbytes is too large and either the maximum packet size is infinite or the minimum packet size is less than or equal to zero. The second exception occurs if nbytes is too small and the minimum packet size is less than or equal to zero. With either exception, does not return and transfers the data. The function may send the user's data buffer in multiple messages. The maximum amount of data that sends in one message is the lower value of the top module's maximum packet size and If the maximum packet size is infinite, compares half of the top module's high water mark to instead. If the high water mark is less than or equal to zero, the page size is used. If a zero-length buffer (nbytes is 0) is passed to zero bytes are sent to the stream and zero bytes are returned. The following is also true for writes to STREAMS devices. If the flag is clear, and the stream cannot accept data (the stream head write queue is full due to flow control conditions), the function blocks until data can be accepted. If the flag is set, and the stream cannot accept data, the function fails, and returns If the flag is set, and the stream cannot accept data, but part of the buffer has already been written, the function terminates and returns the number of bytes written. A write to a STREAMS device may fail for one or more of the following STREAMS-specific conditions: The flag is set, and the stream cannot accept data because it is flow controlled. The function attempts to write to a stream that is linked below a multiplexor. A hangup occurs on a stream while the function is writing to the stream. The nbytes parameter is not within the allowable range. The system call will also fail if an error message has been received at the stream head of the stream to which the function is attempting to write. In this case, the function returns with set to the value included in the error message. Ioctl Enhancements Refer to the streamio(7) man page for a description of STREAMS functionality. Select Enhancements The system call checks the status of STREAMS devices. does not provide as much information for STREAMS devices as A program calls so that it can wait for events on both STREAMS and non-STREAMS devices. If returns an event for a STREAMS device, the program can call to get more information. Refer to the poll(2) man page for more information about returns a read event if a or event exists on the stream. In other words, returns a read event if a normal or priority band message is waiting to be read, if a read error exists at the stream head, if a write error exists at the stream head, if the stream is linked under a multiplexor, or if a hang-up has occurred. returns a write event if a or event exists on the stream. This means that returns a write event if normal data can be written without blocking because of flow control, a read error exists at the stream head, a write error exists at the stream head, or the stream is linked under a multiplexor. returns an exception event if a event exists on the stream. More specifically, returns an exception event if a high-priority message is waiting to be read. Signal Enhancements A new signal, has been added for STREAMS. Processes register to receive a signal for events that occur on a STREAMS device (see the sig- nal(2) man page and in the streamio(7) man page). The default action is to ignore the signal, not to terminate the process. SEE ALSO
close(2), fcntl(2), getmsg(2), open(2), poll(2), putmsg(2), read(2), signal(2), select(2), write(2), streamio(7), and stream(2)