2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
287 lines
7 KiB
Groff
287 lines
7 KiB
Groff
.\" $NetBSD: write.2,v 1.32 2010/04/05 07:53:47 wiz 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 April 3, 2010
|
|
.Dt WRITE 2
|
|
.Os
|
|
.Sh NAME
|
|
.Nm write ,
|
|
.Nm writev ,
|
|
.Nm pwrite ,
|
|
.Nm pwritev
|
|
.Nd write output
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.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"
|
|
.In sys/uio.h
|
|
.Ft ssize_t
|
|
.Fn writev "int d" "const struct iovec *iov" "int iovcnt"
|
|
.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 in
|
|
the file without modifying the file pointer.
|
|
.Pp
|
|
For
|
|
.Fn writev
|
|
and
|
|
.Fn pwritev ,
|
|
the
|
|
.Fa iovec
|
|
structure is defined as:
|
|
.Pp
|
|
.Bd -literal -offset indent -compact
|
|
struct iovec {
|
|
void *iov_base;
|
|
size_t iov_len;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Each
|
|
.Fa 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.
|
|
.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 super-user, 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 super-user.
|
|
.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.
|
|
.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 ERRORS
|
|
.Fn write ,
|
|
.Fn writev ,
|
|
.Fn pwrite ,
|
|
and
|
|
.Fn pwritev
|
|
will fail and the file pointer will remain unchanged if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EAGAIN
|
|
The file was marked for non-blocking I/O,
|
|
and no data could be written immediately.
|
|
.It Bq Er EBADF
|
|
.Fa d
|
|
is not a valid descriptor open for writing.
|
|
.It Bq Er EDQUOT
|
|
The user's quota of disk blocks on the file system
|
|
containing the file has been exhausted.
|
|
.It Bq Er EFAULT
|
|
Part of
|
|
.Fa iov
|
|
or data to be written to the file
|
|
points outside the process's allocated address space.
|
|
.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 EINTR
|
|
A signal was received before any data could be written to a slow
|
|
device.
|
|
See
|
|
.Xr sigaction 2
|
|
for more information on the interaction between signals and system
|
|
calls.
|
|
.It Bq Er EINVAL
|
|
The pointer associated with
|
|
.Fa d
|
|
was negative; or
|
|
the total length of the I/O is more than can be expressed by the ssize_t
|
|
return value.
|
|
.It Bq Er EIO
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
.It Bq Er ENOSPC
|
|
There is no free space remaining on the file system
|
|
containing the file.
|
|
.It Bq Er EPIPE
|
|
An attempt is made to write to a pipe that is not open
|
|
for reading by any process; or
|
|
an attempt is made to write to a socket of type
|
|
.Dv SOCK_STREAM
|
|
that is not connected to a peer socket.
|
|
.El
|
|
.Pp
|
|
In addition,
|
|
.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} ;
|
|
or one of the
|
|
.Fa iov_len
|
|
values in the
|
|
.Fa iov
|
|
array was negative; or
|
|
the sum of the
|
|
.Fa iov_len
|
|
values in the
|
|
.Fa iov
|
|
array overflowed a 32-bit integer.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn pwrite
|
|
and
|
|
.Fn pwritev
|
|
calls may also return the following errors:
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The specified file offset is invalid.
|
|
.It Bq Er ESPIPE
|
|
The file descriptor is associated with a pipe, socket, or FIFO.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr fcntl 2 ,
|
|
.Xr lseek 2 ,
|
|
.Xr open 2 ,
|
|
.Xr pipe 2 ,
|
|
.Xr poll 2 ,
|
|
.Xr select 2 ,
|
|
.Xr sigaction 2
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn write
|
|
function is expected to conform to
|
|
.St -p1003.1-88 .
|
|
The
|
|
.Fn writev
|
|
and
|
|
.Fn pwrite
|
|
functions conform to
|
|
.St -xpg4.2 .
|
|
.Sh HISTORY
|
|
The
|
|
.Fn pwritev
|
|
function call
|
|
appeared in
|
|
.Nx 1.4 .
|
|
The
|
|
.Fn pwrite
|
|
function call
|
|
appeared in
|
|
.At V.4 .
|
|
The
|
|
.Fn writev
|
|
function call
|
|
appeared in
|
|
.Bx 4.2 .
|
|
The
|
|
.Fn write
|
|
function call appeared in
|
|
.At v2 .
|
|
.Sh CAVEATS
|
|
Error checks should explicitly test for \-1.
|
|
Code such as
|
|
.Bd -literal
|
|
while ((nr = write(fd, buf, sizeof(buf))) \*[Gt] 0)
|
|
.Ed
|
|
.Pp
|
|
is not maximally portable, as some platforms allow for
|
|
.Va nbytes
|
|
to range between
|
|
.Dv SSIZE_MAX
|
|
and
|
|
.Dv SIZE_MAX
|
|
\- 2, in which case the return value of an error-free
|
|
.Fn write
|
|
may appear as a negative number distinct from \-1.
|
|
Proper loops should use
|
|
.Bd -literal
|
|
while ((nr = write(fd, buf, sizeof(buf))) != -1 \*[Am]\*[Am] nr != 0)
|
|
.Ed
|