write.3p (22217B)
- '\" et
- .TH WRITE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- pwrite,
- write
- \(em write on a file
- .SH SYNOPSIS
- .LP
- .nf
- #include <unistd.h>
- .P
- ssize_t pwrite(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP,
- off_t \fIoffset\fP);
- ssize_t write(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIwrite\fR()
- function shall attempt to write
- .IR nbyte
- bytes from the buffer pointed to by
- .IR buf
- to the file associated with the open file descriptor,
- .IR fildes .
- .P
- Before any action described below is taken, and if
- .IR nbyte
- is zero and the file is a regular file, the
- \fIwrite\fR()
- function may detect and return errors as described below. In the
- absence of errors, or if error detection is not performed, the
- \fIwrite\fR()
- function shall return zero and have no other results. If
- .IR nbyte
- is zero and the file is not a regular file, the results are
- unspecified.
- .P
- On a regular file or other file capable of seeking, the actual writing
- of data shall proceed from the position in the file indicated by the
- file offset associated with
- .IR fildes .
- Before successful return from
- \fIwrite\fR(),
- the file offset shall be incremented by the number of bytes actually
- written. On a regular file, if the position of the last byte written
- is greater than or equal to the length of the file,
- the length of the file shall be set to this position plus one.
- .P
- On a file not capable of seeking, writing shall always take place
- starting at the current position. The value of a file offset associated
- with such a device is undefined.
- .P
- If the O_APPEND flag of the file status flags is set,
- the file offset shall be set to the end of the file prior to each write
- and no intervening file modification operation shall occur between
- changing the file offset and the write operation.
- .P
- If a
- \fIwrite\fR()
- requests that more bytes be written than there is room for (for
- example,
- the file size limit of the process or
- the physical end of a medium), only as many bytes as there is room for
- shall be written. For example, suppose there is space for 20 bytes more
- in a file before reaching a limit. A write of 512 bytes will return
- 20. The next write of a non-zero number of bytes would give a failure
- return (except as noted below).
- .P
- If the request would cause the file size to exceed the soft file size
- limit for the process and there is no room for any bytes to be written,
- the request shall fail and the implementation shall generate the
- SIGXFSZ signal for the thread.
- .P
- If
- \fIwrite\fR()
- is interrupted by a signal before it writes any data, it shall
- return \-1 with
- .IR errno
- set to
- .BR [EINTR] .
- .P
- If
- \fIwrite\fR()
- is interrupted by a signal after it successfully writes some data, it
- shall return the number of bytes written.
- .P
- If the value of
- .IR nbyte
- is greater than
- {SSIZE_MAX},
- the result is implementation-defined.
- .P
- After a
- \fIwrite\fR()
- to a regular file has successfully returned:
- .IP " *" 4
- Any successful
- \fIread\fR()
- from each byte position in the file that was modified by that write
- shall return the data specified by the
- \fIwrite\fR()
- for that position until such byte positions are again modified.
- .IP " *" 4
- Any subsequent successful
- \fIwrite\fR()
- to the same byte position in the file shall overwrite that file data.
- .br
- .P
- Write requests to a pipe or FIFO shall be handled in the same way
- as a regular file with the following exceptions:
- .IP " *" 4
- There is no file offset associated with a pipe, hence each write
- request shall append to the end of the pipe.
- .IP " *" 4
- Write requests of
- {PIPE_BUF}
- bytes or less shall not be interleaved with data from other processes
- doing writes on the same pipe. Writes of greater than
- {PIPE_BUF}
- bytes may have data interleaved, on arbitrary boundaries, with writes
- by other processes, whether or not the O_NONBLOCK flag of the file
- status flags is set.
- .IP " *" 4
- If the O_NONBLOCK flag is clear, a write request may cause the thread
- to block, but on normal completion it shall return
- .IR nbyte .
- .IP " *" 4
- If the O_NONBLOCK flag is set,
- \fIwrite\fR()
- requests shall be handled differently, in the following ways:
- .RS 4
- .IP -- 4
- The
- \fIwrite\fR()
- function shall not block the thread.
- .IP -- 4
- A write request for
- {PIPE_BUF}
- or fewer bytes shall have the following effect: if there is sufficient
- space available in the pipe,
- \fIwrite\fR()
- shall transfer all the data and return the number of bytes requested.
- Otherwise,
- \fIwrite\fR()
- shall transfer no data and return \-1 with
- .IR errno
- set to
- .BR [EAGAIN] .
- .IP -- 4
- A write request for more than
- {PIPE_BUF}
- bytes shall cause one of the following:
- .RS 4
- .IP -- 4
- When at least one byte can be written, transfer what it can and return
- the number of bytes written. When all data previously written to the
- pipe is read, it shall transfer at least
- {PIPE_BUF}
- bytes.
- .IP -- 4
- When no data can be written, transfer no data, and return \-1 with
- .IR errno
- set to
- .BR [EAGAIN] .
- .RE
- .RE
- .P
- When attempting to write to a file descriptor (other than a pipe or
- FIFO) that supports non-blocking writes and cannot accept the data
- immediately:
- .IP " *" 4
- If the O_NONBLOCK flag is clear,
- \fIwrite\fR()
- shall block the calling thread until the data can be accepted.
- .IP " *" 4
- If the O_NONBLOCK flag is set,
- \fIwrite\fR()
- shall not block the thread. If some data can be written without
- blocking the thread,
- \fIwrite\fR()
- shall write what it can and return the number of bytes written.
- Otherwise, it shall return \-1 and set
- .IR errno
- to
- .BR [EAGAIN] .
- .P
- Upon successful completion, where
- .IR nbyte
- is greater than 0,
- \fIwrite\fR()
- shall mark for update the last data modification and last file
- status change timestamps 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.
- .P
- For regular files, no data transfer shall occur past the offset maximum
- established in the open file description associated with
- .IR fildes .
- .P
- If
- .IR fildes
- refers to a socket,
- \fIwrite\fR()
- shall be equivalent to
- \fIsend\fR()
- with no flags set.
- .P
- If the O_DSYNC bit has been set,
- write I/O operations on the file descriptor shall complete as defined
- by synchronized I/O data integrity completion.
- .P
- If the O_SYNC bit has been set, write I/O operations on the file
- descriptor shall complete as defined by synchronized I/O file
- integrity completion.
- .P
- If
- .IR fildes
- refers to a shared memory object, the result of the
- \fIwrite\fR()
- function is unspecified.
- .P
- If
- .IR fildes
- refers to a typed memory object, the result of the
- \fIwrite\fR()
- function is unspecified.
- .P
- If
- .IR fildes
- refers to a STREAM, the operation of
- \fIwrite\fR()
- shall be determined by the values of the minimum and maximum
- .IR nbyte
- range (packet size) accepted by the STREAM. These values are determined
- by the topmost STREAM module. If
- .IR nbyte
- falls within the packet size range,
- .IR nbyte
- bytes shall be written. If
- .IR nbyte
- does not fall within the range and the minimum packet size value is 0,
- \fIwrite\fR()
- shall break 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
- .IR nbyte
- does not fall within the range and the minimum value is non-zero,
- \fIwrite\fR()
- shall fail with
- .IR errno
- set to
- .BR [ERANGE] .
- Writing a zero-length buffer (\c
- .IR nbyte
- is 0) to a STREAMS device 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
- \fIioctl\fR()
- to enable zero-length messages to be sent across the pipe or FIFO.
- .P
- When writing to a STREAM, data messages are created with a priority
- band of 0. When writing to a STREAM that is not a pipe or FIFO:
- .IP " *" 4
- If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM
- write queue is full due to internal flow control conditions),
- \fIwrite\fR()
- shall block until data can be accepted.
- .IP " *" 4
- If O_NONBLOCK is set and the STREAM cannot accept data,
- \fIwrite\fR()
- shall return \-1 and set
- .IR errno
- to
- .BR [EAGAIN] .
- .IP " *" 4
- If O_NONBLOCK is set and part of the buffer has been written while a
- condition in which the STREAM cannot accept additional data occurs,
- \fIwrite\fR()
- shall terminate and return the number of bytes written.
- .P
- In addition,
- \fIwrite\fR()
- shall fail if the STREAM head has processed an asynchronous error
- before the call. In this case, the value of
- .IR errno
- does not reflect the result of
- \fIwrite\fR(),
- but reflects the prior error.
- .P
- The
- \fIpwrite\fR()
- function shall be equivalent to
- \fIwrite\fR(),
- except that it writes into a given position and does not change the
- file offset (regardless of whether O_APPEND is set). The first three
- arguments to
- \fIpwrite\fR()
- are the same as
- \fIwrite\fR()
- with the addition of a fourth argument
- .IR offset
- for the desired position inside the file. An attempt to perform a
- \fIpwrite\fR()
- on a file that is incapable of seeking shall result in an error.
- .SH "RETURN VALUE"
- Upon successful completion, these functions shall return the number of
- bytes actually written to the file associated with
- .IR fildes .
- This number shall never be greater than
- .IR nbyte .
- Otherwise, \-1 shall be returned and
- .IR errno
- set to indicate the error.
- .SH ERRORS
- These functions shall fail if:
- .TP
- .BR EAGAIN
- The file is neither a pipe, nor a FIFO, nor a socket, the O_NONBLOCK flag
- is set for the file descriptor, and the thread would be delayed in the
- \fIwrite\fR()
- operation.
- .TP
- .BR EBADF
- The
- .IR fildes
- argument is not a valid file descriptor open for writing.
- .TP
- .BR EFBIG
- An attempt was made to write a file that exceeds the
- implementation-defined maximum file size
- or the file size limit of the process,
- and there was no room for any bytes to be written.
- .TP
- .BR EFBIG
- The file is a regular file,
- .IR nbyte
- is greater than 0, and the starting position is greater than or equal
- to the offset maximum established in the open file description
- associated with
- .IR fildes .
- .TP
- .BR EINTR
- The write operation was terminated due to the receipt of a signal, and
- no data was transferred.
- .TP
- .BR EIO
- The process is a member of a background process group attempting to
- write to its controlling terminal, TOSTOP is set, the calling thread
- is not blocking SIGTTOU, the process is not ignoring SIGTTOU,
- and the process group of the process is orphaned. This error may also
- be returned under implementation-defined conditions.
- .TP
- .BR ENOSPC
- There was no free space remaining on the device containing the file.
- .TP
- .BR ERANGE
- The transfer request size was outside the range supported by the
- STREAMS file associated with
- .IR fildes .
- .P
- The
- \fIpwrite\fR()
- function shall fail if:
- .TP
- .BR EINVAL
- The file is a regular file or block special file, and the
- .IR offset
- argument is negative. The file offset shall remain unchanged.
- .TP
- .BR ESPIPE
- The file is incapable of seeking.
- .P
- The
- \fIwrite\fR()
- function shall fail if:
- .TP
- .BR EAGAIN
- The file is a pipe or FIFO, the O_NONBLOCK flag is set for the file
- descriptor, and the thread would be delayed in the write operation.
- .TP
- .BR EAGAIN " or " EWOULDBLOCK
- .br
- The file is a socket, the O_NONBLOCK flag is set for the file
- descriptor, and the thread would be delayed in the write operation.
- .TP
- .BR ECONNRESET
- A write was attempted on a socket that is not connected.
- .TP
- .BR EPIPE
- An attempt is made to write to a pipe or FIFO that is not open for
- reading by any process, or that only has one end open. A SIGPIPE signal
- shall also be sent to the thread.
- .TP
- .BR EPIPE
- A write was attempted on a socket that is shut down for writing, or is
- no longer connected. In the latter case, if the socket is of type
- SOCK_STREAM, a SIGPIPE signal shall also be sent to the thread.
- .P
- These functions may fail if:
- .TP
- .BR EINVAL
- The STREAM or multiplexer referenced by
- .IR fildes
- is linked (directly or indirectly) downstream from a multiplexer.
- .TP
- .BR EIO
- A physical I/O error has occurred.
- .TP
- .BR ENOBUFS
- Insufficient resources were available in the system to perform the
- operation.
- .TP
- .BR ENXIO
- A request was made of a nonexistent device, or the request was outside
- the capabilities of the device.
- .TP
- .BR ENXIO
- A hangup occurred on the STREAM being written to.
- .P
- A write to a STREAMS file may fail if an error message has been
- received at the STREAM head. In this case,
- .IR errno
- is set to the value included in the error message.
- .br
- .P
- The
- \fIwrite\fR()
- function may fail if:
- .TP
- .BR EACCES
- A write was attempted on a socket and the calling
- process does not have appropriate privileges.
- .TP
- .BR ENETDOWN
- A write was attempted on a socket and the local network interface used
- to reach the destination is down.
- .TP
- .BR ENETUNREACH
- .br
- A write was attempted on a socket and no route to the network is
- present.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Writing from a Buffer"
- .P
- The following example writes data from the buffer pointed to by
- .IR buf
- to the file associated with the file descriptor
- .IR fd .
- .sp
- .RS 4
- .nf
- #include <sys/types.h>
- #include <string.h>
- \&...
- char buf[20];
- size_t nbytes;
- ssize_t bytes_written;
- int fd;
- \&...
- strcpy(buf, "This is a test\en");
- nbytes = strlen(buf);
- .P
- bytes_written = write(fd, buf, nbytes);
- \&...
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- See also the RATIONALE section in
- \fIread\fR().
- .P
- An attempt to write to a pipe or FIFO has several major
- characteristics:
- .IP " *" 4
- \fIAtomic/non-atomic\fP: A write is atomic if the whole amount written
- in one operation is not interleaved with data from any other process.
- This is useful when there are multiple writers sending data to a single
- reader. Applications need to know how large a write request can be
- expected to be performed atomically. This maximum is called
- {PIPE_BUF}.
- This volume of POSIX.1\(hy2017 does not say whether write requests for more than
- {PIPE_BUF}
- bytes are atomic, but requires that writes of
- {PIPE_BUF}
- or fewer bytes shall be atomic.
- .IP " *" 4
- \fIBlocking/immediate\fP: Blocking is only possible with O_NONBLOCK
- clear. If there is enough space for all the data requested to be
- written immediately, the implementation should do so. Otherwise, the
- calling thread may block; that is, pause until enough space is
- available for writing. The effective size of a pipe or FIFO (the
- maximum amount that can be written in one operation without blocking)
- may vary dynamically, depending on the implementation, so it is not
- possible to specify a fixed value for it.
- .IP " *" 4
- \fIComplete/partial/deferred\fP: A write request:
- .RS 4
- .sp
- .RS 4
- .nf
- int fildes;
- size_t nbyte;
- ssize_t ret;
- char *buf;
- .P
- ret = write(fildes, buf, nbyte);
- .fi
- .P
- .RE
- .P
- may return:
- .IP Complete 10
- \fIret\fP=\fInbyte\fP
- .IP Partial 10
- \fIret\fP<\fInbyte\fP
- .RS 10
- .P
- This shall never happen if
- .IR nbyte \(<=\c
- {PIPE_BUF}.
- If it does happen (with
- .IR nbyte >\c
- {PIPE_BUF}),
- \&this volume of POSIX.1\(hy2017 does not guarantee atomicity, even if
- .IR ret \(<=\c
- {PIPE_BUF},
- because atomicity is guaranteed according to the amount
- .IR requested ,
- not the amount
- .IR written .
- .RE
- .IP Deferred: 10
- \fIret\fP=\-1, \fIerrno\fP=[EAGAIN]
- .RS 10
- .P
- This error indicates that a later request may succeed. It does not
- indicate that it
- .IR shall
- succeed, even if
- .IR nbyte \(<=\c
- {PIPE_BUF},
- because if no process reads from the pipe or FIFO, the write never
- succeeds. An application could usefully count the number of times
- .BR [EAGAIN]
- is caused by a particular value of
- .IR nbyte >\c
- {PIPE_BUF}
- and perhaps do later writes with a smaller value, on the assumption
- that the effective size of the pipe may have decreased.
- .RE
- .P
- Partial and deferred writes are only possible with O_NONBLOCK set.
- .RE
- .P
- The relations of these properties are shown in the following tables:
- .TS
- center box tab(!);
- cB s s s
- cB | cB cB c
- l1 | lw(1.25i)1 lw(1.25i)1 lw(1.25i).
- Write to a Pipe or FIFO with O_NONBLOCK \fIclear\fP
- _
- Immediately Writable:!None!Some!\fInbyte\fP
- _
- \fInbyte\fP\(<={PIPE_BUF}!Atomic blocking!Atomic blocking!Atomic immediate
- !\fInbyte\fP!\fInbyte\fP!\fInbyte\fP
- _
- \fInbyte\fP>{PIPE_BUF}!Blocking \fInbyte\fP!Blocking \fInbyte\fP!Blocking \fInbyte\fP
- .TE
- .P
- If the O_NONBLOCK flag is clear, a write request shall block if the
- amount writable immediately is less than that requested. If the flag is
- set (by
- \fIfcntl\fR()),
- a write request shall never block.
- .TS
- center box tab(!);
- cB s s s
- cB | cB cB c
- l1 | lw(1.25i)1 lw(1.25i)1 lw(1.25i).
- Write to a Pipe or FIFO with O_NONBLOCK \fIset\fP
- _
- Immediately Writable:!None!Some!\fInbyte\fP
- _
- \fInbyte\fP\(<={PIPE_BUF}!\-1, [EAGAIN]!\-1, [EAGAIN]!Atomic \fInbyte\fP
- _
- \fInbyte\fP>{PIPE_BUF}!\-1, [EAGAIN]!<\fInbyte\fP or \-1,!\(<=\fInbyte\fP or \-1,
- !![EAGAIN]![EAGAIN]
- .TE
- .P
- There is no exception regarding partial writes when O_NONBLOCK is set.
- With the exception of writing to an empty pipe, this volume of POSIX.1\(hy2017 does not specify
- exactly when a partial write is performed since that would require
- specifying internal details of the implementation. Every application
- should be prepared to handle partial writes when O_NONBLOCK is set and
- the requested amount is greater than
- {PIPE_BUF},
- just as every application should be prepared to handle partial writes
- on other kinds of file descriptors.
- .P
- The intent of forcing writing at least one byte if any can be written
- is to assure that each write makes progress if there is any room in the
- pipe. If the pipe is empty,
- {PIPE_BUF}
- bytes must be written; if not, at least some progress must have been
- made.
- .P
- Where this volume of POSIX.1\(hy2017 requires \-1 to be returned and
- .IR errno
- set to
- .BR [EAGAIN] ,
- most historical implementations return zero (with the O_NDELAY
- flag set, which is the historical predecessor of O_NONBLOCK, but is not
- itself in this volume of POSIX.1\(hy2017). The error indications in this volume of POSIX.1\(hy2017 were chosen so that an
- application can distinguish these cases from end-of-file. While
- \fIwrite\fR()
- cannot receive an indication of end-of-file,
- \fIread\fR()
- can, and the two functions have similar return values. Also, some
- existing systems (for example, Eighth Edition) permit a write of zero
- bytes to
- mean that the reader should get an end-of-file indication; for those
- systems, a return value of zero from
- \fIwrite\fR()
- indicates a successful write of an end-of-file indication.
- .P
- Implementations are allowed, but not required, to perform error
- checking for
- \fIwrite\fR()
- requests of zero bytes.
- .P
- The concept of a
- {PIPE_MAX}
- limit (indicating the maximum number of bytes that can be written to a
- pipe in a single operation) was considered, but rejected, because this
- concept would unnecessarily limit application writing.
- .P
- See also the discussion of O_NONBLOCK in
- \fIread\fR().
- .P
- Writes can be serialized with respect to other reads and writes. If a
- \fIread\fR()
- of file data can be proven (by any means) to occur after a
- \fIwrite\fR()
- of the data, it must reflect that
- \fIwrite\fR(),
- even if the calls are made by different processes. A similar
- requirement applies to multiple write operations to the same file
- position. This is needed to guarantee the propagation of data from
- \fIwrite\fR()
- calls to subsequent
- \fIread\fR()
- calls. This requirement is particularly significant for networked file
- systems, where some caching schemes violate these semantics.
- .P
- Note that this is specified in terms of
- \fIread\fR()
- and
- \fIwrite\fR().
- The XSI extensions
- \fIreadv\fR()
- and
- \fIwritev\fR()
- also obey these semantics. A new ``high-performance'' write
- analog that did not follow these serialization requirements would also
- be permitted by this wording. This volume of POSIX.1\(hy2017 is also silent about any effects of
- application-level caching (such as that done by
- .IR stdio ).
- .P
- This volume of POSIX.1\(hy2017 does not specify the value of the file offset after an error is
- returned; there are too many cases. For programming errors, such as
- .BR [EBADF] ,
- the concept is meaningless since no file is involved. For errors that
- are detected immediately, such as
- .BR [EAGAIN] ,
- clearly the pointer should not change. After an interrupt or hardware
- error, however, an updated value would be very useful and is the
- behavior of many implementations.
- .P
- This volume of POSIX.1\(hy2017 does not specify the behavior of concurrent writes to a
- regular file from multiple threads, except that each write
- is atomic (see
- .IR "Section 2.9.7" ", " "Thread Interactions with Regular File Operations").
- Applications should use some form of concurrency control.
- .P
- This volume of POSIX.1\(hy2017 intentionally does not specify any
- \fIpwrite\fR()
- errors related to pipes, FIFOs, and sockets other than
- .BR [ESPIPE] .
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIchmod\fR\^(\|)",
- .IR "\fIcreat\fR\^(\|)",
- .IR "\fIdup\fR\^(\|)",
- .IR "\fIfcntl\fR\^(\|)",
- .IR "\fIgetrlimit\fR\^(\|)",
- .IR "\fIlseek\fR\^(\|)",
- .IR "\fIopen\fR\^(\|)",
- .IR "\fIpipe\fR\^(\|)",
- .IR "\fIread\fR\^(\|)",
- .IR "\fIulimit\fR\^(\|)",
- .IR "\fIwritev\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<limits.h>\fP",
- .IR "\fB<stropts.h>\fP",
- .IR "\fB<sys_uio.h>\fP",
- .IR "\fB<unistd.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .