diff options
Diffstat (limited to 'static/openbsd/man2/write.2')
| -rw-r--r-- | static/openbsd/man2/write.2 | 329 |
1 files changed, 329 insertions, 0 deletions
diff --git a/static/openbsd/man2/write.2 b/static/openbsd/man2/write.2 new file mode 100644 index 00000000..cf7a6fba --- /dev/null +++ b/static/openbsd/man2/write.2 @@ -0,0 +1,329 @@ +.\" $OpenBSD: write.2,v 1.45 2023/02/05 12:33:17 jsg Exp $ +.\" $NetBSD: write.2,v 1.6 1995/02/27 12:39:43 cgd Exp $ +.\" +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)write.2 8.5 (Berkeley) 4/2/94 +.\" +.Dd $Mdocdate: February 5 2023 $ +.Dt WRITE 2 +.Os +.Sh NAME +.Nm write , +.Nm writev , +.Nm pwrite , +.Nm pwritev +.Nd write output +.Sh SYNOPSIS +.In unistd.h +.Ft ssize_t +.Fn write "int d" "const void *buf" "size_t nbytes" +.Ft ssize_t +.Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset" +.Pp +.In sys/uio.h +.Ft ssize_t +.Fn writev "int d" "const struct iovec *iov" "int iovcnt" +.In sys/types.h +.In sys/uio.h +.Ft ssize_t +.Fn pwritev "int d" "const struct iovec *iov" "int iovcnt" "off_t offset" +.Sh DESCRIPTION +.Fn write +attempts to write +.Fa nbytes +of data to the object referenced by the descriptor +.Fa d +from the buffer pointed to by +.Fa buf . +.Fn writev +performs the same action, but gathers the output data from the +.Fa iovcnt +buffers specified by the members of the +.Fa iov +array: iov[0], iov[1], ..., iov[iovcnt-1]. +.Fn pwrite +and +.Fn pwritev +perform the same functions, but write to the specified position +.Fa offset +in the file without modifying the file pointer. +.Pp +For +.Fn writev +and +.Fn pwritev , +the +.Vt iovec +structure is defined as: +.Bd -literal -offset indent +struct iovec { + void *iov_base; + size_t iov_len; +}; +.Ed +.Pp +Each +.Vt iovec +entry specifies the base address and length of an area +in memory from which data should be written. +.Fn writev +and +.Fn pwritev +will always write a complete area before proceeding to the next. +.Pp +On objects capable of seeking, the +.Fn write +starts at a position given by the pointer associated with +.Fa d +(see +.Xr lseek 2 ) . +Upon return from +.Fn write , +the pointer is incremented by the number of bytes which were written. +If a file was opened with the +.Dv O_APPEND +flag (see +.Xr open 2 ) , +calls to +.Fn write +or +.Fn writev +will automatically set the pointer to the end of the file before writing. +.Pp +Objects that are not capable of seeking always write from the current +position. +The value of the pointer associated with such an object is undefined. +.Pp +If the real user is not the superuser, then +.Fn write +clears the set-user-ID bit on a file. +This prevents penetration of system security by a user who +.Dq captures +a writable set-user-ID file owned by the superuser. +.Pp +If +.Fn write +succeeds, it will update the st_ctime and st_mtime fields of the file's +meta-data (see +.Xr stat 2 ) . +.Pp +When using non-blocking I/O on objects such as sockets that are subject +to flow control, +.Fn write +and +.Fn writev +may write fewer bytes than requested; the return value must be noted, +and the remainder of the operation should be retried when possible. +.Pp +Note that +.Fn writev +and +.Fn pwritev +will fail if the value of +.Fa iovcnt +exceeds the constant +.Dv IOV_MAX . +.Sh RETURN VALUES +Upon successful completion the number of bytes which were written +is returned. +Otherwise, a \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Sh EXAMPLES +A typical loop allowing partial writes looks like this: +.Bd -literal +const char *buf; +size_t bsz, off; +ssize_t nw; +int d; + +for (off = 0; off < bsz; off += nw) + if ((nw = write(d, buf + off, bsz - off)) == 0 || nw == -1) + err(1, "write"); +.Ed +.Sh ERRORS +.Fn write , +.Fn pwrite , +.Fn writev , +and +.Fn pwritev +will fail and the file pointer will remain unchanged if: +.Bl -tag -width Er +.It Bq Er EBADF +.Fa d +is not a valid descriptor open for writing. +.It Bq Er EFBIG +An attempt was made to write a file that exceeds the process's +file size limit or the maximum file size. +.It Bq Er ENOSPC +There is no free space remaining on the file system containing the file. +.It Bq Er EDQUOT +The user's quota of disk blocks on the file system containing the file +has been exhausted. +.It Bq Er EINTR +A write to a slow device +(i.e. one that might block for an arbitrary amount of time) +was interrupted by the delivery of a signal +before any data could be written. +.It Bq Er EIO +An I/O error occurred while reading from or writing to the file system. +.It Bq Er EFAULT +Part of +.Fa buf +points outside the process's allocated address space. +.El +.Pp +In addition, +.Fn write +and +.Fn writev +may return the following errors: +.Bl -tag -width Er +.It Bq Er EPIPE +An attempt is made to write to a pipe that is not open +for reading by any process. +.It Bq Er EPIPE +An attempt is made to write to a socket of type +.Dv SOCK_STREAM +that is not connected to a peer socket. +.It Bq Er EAGAIN +The file was marked for non-blocking I/O, and no data could be +written immediately. +.It Bq Er ENETDOWN +The destination address specified a network that is down. +.It Bq Er EDESTADDRREQ +The destination is no longer available when writing to a +.Ux Ns -domain +datagram socket on which +.Xr connect 2 +had been used to set a destination address. +.It Bq Er EIO +The process is a member of a background process attempting to write +to its controlling terminal, +.Dv TOSTOP +is set on the terminal, +the process isn't ignoring the +.Dv SIGTTOUT +signal and the thread isn't blocking the +.Dv SIGTTOUT +signal, +and either the process was created with +.Xr vfork 2 +and hasn't successfully executed one of the exec functions or +the process group is orphaned. +.El +.Pp +.Fn write +and +.Fn pwrite +may return the following error: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa nbytes +was larger than +.Dv SSIZE_MAX . +.El +.Pp +.Fn pwrite +and +.Fn pwritev +may return the following error: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa offset +was negative. +.It Bq Er ESPIPE +.Fa d +is associated with a pipe, socket, FIFO, or tty. +.El +.Pp +.Fn writev +and +.Fn pwritev +may return one of the following errors: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa iovcnt +was less than or equal to 0, or greater than +.Dv IOV_MAX . +.It Bq Er EINVAL +The sum of the +.Fa iov_len +values in the +.Fa iov +array overflowed an +.Vt ssize_t . +.It Bq Er EFAULT +Part of +.Fa iov +points outside the process's allocated address space. +.It Bq Er ENOBUFS +The system lacked sufficient buffer space or a queue was full. +.El +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr lseek 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr poll 2 , +.Xr select 2 , +.Xr termios 4 +.Sh STANDARDS +The +.Fn write , +.Fn writev , +and +.Fn pwrite +functions conform to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn write +function call appeared in +.At v1 , +.Fn pwrite +in +.At V.4 , +.Fn writev +in +.Bx 4.1c , +and +.Fn pwritev +in +.Ox 2.7 . +.Sh CAVEATS +Error checks should explicitly test for \-1. +On some platforms, if +.Fa nbytes +is larger than +.Dv SSIZE_MAX +but smaller than +.Dv SIZE_MAX +\- 2, the return value of an error-free call +may appear as a negative number distinct from \-1. |