 |
Index for Section 2 |
|
 |
Alphabetical listing for W |
|
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);
The following version of the writev() function does not conform to current
standards and is supported only for backward compatibility:
#include <sys/types.h>
#include <sys/uio.h>
ssize_t writev(
int filedes ,
struct iovec *iov,
int iov_count );
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
write(): XPG4, XPG4-UNIX
pwrite(): POSIX.1c
writev(): XPG4-UNIX
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;
[Digital] The backward-compatible version of the iovec structure
contains the following members:
caddr_t iov_base;
int 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.
[XPG4-UNIX] If filedes refers to a socket, write() is equivalent to send()
with no flags 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 flags is set and the filedes
parameter refers to a regular file, a successful write() or pwrite()
function does not return until the data is delivered to the underlying
hardware (as described in the open() function).
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 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
room for (for example, the ulimit() or the physical end of a medium), only
as many bytes as there is room 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). [XPG4-UNIX] Also, 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()
function 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.
[Digital] 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.
[Digital] 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 what 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.
[Digital] 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.
[Digital] 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 what it can and returns the number of bytes written. Otherwise,
it returns -1 and errno is set to [EAGAIN].
[Digital] This also applies if O_NDELAY is set, except 0 (zero) is
returned.
[Digital] 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 the blocking locks are removed, or the
function is terminated by a signal.
· If O_NDELAY or O_NONBLOCK is set, then 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 clears its set-
user ID and set-group ID attributes if the file is a regular file.
The fcntl() function provides more information about record locks.
Writing Data to STREAMS Files
[XPG4-UNIX] 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 I_SWROPT ioctl() to
enable zero-length messages to be sent across the pipe or FIFO.
[XPG4-UNIX] 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 (the STREAM
write queue is full due to internal flow control conditions), the
function blocks until data can be accepted.
[Digital] 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].
[Digital] This also applies if O_NDELAY is set.
· If O_NONBLOCK is set and part of the buffer has been written when a
condition in which the STREAM can not accept additional data occurs,
the function terminates and returns the number of bytes written.
[Digital] This also applies if O_NDELAY is set.
[XPG4-UNIX] 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
[Digital] 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.
[Digital] When debugging a module that includes the writev() function and
for which _XOPEN_SOURCE_EXTENDED has been defined, use _Ewritev to refer to
the writev() call. See standards(5) for information on when the
_XOPEN_SOURCE_EXTENDED macro is defined.
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, when both read() and write() either
restarted the transfer or set errno to [EINTR], depending on the setting of
the SA_RESTART flag for the interrupting signal.
As a result of this change, applications must now either handle the [EINTR]
return 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 be 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 and placed into the buffer.
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 which 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.
[Digital] An attempt was made to write to a STREAM that can not
accept data with either the O_NDELAY or O_NONBLOCK flag set.
[Digital] 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
open for writing.
[EDEADLK] [Digital] Enforced record locking is enabled, O_NDELAY is clear,
and a deadlock condition is detected.
[EDQUOT] [Digital] The write has failed because the user's disk block
quota is exhausted.
[EFAULT] [Digital] The buffer parameter or part of the iov parameter
points to a location outside of 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] [XPG4-UNIX] The STREAM or multiplexer referenced by filedes is
linked (directly or indirectly) downstream from a multiplexer.
[XPG4-UNIX] The iov_count parameter value was less than or equal
to 0 or greater than IOV_MAX.
[XPG4-UNIX] The sum of the iov_len values in the iov array would
overflow an ssize_t.
[Digital] The file position pointer associated with the filedes
parameter was negative.
[Digital] One of the iov_len values in the iov array was
negative or the sum overflowed a 32-bit integer.
[EIO] [XPG4-UNIX] A physical I/O error has occurred. These errors do
not always occur with the associated function, but can occur with
the subsequent function.
[ENOLCK] [Digital] The file has enforcement mode file locking set and
allocating another locked region would exceed the configurable
system limit of NLOCK_RECORD.
[ENOSPC] [XPG4-UNIX] No free space is left on the file system containing
the file.
[Digital] An attempt was made to write past the "early warning"
EOT while this indicator was enabled.
[Digital] An attempt was made to write at or beyond the end of a
partition.
[ENXIO] [XPG4-UNIX] 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] [Digital] An attempt was made to write to a socket or type
SOCK_STREAM that is not connected to a peer socket.
[EPIPE] [XPG4-UNIX] 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] [XPG4-UNIX] 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.
[XPG4-UNIX] 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] [Digital] For filesystems mounted with the nfsv2 option, the
process attempted to write beyond the 2 gigabyte boundary.
[EISDIR] [Digital] The named file is a directory and write access is
requested.
[ENOBUFS] [Digital] Indicates insufficient resources, such as buffers, to
complete the call. Typically, a call used with sockets has
failed due to a shortage of message or send/receive buffer space.
[EROFS] [Digital] The named file resides on a read-only file system and
write access is required.
[ESTALE] [Digital] Indicates a stale NFS file handle. 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] [Digital] 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.
[Digital] 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] [Digital] The sum of the iov_len values in the iov array
overflowed an integer.
[ERANGE] [Digital] Attempts to write to a STREAM with nbytes are outside
the specified minimum and maximum range, and the minimum value is
non-zero.
RELATED INFORMATION
Functions: open(2), fcntl(2), lseek(2), mtio(7), open(2), getmsg(2),
lockf(3), pipe(2), poll(2), select(2) ulimit(3)
Standards: standards(5)