 |
Index for
Section 2 |
|
 |
Alphabetical
listing for W |
|
 |
Bottom of
page |
|
write(2)
NAME
write, pwrite, writev - Write to a file
SYNOPSIS
#include <unistd.h>
ssize_t write(
int filedes,
const void *buffer,
size_t nbytes );
ssize_t pwrite(
int filedes,
const void *buffer,
size_t nbytes,
off_t offset );
#include <sys/uio.h>
ssize_t writev(
int filedes,
const struct iovec *iov,
int iov_count );
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
write(), writev(): XSH4.0, XSH4.2, XSH5.0, XNS5.0
pwrite(): POSIX.1, XSH5.0
Unless otherwise stated, when text is tagged with an indicator for a
particular revision of a standard, the information applies when the
application is built in a compilation environment that adheres to the
specified and higher revisions of that standard. Refer to the standards(5)
reference page for more information about industry standards and associated
tags.
PARAMETERS
filedes
Identifies the file to which the data is to be written.
buffer
Points to the buffer containing the data to be written.
nbytes
Specifies the number of bytes to write to the file associated with the
filedes parameter.
offset
Specifies the desired start position inside the file associated with
the filedes parameter.
iov Points to an array of iovec structures, which identifies the buffers
containing the data to be written. The iovec structure is defined in
the sys/uio.h header file and contains the following members:
void *iov_base;
size_t iov_len;
iov_count
Specifies the number of iovec structures pointed to by the iov
parameter.
DESCRIPTION
The write() function attempts to write nbytes of data to the file
associated with the filedes parameter from the buffer pointed to by the
buffer parameter.
If the nbytes parameter is 0 (zero), the write() function returns 0 (zero)
and has no other results if the file is a regular file.
[XNS5.0] If filedes refers to a socket, a write() request is equivalent to
a send() request with no options set.
The pwrite() function performs the same action as write(), except that it
writes into a given position in the file (specified by the offset
parameter) without changing the file pointer.
The writev() function performs the same action as the write() function, but
gathers the output data from the iov_count buffers specified by the array
of iovec structures pointed to by the iov parameter. Each iovec entry
specifies the base address and length of an area in memory from which data
should be written. The iov_count parameter is valid if greater than 0
(zero) and less than or equal to IOV_MAX, which is defined in the
<limits.h> header file. The writev() function always writes a complete area
before proceeding to the next.
If filedes refers to a regular file and all of the iov_len members in the
array pointed to by iov are 0 (zero), writev() returns 0 and has no other
effect.
With regular files and devices capable of seeking, the actual writing of
data proceeds from the position in the file indicated by the file pointer.
If this incremented file pointer is greater than the length of the file,
the length of the file is set to this file offset. Upon return from the
write() or pwrite() function, the file pointer increments by the number of
bytes actually written.
If the O_SYNC flag of the file status options is set and the filedes
parameter refers to a regular file, a successful write() or pwrite() call
does not return until the data is delivered to the underlying hardware, as
described in open(2).
With 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.
If the O_APPEND flag of the file status options is set, the file offset is
set to the end of the file prior to each write, and no intervening file
modification operation occurs between changing the file offset and the
write operation.
If a write() or pwrite() requests that more bytes be written than there is
space for (for example, the ulimit() or the physical end of a medium), only
as many bytes as there is space for are 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 nonzero number of bytes will give
a failure return (except as noted below) and [XSH4.2] a SIGXFSZ signal is
generated for the process.
If a write() or pwrite() function is interrupted by a signal before it
writes any data, it returns -1 with errno set to [EINTR].
If a write() or pwrite() function is interrupted by a signal after it
successfully writes some data, it returns the number of bytes written.
After a write() or pwrite() to a regular file has successfully returned:
· Any successful read() from each byte position in the file that was
modified by that write returns the data specified by the write() or
pwrite() for that position until such byte positions are again
modified.
· Any subsequent successful write() or pwrite() to the same byte
position in the file overwrites that file data.
Write requests to a pipe (or FIFO) are handled the same as a regular file
with the following exceptions:
· There is no file offset associated with a pipe; hence each write() or
pwrite() request appends to the end of the pipe.
· If the size of the write() or pwrite() request is less than or equal
to the value of the PIPE_BUF system variable, the write() or pwrite()
call is guaranteed to be atomic. The data is not interleaved with data
from other processes doing writes on the same pipe. Writes of greater
than PIPE_BUF bytes can have data interleaved, on arbitrary
boundaries, with writes by other processes, whether or not O_NONBLOCK
is set.
[Tru64 UNIX] This also applies whether or not O_NDELAY is set.
· If O_NONBLOCK is clear, a write() or pwrite() request to a full pipe
causes the process to block until enough space becomes available to
handle the entire request.
[Tru64 UNIX] This also applies if O_NDELAY is clear.
· If the O_NONBLOCK flag is set, write() or pwrite() requests are
handled differently in the following ways: the function does block the
process; requests for PIPE_BUF or fewer bytes either succeed
completely and return nbytes, or return -1 and set errno to [EAGAIN].
A request for greater than PIPE_BUF bytes either transfers as much as
it can and returns the number of bytes written, or transfers no data
and returns -1 with errno set to [EAGAIN]. Also, if a request is
greater than PIPE_BUF bytes and all data previously written to the
pipe has been read, write() or pwrite() transfers at least PIPE_BUF
bytes.
[Tru64 UNIX] This also applies if O_NDELAY is set.
When attempting to write to a file descriptor (other than a pipe or a FIFO)
that supports nonblocking writes and cannot accept data immediately, the
write() and pwrite() functions behave as follows:
· If O_NONBLOCK is clear, the function blocks until the data can be
accepted.
[Tru64 UNIX] This also applies if O_NDELAY is clear.
· If O_NONBLOCK is set, the function does not block the process.
Instead, if some data can be written without blocking the process, it
writes as much as it can and returns the number of bytes written.
Otherwise, it returns -1 and errno is set to [EAGAIN].
[Tru64 UNIX] This also applies if O_NDELAY is set, except 0 (zero) is
returned.
[Tru64 UNIX] When attempting to write to a regular file with enforcement
mode record locking enabled and all or part of the region to be written is
currently locked by another process, the write() and pwrite() functions
behave as follows:
· If O_NDELAY and O_NONBLOCK are clear (the default), the calling
process blocks until all of the blocking locks are removed or until
the function is terminated by a signal.
· If O_NDELAY or O_NONBLOCK is set, the function returns --1 and sets
errno to [EAGAIN].
Upon successful completion, the write() or pwrite() function marks the
st_ctime and st_mtime fields of the file for update and, if the file is a
regular file, clears its set-user ID and set-group ID attributes.
The fcntl(2) reference page provides more information about record locks.
Writing Data to STREAMS Files
[XSH4.2] For STREAMS files, the operation of write() and pwrite() is
determined by the values of the minimum and maximum nbytes range ("packet
size" accepted by the STREAM). These values are contained in the topmost
STREAM module. Unless the user pushes the topmost module, these values
cannot be set or tested from user level (see I_PUSH on the streamio(7))
reference page). If nbytes falls within the packet size range, nbytes bytes
are written. If nbytes does not fall within the range and the minimum
packet size value is 0 (zero), write() or pwrite() breaks the buffer into
maximum packet size segments prior to sending the data downstream (the last
segment may contain less than the maximum packet size). If nbytes does not
fall within the range and the minimum value is nonzero, write() or pwrite()
fails with errno set to [ERANGE]. Writing a zero-length buffer (nbytes is
0) sends 0 bytes with 0 returned. However, writing a zero-length buffer to
a STREAMS-based pipe or FIFO sends no message and 0 is returned. The
process may issue the I_SWROPT ioctl() request to enable zero-length
messages to be sent across the pipe or FIFO.
[XSH4.2] When writing to a STREAM, data messages are created with a
priority band of 0 (zero). When writing to a STREAM that is not a pipe or
FIFO, the write() and pwrite() functions behave as follows:
· If O_NONBLOCK is clear and the STREAM cannot accept data (that is, the
STREAM write queue is full due to internal flow control conditions),
the function blocks until data can be accepted.
[Tru64 UNIX] This also applies if O_NDELAY is clear.
· If O_NONBLOCK is set and the STREAM cannot accept data, the function
returns -1 and sets errno to [EAGAIN].
[Tru64 UNIX] This also applies if O_NDELAY is set.
· If O_NONBLOCK is set and part of the buffer has been written when a
condition occurs in which the STREAM cannot accept additional data,
the function terminates and returns the number of bytes written.
[Tru64 UNIX] This also applies if O_NDELAY is set.
[XSH4.2] In addition, write(), pwrite(), and writev() 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(), pwrite(),
or writev(), but reflects the prior error.
NOTES
[Tru64 UNIX] For compatibility with earlier releases, values for iov_len
that are greater than or equal to 2^63 will be treated as zero.
[Tru64 UNIX] The write(), pwrite(), and writev() functions, which suspend
the calling process until the request is completed, are redefined so that
only the calling thread is suspended.
[Tru64 UNIX] When debugging a module that includes the writev() function,
use _Ewritev to refer to the writev() call.
When a read(), pread(), write(), or pwrite() system call on a pipe is
interrupted by a signal and no bytes have been transferred through the
pipe, a value of -1 is returned and errno is set to [EINTR]. This behavior
is different from previous releases in which both read() and write() either
restarted the transfer or set errno to [EINTR], depending on the setting of
the SA_RESTART option for the interrupting signal.
As a result of this change, applications must now either handle the [EINTR]
error or block any expected signals for the duration of the read(),
pread(), write(), or pwrite() operation.
RETURN VALUES
Upon successful completion, the write() or pwrite() function returns the
number of bytes actually written to the file associated with the filedes
parameter. This number is never greater than nbytes. Otherwise, a value of
-1 is returned and errno is set to indicate the error.
Upon successful completion, the writev() function returns the number of
bytes that were actually written. Otherwise, a value of -1 is returned, the
file-pointer remains unchanged, and errno is set to indicate the error.
End-of-Media Handling for Tapes
If writing goes beyond the "early warning" EOT indicator while this
indicator is disabled, the write(), pwrite(), and writev() functions will
return the number of bytes actually written. The write(), pwrite(), and
writev() functions return a value of -1, if:
· Attempting to write past the "real" EOT.
· Attempting to write past "early warning" EOT indicator while this
indicator is enabled.
Refer to mtio(7) for information on enabling and disabling "early warning"
EOT.
End-of-Media Handling for Disks
Disk end-of-media handling is POSIX-compliant. Attempting to write at or
beyond the end of a partition returns a value of -1. A partial write
returns the number of bytes actually written.
Note: A partial write is a request that spans the end of a partition.
ERRORS
The write(), pwrite(), and writev() functions set errno to the specified
values for the following conditions:
[EAGAIN]
The O_NONBLOCK flag is set on this file and the process would be
delayed in the write operation.
[Tru64 UNIX] An attempt was made to write to a STREAM that cannot
accept data with either the O_NDELAY or O_NONBLOCK flag set.
[Tru64 UNIX] An enforcement mode record lock is outstanding in the
portion of the file that is to be written.
[EBADF]
The filedes parameter does not specify a valid file descriptor that is
open for writing.
[EDEADLK]
[Tru64 UNIX] Enforced record locking is enabled, O_NDELAY is clear,
and a deadlock condition is detected.
[EDQUOT]
[Tru64 UNIX] The write failed because the user's disk block quota is
exhausted.
[EFAULT]
[Tru64 UNIX] The buffer parameter or part of the iov parameter points
to a location outside the allocated address space of the process.
[EFBIG]
An attempt was made to write a file that exceeds the maximum file size.
[EINTR]
A write() or pwrite() on a pipe is interrupted by a signal and no bytes
have been transferred through the pipe.
[EINVAL]
[XSH4.2] The STREAM or multiplexer referenced by filedes is linked
(directly or indirectly) downstream from a multiplexer.
[XSH4.2] The iov_count parameter value was less than or equal to 0 or
greater than IOV_MAX.
[XSH4.2] The sum of the iov_len values in the iov array would overflow
an ssize_t buffer.
[Tru64 UNIX] The file position pointer associated with the filedes
parameter was negative.
[Tru64 UNIX] One of the iov_len values in the iov array was negative
or the sum overflowed a 32-bit integer.
[EIO]
[XSH4.2] A physical I/O error occurred. These errors do not always
occur with the associated function, but can occur with the subsequent
function.
[ENOLCK]
[Tru64 UNIX] The file has enforcement mode file locking set, and
allocating another locked region would exceed the configurable system
limit of NLOCK_RECORD.
[ENOSPC]
[XSH4.2] No free space is left on the file system containing the file.
[Tru64 UNIX] An attempt was made to write past the "early warning" EOT
while this indicator was enabled.
[Tru64 UNIX] An attempt was made to write at or beyond the end of a
partition.
[ENXIO]
[XSH4.2] A hangup occurred on the STREAM being written to.
The device associated with file descriptor (the filedes parameter) is a
block special device or character special file, and the file pointer is
out of range.
[EPERM]
[Tru64 UNIX] An attempt was made to write to a socket or type
SOCK_STREAM that is not connected to a peer socket.
[EPIPE]
[XSH4.2] An attempt was made to write to a pipe that has only one end
open.
An attempt was made to write to a pipe or FIFO that is not opened for
reading by any process. A SIGPIPE signal is sent to the process.
[ERANGE]
[XSH4.2] The transfer request size was outside the range supported by
the STREAMS file associated with filedes.
In addition, the pwrite() function fails and the file pointer remains
unchanged if the following is true:
[ESPIPE]
The file specified by fildes is associated with a pipe or FIFO.
[XSH4.2] A write to a STREAMS file can 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.
For NFS file access, if the write(), pwrite(), or writev() function fails,
errno may also be set to one of the following values:
[EFBIG]
[Tru64 UNIX] For filesystems mounted with the nfsv2 option, the
process attempted to write beyond the 2 gigabyte boundary.
[EISDIR]
[Tru64 UNIX] The named file is a directory and write access is
requested.
[ENOBUFS]
[Tru64 UNIX] Insufficient resources, such as buffers, are available
to complete the call. Typically, a call used with sockets has failed
due to a shortage of message or send/receive buffer space.
[EROFS]
[Tru64 UNIX] The named file resides on a read-only file system and
write access is required.
[ESTALE]
[Tru64 UNIX] The NFS file handle is stale. An opened file was deleted
by the server or another client, a client cannot open a file because
the server has unmounted or unexported the remote directory, or the
directory that contains an opened file was either unmounted or
unexported by the server.
If the write(), pwrite(), or writev() function fails while in the System V
habitat, errno may also be set to one of the following errors:
[EAGAIN]
[Tru64 UNIX] A write to a pipe (FIFO) of PIPE_BUF bytes or less is
requested, O_NONBLOCK is set, and less than nbytes bytes of free space
is available.
[Tru64 UNIX] Enforced record locking was enabled, O_NDELAY or
O_NONBLOCK was set and there were record-locks on the file, or
O_NONBLOCK was set, and data cannot be accepted immediately.
[EINVAL]
[Tru64 UNIX] The sum of the iov_len values in the iov array
overflowed an integer.
[ERANGE]
[Tru64 UNIX] Attempts to write to a STREAM with nbytes are outside
the specified minimum and maximum range, and the minimum value is non-
zero.
SEE ALSO
Functions: fcntl(2), getmsg(2), lseek(2), open(2), pipe(2), poll(2),
select(2), lockf(3), ulimit(3)
Files: mtio(7)
Standards: standards(5)
|
Index for
Section 2 |
|
|
Alphabetical
listing for W |
|
 |
Top of
page |
|