projects / unix-history / blobdiff
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
BSD 4_3_Net_2 release
[unix-history] / usr / src / lib / libc / sys / write.2
diff --git a/usr/src/lib/libc/sys/write.2 b/usr/src/lib/libc/sys/write.2
index af35a6b..f7d1f05 100644 (file)
--- a/usr/src/lib/libc/sys/write.2
+++ b/usr/src/lib/libc/sys/write.2
@@ -1,171 +1,203 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1980, 1991 Regents of the University of California.
+.\" All rights reserved.
 .\"
 .\"
-.\"    @(#)write.2     6.5 (Berkeley) 5/14/86
+.\" 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. 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.
 .\"
 .\"
-.TH WRITE 2 "May 14, 1986"
-.UC 4
-.SH NAME
-write, writev \- write output
-.SH SYNOPSIS
-.nf
-.ft B
-cc = write(d, buf, nbytes)
-int cc, d;
-char *buf;
-int nbytes;
-.PP
-.ft B
-#include <sys/types.h>
-#include <sys/uio.h>
-.PP
-.ft B
-cc = writev(d, iov, iovcnt)
-int cc, d;
-struct iovec *iov;
-int iovcnt;
-.fi
-.SH DESCRIPTION
-.I Write
+.\" 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    6.6 (Berkeley) 3/10/91
+.\"
+.Dd March 10, 1991
+.Dt WRITE 2
+.Os BSD 4
+.Sh NAME
+.Nm write ,
+.Nm writev
+.Nd write output
+.Sh SYNOPSIS
+.Fd #include <unistd.h>
+.Fd #include <sys/types.h>
+.Fd #include <sys/uio.h>
+.Ft ssize_t
+.Fn write "int d" "const char *buf" "size_t nbytes"
+.Ft int
+.Fn writev "int d" "struct iovec *iov" "int iovcnt"
+.Sh DESCRIPTION
+.Fn Write
 attempts to write
 attempts to write
-.I nbytes
+.Fa nbytes
 of data to the object referenced by the descriptor
 of data to the object referenced by the descriptor
-.I d
+.Fa d
 from the buffer pointed to by
 from the buffer pointed to by
-.IR buf .
-.I Writev
+.Fa buf .
+.Fn Writev
 performs the same action, but gathers the output data
 from the 
 performs the same action, but gathers the output data
 from the 
-.I iovcnt
+.Fa iovcnt
 buffers specified by the members of the
 buffers specified by the members of the
-.I iov
-array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
-.PP
+.Fa iov
+array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
+.Pp
 For 
 For 
-.IR writev ,
+.Fn writev ,
 the 
 the 
-.I iovec
-structure is defined as
-.PP
-.nf
-.RS
-.DT
+.Fa iovec
+structure is defined as:
+.Bd -literal -offset indent -compact
 struct iovec {
        caddr_t iov_base;
        int     iov_len;
 };
 struct iovec {
        caddr_t iov_base;
        int     iov_len;
 };
-.RE
-.fi
-.PP
+.Ed
+.Pp
 Each 
 Each 
-.I iovec
+.Fa iovec
 entry specifies the base address and length of an area
 in memory from which data should be written.
 entry specifies the base address and length of an area
 in memory from which data should be written.
-.I Writev
+.Fn Writev
 will always write a complete area before proceeding
 to the next.
 will always write a complete area before proceeding
 to the next.
-.PP
-On objects capable of seeking, the \fIwrite\fP starts at a position
+.Pp
+On objects capable of seeking, the
+.Fn write
+starts at a position
 given by the pointer associated with
 given by the pointer associated with
-.IR d ,
+.Fa d ,
 see
 see
-.IR lseek (2).
+.Xr lseek 2 .
 Upon return from
 Upon return from
-.IR write ,
-the pointer is incremented by the number of bytes actually written.
-.PP
+.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.
 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
+.Pp
 If the real user is not the super-user, then
 If the real user is not the super-user, then
-.I write
+.Fn write
 clears the set-user-id bit on a file.
 This prevents penetration of system security
 by a user who
 clears the set-user-id bit on a file.
 This prevents penetration of system security
 by a user who
-\*(lqcaptures\*(rq a writable set-user-id file
+.Dq captures
+a writable set-user-id file
 owned by the super-user.
 owned by the super-user.
-.PP
+.Pp
 When using non-blocking I/O on objects such as sockets that are subject
 to flow control,
 When using non-blocking I/O on objects such as sockets that are subject
 to flow control,
-.I write
+.Fn write
 and
 and
-.I writev
+.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.
 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 VALUE
-Upon successful completion the number of bytes actually written
-is returned.  Otherwise a \-1 is returned and the global variable
-.I errno
+.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.
 is set to indicate the error.
-.SH ERRORS
-.I Write
+.Sh ERRORS
+.Fn Write
 and
 and
-.I writev
-will fail and the file pointer will remain unchanged if one or more
-of the following are true:
-.TP 15
-[EBADF]
-\fID\fP is not a valid descriptor open for writing.
-.TP 15
-[EPIPE]
+.Fn writev
+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 EPIPE
 An attempt is made to write to a pipe that is not open
 for reading by any process.
 An attempt is made to write to a pipe that is not open
 for reading by any process.
-.TP 15
-[EPIPE]
-An attempt is made to write to a socket of type SOCK_STREAM
+.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.
 that is not connected to a peer socket.
-.TP 15
-[EFBIG]
+.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.
 An attempt was made to write a file that exceeds the process's
 file size limit or the maximum file size.
-.TP 15
-[EFAULT]
-Part of \fIiov\fP or data to be written to the file
+.It Bq Er EFAULT
+Part of
+.Fa iov
+or data to be written to the file
 points outside the process's allocated address space.
 points outside the process's allocated address space.
-.TP 15
-[EINVAL]
+.It Bq Er EINVAL
 The pointer associated with
 The pointer associated with
-.I d
+.Fa d
 was negative.
 was negative.
-.TP 15
-[ENOSPC]
+.It Bq Er ENOSPC
 There is no free space remaining on the file system
 containing the file.
 There is no free space remaining on the file system
 containing the file.
-.TP 15
-[EDQUOT]
+.It Bq Er EDQUOT
 The user's quota of disk blocks on the file system
 containing the file has been exhausted.
 The user's quota of disk blocks on the file system
 containing the file has been exhausted.
-.TP 15
-[EIO]
+.It Bq Er EIO
 An I/O error occurred while reading from or writing to the file system.
 An I/O error occurred while reading from or writing to the file system.
-.TP 15
-[EWOULDBLOCK]
+.It Bq Er EWOULDBLOCK
 The file was marked for non-blocking I/O,
 and no data could be written immediately.
 The file was marked for non-blocking I/O,
 and no data could be written immediately.
-.PP
+.El
+.Pp
 In addition, 
 In addition, 
-.I writev
+.Fn writev
 may return one of the following errors:
 may return one of the following errors:
-.TP 15
-[EINVAL]
-.I Iovcnt
+.Bl -tag -width Er
+.It Bq Er EINVAL
+.Fa Iovcnt
 was less than or equal to 0, or greater than 16.
 was less than or equal to 0, or greater than 16.
-.TP 15
-[EINVAL]
+.It Bq Er EINVAL
 One of the
 One of the
-.I iov_len
+.Fa iov_len
 values in the
 values in the
-.I iov
+.Fa iov
 array was negative.
 array was negative.
-.TP 15
-[EINVAL]
+.It Bq Er EINVAL
 The sum of the
 The sum of the
-.I iov_len
+.Fa iov_len
 values in the
 values in the
-.I iov
+.Fa iov
 array overflowed a 32-bit integer.
 array overflowed a 32-bit integer.
-.SH "SEE ALSO"
-fcntl(2), lseek(2), open(2), pipe(2), select(2)
+.El
+.Sh SEE ALSO
+.Xr fcntl 2 ,
+.Xr lseek 2 ,
+.Xr open 2 ,
+.Xr pipe 2 ,
+.Xr select 2
+.Sh STANDARDS
+.Fn Write
+is expected to conform to IEEE Std 1003.1-1988
+.Pq Dq Tn POSIX .
+.Sh HISTORY
+The
+.Fn writev
+function call
+appeared in
+.Bx 4.2 .
+A
+.Nm write
+function call
+appeared in
+Version 6 AT&T UNIX.
Continuous source code history from original PDP-7 UNIX to FreeBSD 2, the first fully unencumbered FreeBSD release.