[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[s-x86] Re: Solaris 8 /dev/poll?
On Wed, 2 Feb 2000, Dan Kegel wrote:
> Hi,
> can someone email me the man pages or doc for Solaris 8's /dev/poll
> interface? I'd like to post about it on my high performance
> web server info page.
>
>
Here you go Dan. By the way I notice you discuss Linux io benchmarks
quite a bit on your webpages comparing them to NT but make no note
of Solaris x86 io compared to either Linux or NT. I wish there
was some specweb 96 numbers to compare linux too spec 99 is not
a pure io measurement and I didn't see any Linux spec96 numbers
to compare it too. Volanomarks should be a good one to compare
on Solaris 8 to the recent Linux 2.3.x kernels with say 4 cpu's.
The other fast messaging net information systems would be
nntp messaging (haven't seen a benchmark for this but highwind
keeps live stats) see
http://nntp.news.abs.net/cyclone/stats/index.html
gives an idea what a dual 300mhz PII Solaris 2.7 box will give
in articles per/sec. Proxy benchmarks, haven't tried Vixes yet.
And of coarse your new ftp benchmark. [maybe a ldap/email] benchmark.
I enjoy reading your webpages and hope you give Solaris 8 a chance
in some of your pages.
Regards,
---Bob
Here's my notes on the new poll API
New API for polling on file descriptors
This API supplements not replaces poll(2)
Allows fast polling of large numbers of descriptors in the thousands
Useful when polling on the same set of desriptors over and over,
large sets.
You access the driver via open(2), write(2) and ioctl(2) on /dev/poll
poll(7d) has the examples.
Pertinent manpages:
Devices poll(7d)
NAME
poll - driver for fast poll on many file descriptors
SYNOPSIS
#include <sys/devpoll.h>
PARAMETERS
fd Open file descriptor that refers to the /dev/poll
driver.
path /dev/poll
buf Array of pollfd structures.
bufsize
Size of buf in bytes.
arg Pointer to pollcall structure.
pfd Pointer to pollfd structure.
DESCRIPTION
The /dev/poll driver is a special driver that lets user
monitor multiple sets of polled file descriptors. By using
the /dev/poll driver, users can poll large number of file
descriptors very efficiently. Access to /dev/poll driver is
provided through open(2), write(2), and
ioctl(2) system calls.
Writing an array of pollfd struct to the /dev/poll driver
has the effect of adding these file descriptors to the mon-
itored poll file descriptor set represented by the fd.
Users wishing to monitor multiple file descriptor sets
should open the /dev/poll driver multiple times. Each fd
corresponds to one set. For each pollfd struct entry
(defined in sys/poll.h):
struct pollfd {
int fd;
short events;
short revents;
}
The fd field specifies the file descriptor being polled.
The events field indicates the interested poll events on
the file descriptor. If a pollfd array contains multiple
pollfd entries with same fd field, the "events" field in
each pollfd entry is OR'ed. A special POLLREMOVE event in
the events field of the pollfd structure will remove the
fd from the monitored set. The revents field is not used.
Write returns the number of bytes written successfully or
SunOS 5.8 Last change: 31 Jan 1999 1
Devices poll(7d)
-1 when write fails.
The DP_POLL ioctl is used to retrieve returned poll events
occured on the polled file descriptors in the monitored set
represented by fd. arg is a pointer to the devpoll struc-
tures which are defined as follows:
struct dvpoll {
struct pollfd* dp_fds;
int dp_nfds;
int dp_timeout;
}
The dp_fds points to a buffer which is used to hold an
array of returned pollfd structures. The dp_nfds field
specifies the size of the buffer in terms of the number of
pollfd entries it contains; dp_nfds also indicates the max-
imum number of file descriptors on which a user is
interested in getting poll information. If there is no
interested events on any of the polled file descriptors,
the DP_POLL ioctl call will wait dp_timeout miliseconds
before returning. If dp_timeout is 0, the ioctl call
returns immediately; if dp_timeout is -1, the call blocks
until an interested poll events is available or the call
is interrupted. Upon return, if the ioctl call has failed,
-1 is returned. The memory content pointed by dp_fds is not
modified. A return value 0 means the ioctl is timed out. In
this case, the memory content pointed by dp_fds is not
modified. If the call is successful, it returns the number
of valid pollfd entries in the array pointed by dp_fds;
the contents of the rest of the buffer is undefined. For
each valid pollfd entry, the fd field indicates the file
desciptor on which the polled events happened. The events
field is the user specified poll events. The revents field
contains the events occurred. -1 is returned if the call
fails.
DP_ISPOLLED ioctl allows user to query if a file descriptor
is already in the monitored set represented by fd. The fd
field of the pollfd structure indicates the file descrip-
tor of interest. The DP_ISPOLLED ioctl returns 1 if the
file descriptor is in the set. The events field contains
the currently polled events. The revents field contains
0. The ioctl returns 0 if the file descriptor is not in the
set. The pollfd structure pointed by pfd is not modified.
The ioctl returns a -1 if the call fails.
EXAMPLES
Example 1: The following example shows how /dev/poll may be
used.
SunOS 5.8 Last change: 31 Jan 1999 2
Devices poll(7d)
{
...
/*
* open the driver
*/
if ((wfd = open("/dev/poll", O_RDWR)) < 0) {
exit(-1);
}
pollfd = (struct pollfd* )malloc(sizeof(struct pollfd) * MAXBUF);
if (pollfd == NULL) {
close(wfd);
exit(-1);
}
/*
* initialize buffer
*/
for (i = 0; i < MAXBUF; i++) {
pollfd[i].fd = fds[i];
pollfd[i].events = POLLIN;
pollfd[i].revents = 0;
}
if (write(wfd, &pollfd[0], sizeof(struct pollfd) * MAXBUF) !=
sizeof(struct pollfd) * MAXBUF) {
perror("failed to write all pollfds");
close (wfd);
free(pollfd);
exit(-1);
}
/*
* read from the devpoll driver
*/
dopoll.dp_timeout = -1;
dopoll.dp_nfds = MAXBUF;
dopoll.dp_fds = pollfd;
result = ioctl(wfd, DP_POLL, &dopoll);
if (result < 0) {
perror("/dev/poll ioctl DP_POLL failed");
close (wfd);
free(pollfd);
exit(-1);
}
for (i = 0; i < result; i++) {
read(dopoll.dp_fds[i].fd, rbuf, STRLEN);
}
...
}
ERRORS
EACCES
A process does not have permission to access the con-
tent cached in /dev/poll.
SunOS 5.8 Last change: 31 Jan 1999 3
Devices poll(7d)
EINTR A signal was caught during the execution of the
ioctl(2) function.
EFAULT
The request argument requires a data transfer to or
from a buffer pointed to by arg, but arg points to an
illegal address.
EINVAL
The request or arg parameter is not valid for this
device.
ENXIO The O_NONBLICK flag is set, the named file is a FIFO,
the O_WRONGLY flag is set, and no process has the file
open for reading; or the named file is a character
special or block special file and the device associ-
ated with this special file does not exist.
ATTRIBUTES
See attributes(5) for a description of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Architecture | SPARC, Intel |
| Availability | SUNWcarx.u, SUNWcsxu (64|
| | bit Solaris) |
| | SUNWcsr, SUNWcsu (32-bit|
| | Solaris on Intel) |
| | SUNWhea (header files) |
| Interface Stability | Evolving |
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
open(2), poll(2), write(2), attributes(5)
NOTES
The /dev/poll API is particularly beneficial to applications
which poll a large number of file descriptors and poll
them repeatedly. Applications will exhibit the best perfor-
mance gain if the polled file descriptor list rarely change.
When using the /dev/poll driver, user should pay attention
to remove a closed file descriptor from a monitored poll
set. Failure to do so may result in a POLLNVAL revents
being returned for the closed file descriptor. When a file
descriptor is closed but not removed from the monitored set,
and if the file descriptor is reused in subsequent open of
a possibly different device, user will be polling the device
associated with the reused file descriptor. In a
SunOS 5.8 Last change: 31 Jan 1999 4
Devices poll(7d)
multithreaded application, careful coordination among
threads doing close and DP_POLL ioctl is recommended for
consistent results.
The /dev/poll driver caches a list of polled file descrip-
tors, which are specific to a process. Therefore, the
/dev/poll file descriptor of a process will be inherited by
its child process, just like any other file descriptors. But
the child process will have very limited access through this
inherited /dev/poll file descriptor. Any attempt to write or
do ioctl by the child process will result in an EACCES
error. The child process should close the inherited
/dev/poll file descriptor and open its own if desired.
The /dev/poll driver does not yet support polling. Polling
on a /dev/poll file descriptor will result in POLLERR
being returned in the revents field of pollfd structure.
SunOS 5.8 Last change: 31 Jan 1999 5
System Calls open(2)
NAME
open - open a file
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
int open(const char *path, int oflag, /* mode_t mode */...);
DESCRIPTION
The open() function establishes the connection between a
file and a file descriptor. It creates an open file descrip-
tion that refers to a file and a file descriptor that refers
to that open file description. The file descriptor is used
by other I/O functions to refer to that file. The path
argument points to a pathname naming the file.
The open() function returns a file descriptor for the named
file that is the lowest file descriptor not currently open
for that process. The open file description is new, and
therefore the file descriptor does not share it with any
other process in the system. The FD_CLOEXEC file descriptor
flag associated with the new file descriptor is cleared.
The file offset used to mark the current position within the
file is set to the beginning of the file.
The file status flags and file access modes of the open file
description are set according to the value of oflag. The
mode argument is used only when O_CREAT is specified (see
below.)
Values for oflag are constructed by a bitwise-inclusive-OR
of flags from the following list, defined in <fcntl.h>.
Applications must specify exactly one of the first three
values (file access modes) below in the value of oflag:
O_RDONLY
Open for reading only.
O_WRONLY
Open for writing only.
O_RDWR
Open for reading and writing. The result is undefined
if this flag is applied to a FIFO.
Any combination of the following may be used:
O_APPEND
If set, the file offset is set to the end of the file
SunOS 5.8 Last change: 16 Apr 1998 1
System Calls open(2)
prior to each write.
O_CREAT
Create the file if it does not exist. This flag
requires that the mode argument be specified.
If the file exists, this flag has no effect except as
noted under O_EXCL below. Otherwise, the file is
created with the user ID of the file set to the effec-
tive user ID of the process. The group ID of the file
is set to the effective group IDs of the process, or
if the S_ISGID bit is set in the directory in which
the file is being created, the file's group ID is set
to the group ID of its parent directory. If the group
ID of the new file does not match the effective group
ID or one of the supplementary groups IDs, the S_ISGID
bit is cleared. The access permission bits (see
<sys/stat.h>) of the file mode are set to the value of
mode, modified as follows (see creat(2)): a bitwise-
AND is performed on the file-mode bits and the
corresponding bits in the complement of the process's
file mode creation mask. Thus, all bits set in the
process's file mode creation mask (see umask(2)) are
correspondingly cleared in the file's permission mask.
The "save text image after execution bit" of the mode
is cleared (see chmod(2)). O_SYNC Write I/O operations
on the file descriptor complete as defined by syn-
chronized I/O file integrity completion (see
fcntl(3HEAD) definition of O_SYNC.) When bits other
than the file permission bits are set, the effect is
unspecified. The mode argument does not affect whether
the file is open for reading, writing or for both.
O_DSYNC
Write I/O operations on the file descriptor complete
as defined by synchronized I/O data integrity comple-
tion.
O_EXCL
If O_CREAT and O_EXCL are set, open() fails if the
file exists. The check for the existence of the file
and the creation of the file if it does not exist is
atomic with respect to other processes executing
open() naming the same filename in the same directory
with O_EXCL and O_CREAT set. If O_CREAT is not set,
the effect is undefined.
O_LARGEFILE
If set, the offset maximum in the open file descrip-
tion is the largest value that can be represented
correctly in an object of type off64_t.
SunOS 5.8 Last change: 16 Apr 1998 2
System Calls open(2)
O_NOCTTY
If set and path identifies a terminal device, open()
does not cause the terminal device to become the con-
trolling terminal for the process.
O_NONBLOCK or O_NDELAY
These flags may affect subsequent reads and writes
(see read(2) and write(2)). If both O_NDELAY and
O_NONBLOCK are set, O_NONBLOCK takes precedence.
When opening a FIFO with O_RDONLY or O_WRONLY set:
If O_NONBLOCK or O_NDELAY is set:
An open() for reading only returns without delay.
An open() for writing only returns an error if no
process currently has the file open for reading.
If O_NONBLOCK and O_NDELAY are clear:
An open() for reading only blocks until a process
opens the file for writing. An open() for writing
only blocks until a process opens the file for read-
ing.
After both ends of a FIFO have been opened, there is
no guarantee that further calls to open() O_RDONLY
(O_WRONLY) will synchronize with later calls to open()
O_WRONLY (O_RDONLY) until both ends of the FIFO have
been closed by all readers and writers. Any data
written into a FIFO will be lost if both ends of the
FIFO are closed before the data is read.
When opening a block special or character special file
that supports non-blocking opens:
If O_NONBLOCK or O_NDELAY is set:
The open() function returns without blocking for the
device to be ready or available. Subsequent behavior
of the device is device-specific.
If O_NONBLOCK and O_NDELAY are clear:
The open() function blocks until the device is ready
or available before returning.
Otherwise, the behavior of O_NONBLOCK and O_NDELAY is
unspecified.
O_RSYNC
Read I/O operations on the file descriptor complete at
SunOS 5.8 Last change: 16 Apr 1998 3
System Calls open(2)
the same level of integrity as specified by the
O_DSYNC and O_SYNC flags. If both O_DSYNC and O_RSYNC
are set in oflag, all I/O operations on the file
descriptor complete as defined by synchronized I/O
data integrity completion. If both O_SYNC and O_RSYNC
are set in oflag, all I/O operations on the file
descriptor complete as defined by synchronized I/O
file integrity completion.
O_SYNC
If O_SYNC is set on a regular file, writes to that
file cause the process to block until the data is
delivered to the underlying hardware.
O_TRUNC
If the file exists and is a regular file, and the file
is successfully opened O_RDWR or O_WRONLY, its length
is truncated to 0 and the mode and owner are
unchanged. It has no effect on FIFO special files or
terminal device files. Its effect on other file types
is implementation-dependent. The result of using
O_TRUNC with O_RDONLY is undefined.
If O_CREAT is set and the file did not previously exist,
upon successful completion, open() marks for update the
st_atime, st_ctime, and st_mtime fields of the file and the
st_ctime and st_mtime fields of the parent directory.
If O_TRUNC is set and the file did previously exist, upon
successful completion, open() marks for update the st_ctime
and st_mtime fields of the file.
If path refers to a STREAMS file, oflag may be constructed
from O_NONBLOCK or O_NODELAY OR-ed with either O_RDONLY,
O_WRONLY, or O_RDWR. Other flag values are not applicable to
STREAMS devices and have no effect on them. The values
O_NONBLOCK and O_NODELAY affect the operation of STREAMS
drivers and certain functions (see read(2), getmsg(2),
putmsg(2), and write(2)) applied to file descriptors associ-
ated with STREAMS files. For STREAMS drivers, the implemen-
tation of O_NONBLOCK and O_NODELAY is device-specific.
When open() is invoked to open a named stream, and the
connld module (see connld(7M)) has been pushed on the pipe,
open() blocks until the server process has issued an
I_RECVFD ioctl() (see streamio(7I)) to receive the file
descriptor.
If path names the master side of a pseudo-terminal device,
then it is unspecified whether open() locks the slave side
so that it cannot be opened. Portable applications must
call unlockpt(3C) before opening the slave side.
SunOS 5.8 Last change: 16 Apr 1998 4
System Calls open(2)
If path is a symbolic link and O_CREAT and O_EXCL are set,
the link is not followed.
Certain flag values can be set following open() as described
in fcntl(2).
The largest value that can be represented correctly in an
object of type off_t is established as the offset maximum in
the open file description.
RETURN VALUES
Upon successful completion, the open() function opens the
file and return a non-negative integer representing the
lowest numbered unused file descriptor. Otherwise, -1 is
returned, errno is set to indicate the error, and no files
are created or modified.
ERRORS
The open() function will fail if:
EACCES
Search permission is denied on a component of the path
prefix, or the file exists and the permissions speci-
fied by oflag are denied, or the file does not exist
and write permission is denied for the parent direc-
tory of the file to be created, or O_TRUNC is speci-
fied and write permission is denied.
EDQUOT
The file does not exist, O_CREAT is specified, and
either the directory where the new file entry is being
placed cannot be extended because the user's quota of
disk blocks on that file system has been exhausted, or
the user's quota of inodes on the file system where
the file is being created has been exhausted.
EEXIST
The O_CREAT and O_EXCL flags are set, and the named
file exists.
EINTR A signal was caught during open().
EFAULT
The path argument points to an illegal address.
EIO The path argument names a STREAMS file and a hangup or
error occurred during the open().
EISDIR
The named file is a directory and oflag includes
O_WRONLY or O_RDWR.
SunOS 5.8 Last change: 16 Apr 1998 5
System Calls open(2)
ELOOP Too many symbolic links were encountered in resolving
path.
EMFILE
OPEN_MAX file descriptors are currently open in the
calling process.
EMULTIHOP
Components of path require hopping to multiple remote
machines and the file system does not allow it.
ENAMETOOLONG
The length of the path argument exceeds PATH_MAX or a
pathname component is longer than NAME_MAX.
ENFILE
The maximum allowable number of files is currently
open in the system.
ENOENT
The O_CREAT flag is not set and the named file does
not exist; or the O_CREAT flash is set and either the
path prefix does not exist or the path argument points
to an empty string.
ENOLINK
The path argument points to a remote machine, and the
link to that machine is no longer active.
ENOSR The path argument names a STREAMS-based file and the
system is unable to allocate a STREAM.
ENOSPC
The directory or file system that would contain the
new file cannot be expanded, the file does not exist,
and O_CREAT is specified.
ENOTDIR
A component of the path prefix is not a directory.
ENXIO The O_NONBLOCK flag is set, the named file is a FIFO,
the O_WRONLY flag is set, and no process has the file
open for reading; or the named file is a character
special or block special file and the device associ-
ated with this special file does not exist.
EOPNOTSUPP
An attempt was made to open a path that corresponds to
a AF_UNIX socket.
EOVERFLOW
The named file is a regular file and either
SunOS 5.8 Last change: 16 Apr 1998 6
System Calls open(2)
O_LARGEFILE is not set and the size of the file cannot
be represented correctly in an object of type off_t or
O_LARGEFILE is set and the size of the file cannot be
represented correctly in an object of type off64_t.
EROFS The named file resides on a read-only file system and
either O_WRONLY, O_RDWR, O_CREAT (if file does not
exist), or O_TRUNC is set in the oflag argument.
The open() function may fail if:
EAGAIN
The path argument names the slave side of a pseudo-
terminal device that is locked.
EINVAL
The value of the oflag argument is not valid.
ENAMETOOLONG
Pathname resolution of a symbolic link produced an
intermediate result whose length exceeds PATH_MAX.
ENOMEM
The path argument names a STREAMS file and the system
is unable to allocate resources.
ETXTBSY
The file is a pure procedure (shared text) file that
is being executed and oflag is O_WRONLY or O_RDWR.
USAGE
The open() function has a transitional interface for 64-bit
file offsets. See lf64(5). Note that using open64() is
equivalent to using open() with O_LARGEFILE set in oflag.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | Async-Signal-Safe |
|_____________________________|_____________________________|
SEE ALSO
intro(3), chmod(2), close(2), creat(2), dup(2), exec(2),
fcntl(2), getmsg(2), getrlimit(2), lseek(2), putmsg(2),
read(2), stat(2), umask(2), write(2), unlockpt(3C), attri-
butes(5), fcntl(3HEAD), lf64(5), stat(3HEAD), connld(7M),
streamio(7I)
SunOS 5.8 Last change: 16 Apr 1998 7
System Calls open(2)
NOTES
Hierarchical Storage Management (HSM) file systems can some-
times cause long delays when opening a file, since HSM files
must be recalled from secondary storage.
SunOS 5.8 Last change: 16 Apr 1998 8
System Calls write(2)
NAME
write, pwrite, writev - write on a file
SYNOPSIS
#include <unistd.h>
ssize_t write(int fildes, const void *buf, size_t nbyte);
ssize_t pwrite(int fildes, const void *buf, size_t nbyte,
off_t offset);
#include <sys/uio.h>
ssize_t writev(int fildes, const struct iovec *iov, int
iovcnt);
DESCRIPTION
The write() function attempts to write nbyte bytes from the
buffer pointed to by buf to the file associated with the
open file descriptor, fildes.
If nbyte is 0, write() will return 0 and have no other
results if the file is a regular file; otherwise, the
results are unspecified.
On a regular file or other file capable of seeking, the
actual writing of data proceeds from the position in the
file indicated by the file offset associated with fildes.
Before successful return from write(), the file offset is
incremented by the number of bytes actually written. On a
regular file, if this incremented file offset is greater
than the length of the file, the length of the file will be
set to this file offset.
If the O_SYNC flag of the file status flags is set and
fildes refers to a regular file, a successful write() does
not return until the data is delivered to the underlying
hardware.
If fildes refers to a socket, write() is equivalent to
send(3SOCKET) with no flags set.
On a file not capable of seeking, writing always takes place
starting at the current position. The value of a file
offset associated with such a device is undefined.
If the O_APPEND flag of the file status flags is set, the
file offset will be set to the end of the file prior to each
write and no intervening file modification operation will
occur between changing the file offset and the write opera-
tion.
SunOS 5.8 Last change: 19 Mar 1999 1
System Calls write(2)
For regular files, no data transfer will occur past the
offset maximum established in the open file description with
fildes.
A write() to a regular file is blocked if mandatory
file/record locking is set (see chmod(2)), and there is a
record lock owned by another process on the segment of the
file to be written:
o If O_NDELAY or O_NONBLOCK is set, write() returns -1
and sets errno to EAGAIN.
o If O_NDELAY and O_NONBLOCK are clear, write() sleeps
until all blocking locks are removed or the write() is
terminated by a signal.
If a write() requests that more bytes be written than there
is room for-for example, if the write would exceed the pro-
cess file size limit (see getrlimit(2) and ulimit(2)), the
system file size limit, or the free space on the device-only
as many bytes as there is room for will be written. For
example, suppose there is space for 20 bytes more in a file
before reaching a limit. A write() of 512-bytes returns 20.
The next write() of a non-zero number of bytes gives a
failure return (except as noted for pipes and FIFO below).
If write() is interrupted by a signal before it writes any
data, it will return -1 with errno set to EINTR.
If write() is interrupted by a signal after it successfully
writes some data, it will return the number of bytes writ-
ten.
If the value of nbyte is greater than SSIZE_MAX, the result
is implementation-dependent.
After a write() to a regular file has successfully returned:
o Any successful read(2) from each byte position in the
file that was modified by that write will return the
data specified by the write() for that position until
such byte positions are again modified.
o Any subsequent successful write() to the same byte
position in the file will overwrite that file data.
Write requests to a pipe or FIFO are handled the same as a
regular file with the following exceptions:
o There is no file offset associated with a pipe, hence
each write request appends to the end of the pipe.
SunOS 5.8 Last change: 19 Mar 1999 2
System Calls write(2)
o Write requests of {PIPE_BUF} bytes or less are
guaranteed not to be interleaved with data from other
processes doing writes on the same pipe. Writes of
greater than {PIPE_BUF} bytes may have data inter-
leaved, on arbitrary boundaries, with writes by other
processes, whether or not the O_NONBLOCK or O_NDELAY
flags are set.
o If O_NONBLOCK and O_NDELAY are clear, a write request
may cause the process to block, but on normal comple-
tion it returns nbyte.
o If O_NONBLOCK and O_NDELAY are set, write() does not
block the process. If a write() request for PIPE_BUF
or fewer bytes succeeds completely write() returns
nbyte. Otherwise, if O_NONBLOCK is set, it returns -1
and sets errno to EAGAIN or if O_NDELAY is set, it
returns 0. A write() request for greater than
{PIPE_BUF} bytes transfers what it can and returns
the number of bytes written or it transfers no data
and, if O_NONBLOCK is set, returns -1 with errno set
to EAGAIN or if O_NDELAY is set, it returns 0.
Finally, if a request is greater than PIPE_BUF bytes
and all data previously written to the pipe has been
read, write() transfers at least PIPE_BUF bytes.
When attempting to write to a file descriptor (other than a
pipe, a FIFO, a socket, or a STREAM) that supports nonblock-
ing writes and cannot accept the data immediately:
o If O_NONBLOCK and O_NDELAY are clear, write() blocks
until the data can be accepted.
o If O_NONBLOCK or O_NDELAY is set, write() does not
block the process. If some data can be written without
blocking the process, write() writes what it can and
returns the number of bytes written. Otherwise, if
O_NONBLOCK is set, it returns -1 and sets errno to
EAGAIN or if O_NDELAY is set, it returns 0.
Upon successful completion, where nbyte is greater than 0,
write() will mark for update the st_ctime and st_mtime
fields of the file, and if the file is a regular file, the
S_ISUID and S_ISGID bits of the file mode may be cleared.
For STREAMS files (see intro(3) and streamio(7I)), the
operation of write() is determined by the values of the
minimum and maximum nbyte range ("packet size") accepted by
the STREAM. These values are contained in the topmost STREAM
module, and can not be set or tested from user level. If
nbyte falls within the packet size range, nbyte bytes are
written. If nbyte does not fall within the range and the
SunOS 5.8 Last change: 19 Mar 1999 3
System Calls write(2)
minimum packet size value is zero, write() breaks the
buffer into maximum packet size segments prior to sending
the data downstream (the last segment may be smaller than
the maximum packet size). If nbyte does not fall within
the range and the minimum value is non-zero, write() fails
and sets errno to ERANGE. Writing a zero-length buffer
(nbyte is zero) to a STREAMS device sends a zero length
message with zero returned. However, writing a zero-length
buffer to a pipe or FIFO sends no message
and zero is returned. The user program may issue the
I_SWROPT ioctl(2) to enable zero-length messages to be sent
across the pipe or FIFO (see streamio(7I)).
When writing to a STREAM, data messages are created with a
priority band of zero. When writing to a socket or to a
STREAM that is not a pipe or a FIFO:
o If O_NDELAY and O_NONBLOCK are not set, and the STREAM
cannot accept data (the STREAM write queue is full due
to internal flow control conditions), write() blocks
until data can be accepted.
o If O_NDELAY or O_NONBLOCK is set and the STREAM cannot
accept data, write() returns -1 and sets errno to
EAGAIN.
o If O_NDELAY or O_NONBLOCK is set and part of the
buffer has already been written when a condition
occurs in which the STREAM cannot accept additional
data, write() terminates and returns the number of
bytes written.
The write() and writev() functions will fail if the STREAM
head had processed an asynchronous error before the call.
In this case, the value of errno does not reflect the result
of write() or writev() but reflects the prior error.
pwrite()
The pwrite() function performs the same action as write(),
except that it writes into a given position without changing
the file pointer. The first three arguments to pwrite() are
the same as write() with the addition of a fourth argument
offset for the desired position inside the file.
writev()
The writev() function performs the same action as write(),
but gathers the output data from the iovcnt buffers speci-
fied by the members of the iov array: iov[0], iov[1], ...,
iov[iovcnt-1]. The iovcnt buffer is valid if greater than 0
and less than or equal to {IOV_MAX}. See intro(3) for a
definition of {IOV_MAX}.
SunOS 5.8 Last change: 19 Mar 1999 4
System Calls write(2)
The iovec structure contains the following members:
caddr_t iov_base;
int iov_len;
Each iovec entry specifies the base address and length of an
area in memory from which data should be written. The wri-
tev() function always writes all data from an area before
proceeding to the next.
If fildes refers to a regular file and all of the iov_len
members in the array pointed to by iov are 0, writev() will
return 0 and have no other effect. For other file types,
the behavior is unspecified.
If the sum of the iov_len values is greater than SSIZE_MAX,
the operation fails and no data is transferred.
RETURN VALUES
Upon successful completion, write() returns the number of
bytes actually written to the file associated with fildes.
This number is never greater than nbyte. Otherwise, -1 is
returned, the file-pointer remains unchanged, and errno is
set to indicate the error.
Upon successful completion, writev() returns the number of
bytes actually written. Otherwise, it returns -1, the
file-pointer remains unchanged, and errno is set to indicate
an error.
ERRORS
The write(), pwrite(), and writev() functions will fail if:
EAGAIN
Mandatory file/record locking is set, O_NDELAY or
O_NONBLOCK is set, and there is a blocking record
lock; an attempt is made to write to a STREAM that can
not accept data with the O_NDELAY or O_NONBLOCK flag
set; or a write to a pipe or FIFO of PIPE_BUF bytes or
less is requested and less than nbytes of free space
is available.
EBADF The fildes argument is not a valid file descriptor
open for writing.
EDEADLK
The write was going to go to sleep and cause a
deadlock situation to occur.
EDQUOT
The user's quota of disk blocks on the file system
containing the file has been exhausted.
SunOS 5.8 Last change: 19 Mar 1999 5
System Calls write(2)
EFAULT
The buf argument points to an illegal address.
EFBIG An attempt is made to write a file that exceeds the
process's file size limit or the maximum file size
(see getrlimit(2) and ulimit(2)).
EFBIG The file is a regular file, nbyte is greater than 0,
and the starting position is greater than or equal to
the offset maximum established in the file description
associated with fildes.
EINTR A signal was caught during the write operation and no
data was transferred.
EIO The process is in the background and is attempting to
write to its controlling terminal whose TOSTOP flag is
set, or the process is neither ignoring nor blocking
SIGTTOU signals and the process group of the process
is orphaned.
ENOLCK
Enforced record locking was enabled and {LOCK_MAX}
regions are already locked in the system, or the sys-
tem record lock table was full and the write could
not go to sleep until the blocking record lock was
removed.
ENOLINK
The fildes argument is on a remote machine and the
link to that machine is no longer active.
ENOSPC
During a write to an ordinary file, there is no free
space left on the device.
ENOSR An attempt is made to write to a STREAMS with insuffi-
cient STREAMS memory resources available in the sys-
tem.
ENXIO A hangup occurred on the STREAM being written to.
EPIPE An attempt is made to write to a pipe or a FIFO that
is not open for reading by any process, or that has
only one end open (or to a file descriptor created by
socket(3SOCKET), using type SOCK_STREAM that is no
longer connected to a peer endpoint). A SIGPIPE signal
will also be sent to the process. The process dies
unless special provisions were taken to catch or
ignore the signal.
ERANGE
SunOS 5.8 Last change: 19 Mar 1999 6
System Calls write(2)
The transfer request size was outside the range sup-
ported by the STREAMS file associated with fildes.
The pwrite() function fails and the file pointer remains
unchanged if:
ESPIPE
The fildes argument is associated with a pipe or FIFO.
The writev() function will fail if:
EINVAL
The sum of the iov_len values in the iov array would
overflow an ssize_t.
The write() and writev() functions may fail if:
EINVAL
The STREAM or multiplexer referenced by fildes is
linked (directly or indirectly) downstream from a mul-
tiplexer.
ENXIO A request was made of a non-existent device, or the
request was outside the capabilities of the device.
ENXIO A hangup occurred on the STREAM being written to.
A write to a STREAMS file may fail if an error message has
been received at the STREAM head. In this case, errno is
set to the value included in the error message.
The writev() function may fail if:
EINVAL
The iovcnt argument was less than or equal to 0 or
greater than {IOV_MAX}; one of the iov_len values in
the iov array was negative; or the sum of the iov_len
values in the iov array overflowed an int.
USAGE
The pwrite() function has a transitional interface for 64-
bit file offsets. See lf64(5).
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.8 Last change: 19 Mar 1999 7
System Calls write(2)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | write() is Async-Signal-Safe|
|_____________________________|_____________________________|
SEE ALSO
Intro(3), chmod(2), creat(2), dup(2), fcntl(2),
getrlimit(2), ioctl(2), lseek(2), open(2), pipe(2),
ulimit(2), send(3SOCKET), socket(3SOCKET), attributes(5),
lf64(5), streamio(7I)
SunOS 5.8 Last change: 19 Mar 1999 8
System Calls ioctl(2)
NAME
ioctl - control device
SYNOPSIS
#include <unistd.h>
#include <stropts.h>
int ioctl(int fildes, int request, /* arg */ ...);
DESCRIPTION
The ioctl() function performs a variety of control functions
on devices and STREAMS. For non-STREAMS files, the functions
performed by this call are device-specific control func-
tions.
The request argument and an optional third argument with
varying type are passed to the file designated by fildes and
are interpreted by the device driver.
For STREAMS files, specific functions are performed by the
ioctl() function as described in streamio(7I).
The fildes argument is an open file descriptor that refers
to a device. The request argument selects the control func-
tion to be performed and depends on the device being
addressed. The arg argument represents a third argument
that has additional information that is needed by this
specific device to perform the requested function. The data
type of arg depends upon the particular control request, but
it is either an int or a pointer to a device-specific data
structure.
In addition to device-specific and STREAMS functions, gen-
eric functions are provided by more than one device driver
(for example, the general terminal interface.) See
termio(7I)).
RETURN VALUES
Upon successful completion, the value returned depends upon
the device control function, but must be a non-negative
integer. Otherwise, -1 is returned and errno is set to
indicate the error.
ERRORS
The ioctl() function will fail for any type of file if:
EBADF The fildes argument is not a valid open file descrip-
tor.
EINTR A signal was caught during the execution of the
ioctl() function.
EINVAL
SunOS 5.8 Last change: 15 Feb 1996 1
System Calls ioctl(2)
The STREAM or multiplexer referenced by fildes is
linked (directly or indirectly) downstream from a mul-
tiplexer.
The ioctl() function will also fail if the device driver
detects an error. In this case, the error is passed through
ioctl() without change to the caller. A particular driver
might not have all of the following error cases. Under the
following conditions, requests to device drivers may fail
and set errno to indicate the error
EFAULT
The request argument requires a data transfer to or
from a buffer pointed to by arg, but arg points to an
illegal address.
EINVAL
The request or arg argument is not valid for this dev-
ice.
EIO Some physical I/O error has occurred.
ENOLINK
The fildes argument is on a remote machine and the
link to that machine is no longer active.
ENOTTY
The fildes argument is not associated with a STREAMS
device that accepts control functions.
ENXIO The request and arg arguments are valid for this dev-
ice driver, but the service requested can not be per-
formed on this particular subdevice.
ENODEV
The fildes argument refers to a valid STREAMS device,
but the corresponding device driver does not support
the ioctl() function.
STREAMS errors are described in streamio(7I).
SEE ALSO
streamio(7I), termio(7I)
SunOS 5.8 Last change: 15 Feb 1996 2
Bob Palowoda | Solaris x86 Corner http://fishbutt.fiver.net
palowoda@xxxxxxxxx | Do you still remember, December's foggy freeze.
bob.palowoda@xxxxxxx |
------------------------------------------------------------------------
GET A NEXTCARD VISA, in 30 seconds! Get rates
as low as 0.0% Intro APR and no hidden fees.
Apply NOW!
http://click.egroups.com/1/967/3/_/3702/_/949574672/
-- Create a poll/survey for your group!
-- http://www.egroups.com/vote?listname=solarisonintel&m=1