B.5 Streams User-Level Interface
STREAMS does not provide a Transport Layer Interface (TLI) library. User-mode programs, such as routing or plumbing daemons, can access STREAMS drivers and modules directly with the following functions listed below, which block synchronously.
·getmsg
·putmsg
·poll
·s_ioctl
·s_open
These functions operate only on handles to STREAMS drivers. To close a handle, call the Win32 CloseHandle API. These functions are defined in Further Readings on Streams, Reference 1. Windows NT adds the s_ prefix to the last two due to a name conflict with the C runtime functions of the same name.
These functions are not recommended for general application access to transports. The Windows Sockets interface is more appropriate for general use.
INT
getmsg(
IN HANDLE fd,
IN OUT struct strbuf *ctrlptr OPTIONAL,
IN OUT struct strbuf *dataptr OPTIONAL,
IN OUT int *flagsp
);
Parameters
fd
The stream handle.
ctrlptr
Pointer to the control portion of the STREAMS message.
dataptr
Pointer to the data portion of the STREAMS message.
flagsp
Pointer to the returned flags argument, which may be RS_HIPRI.
INT
putmsg(
IN HANDLE fd,
IN struct strbuf *ctrlptr OPTIONAL,
IN struct strbuf *dataptr OPTIONAL,
IN int flags
);
Parameters
fd
The stream handle.
ctrlptr
Pointer to the control portion of the STREAMS message.
dataptr
Pointer to the data portion of the STREAMS message.
flags
0 or RS_HIPRI.
INT
poll(
IN OUT struct pollfd *fds,
IN unsigned int nfds,
IN int timeout
);
Parameters
fds
Pointer to an array of poll structures
nfds
The number of poll strucutures contained in the array.
timeout
0, INFTIM (-1), or timeout value in milliseconds.
struct pollfd {
HANDLE fd; // file handle to poll
short events; // events of interest on fd
short revents; // events that occurred on fd
};
INT
s_ioctl(
IN HANDLE fd,
IN int cmd,
IN OUT void *arg OPTIONAL
);
Parameters
fd
The stream handle.
cmd
The IOCTL_xxx
arg
Command-dependant argument.
HANDLE
s_open(
IN CHAR *path,
IN INT oflag,
IN INT ignored
);
Parameters
path
Defines the path \Device\Streams\name, where name specifies the name of the driver.
oflag
Defines the open flag; must be 0.
ignored
Ignored.
STREAMS does not provide the stream head API functions listed below. These functions apply predominantly to named streams and pseudo-TTYs.
fattach
getpmsg
ptsname
fcntl
grantpt
putpmsg
fdetach
isastream
unlockpt
The s_poll function allows the caller to query several streams for information. For STREAMS, the flags listed below can be used to specify the events of interest to poll:
·POLLIN
·POLLOUT
·POLLMSG (1)
·POLLPRI
·POLLERR
·POLLNVAL
(1) New in UNIX SVR4
STREAMS does not support the following flags:
·POLLHUP
·POLLRDNORM
·POLLRDBAND
·POLLWRNORM
·POLLWRBAND