write, writex
Purpose
Writes to a file.
Syntax
int write (fildes, buf, nbytes) int writex (fildes, buf, nbytes, ext)
int fildes; int fildes;
char *buf; char *buf;
unsigned int nbytes; unsigned int nbytes;
int ext;
Description
The write system call writes the number of bytes speci-
fied by the nbytes parameter from the buffer specified by
the buf parameter to the file associated with the fildes
parameter. If Distributed Services is installed on your
system, this file can reside on another node.
The fildes parameter is a file descriptor obtained from a
creat, open, dup, fcntl, or pipe system call.
On devices capable of seeking, the actual writing of data
proceeds from the position in the file indicated by the
file pointer. Upon return from the write system call,
the file pointer increments by the number of bytes actu-
ally written.
On devices incapable of seeking, writing always takes
place starting at the current position. The value of a
file pointer associated with such a device is undefined.
When the O_APPEND flag of the file status is set, the
file pointer is set to the end of the file prior to each
write.
If the write system call requests that more bytes be
written than there is room for, only as many bytes as
there is room for are written and the write system call
returns an integer equal to the number of bytes written.
The next attempt to write nonzero number of bytes will
fail (except as noted following). The limit reached can
be either the ulimit (see "ulimit") or the end of the
physical medium. A partial write is not permitted for
the following:
o If the file being written is a pipe (or FIFO) and the
O_NDELAY flag of the file flag word is set, then a
write to a full pipe (or FIFO) returns a count of 0.
o If the file being written is a pipe (or FIFO) and the
O_NDELAY flag of the file flag word is not set, then
a write to a full pipe (or FIFO) blocks until space
becomes available.
If the file to be written supports enforcement mode
record locks and all or part of the region to be written
is currently locked by another process, then the action
taken depends on the setting of the O_NDELAY flag:
o If O_NDELAY is set, then write returns -1 and sets
errno to EAGAIN.
o If O_NDELAY is not set, then the calling process
blocks until the lock is released.
For more information about record locks, see "lockf."
If the file has been mapped, the write system call writes
to a mapped file segment. If the fildes file descriptor
was used to map the file copy-on-write, then the copy-on-
write segment is used. Otherwise, the write system call
writes to the read-write mapped segment for the file.
Warning: If a process issues a write system call to a
file that it has not mapped, but that other processes
have mapped copy-on-write, then the results are unpre-
dictable. However, if the process first attaches the
mapped file in copy-on-write mode with the shmat system
call, then the write to the file is properly reflected in
the copy-on-write shared segment.
The writex system call performs the same function as
write, except that it provides communication with char-
acter device drivers that require more information or
return more status than write can handle.
For files, directories, or special files with drivers
that do not handle extended operations, the writex system
call does exactly what the write system call does, and
the ext parameter is ignored.
Each driver interprets the ext parameter in a device-
dependent way, either as a value or as a pointer to a
communication area. The nonextended write system call is
equivalent to the extended writex system call with an ext
parameter value of 0. Drivers must apply reasonable
defaults when the ext parameter value is 0.
Return Value
Upon successful completion, the number of bytes actually
written is returned. If the write or writex system call
fails, a value of -1 is returned and errno is set to
indicate the error.
Diagnostics
The write and writex system calls fail and the file
pointer remains unchanged if one or more of the following
are true:
EBADF The fildes parameter is not a valid file
descriptor open for writing.
EAGAIN An enforcement mode record lock is outstanding
in the portion of the file that is to be
written.
EPIPE An attempt is made to write to a pipe that is
not open for reading by any process. A
SIGPIPE signal is also sent to the calling
process.
EFBIG An attempt is made to write a file that
exceeds the process's file size limit or the
maximum file size (see "ulimit"). If Distrib-
uted Services is installed on your system, the
file size cannot exceed the client's default
file size limit.
EFAULT buf &pointsout..
EDEADLK A deadlock would occur if the calling process
were to sleep until the region to be written
was unlocked.
EINTR A signal was caught during the write system
call.
If Distributed Services is installed on your system,
write can also fail if one or more of the following are
true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EAGAIN The server is too busy to accept the
request.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "creat," "dup," "lockf," "lseek,"
"open," "pipe," "ulimit," and "writev."
Device Driver Development Guide.