lib/libcr/sys/write.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)write.2     8.5 (Berkeley) 4/2/94
  33 .\" $FreeBSD: src/lib/libc/sys/write.2,v 1.12.2.8 2002/10/13 17:42:14 schweikh Exp $
  34 .\"
  35 .Dd April 2, 1994
  36 .Dt WRITE 2
  37 .Os
  38 .Sh NAME
  39 .Nm write ,
  40 .Nm writev ,
  41 .Nm pwrite
  42 .Nd write output
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In sys/uio.h
  48 .In unistd.h
  49 .Ft ssize_t
  50 .Fn write "int d" "const void *buf" "size_t nbytes"
  51 .Ft ssize_t
  52 .Fn writev "int d" "const struct iovec *iov" "int iovcnt"
  53 .Ft ssize_t
  54 .Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset"
  55 .Sh DESCRIPTION
  56 .Fn Write
  57 attempts to write
  58 .Fa nbytes
  59 of data to the object referenced by the descriptor
  60 .Fa d
  61 from the buffer pointed to by
  62 .Fa buf .
  63 .Fn Writev
  64 performs the same action, but gathers the output data
  65 from the
  66 .Fa iovcnt
  67 buffers specified by the members of the
  68 .Fa iov
  69 array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
  70 .Fn Pwrite
  71 performs the same function, but writes to the specified position in
  72 the file without modifying the file pointer.
  73 .Pp
  74 For
  75 .Fn writev ,
  76 the
  77 .Fa iovec
  78 structure is defined as:
  79 .Pp
  80 .Bd -literal -offset indent -compact
  81 struct iovec {
  82         char   *iov_base;  /* Base address. */
  83         size_t iov_len;    /* Length. */
  84 };
  85 .Ed
  86 .Pp
  87 Each
  88 .Fa iovec
  89 entry specifies the base address and length of an area
  90 in memory from which data should be written.
  91 .Fn Writev
  92 will always write a complete area before proceeding
  93 to the next.
  94 .Pp
  95 On objects capable of seeking, the
  96 .Fn write
  97 starts at a position
  98 given by the pointer associated with
  99 .Fa d ,
 100 see
 101 .Xr lseek 2 .
 102 Upon return from
 103 .Fn write ,
 104 the pointer is incremented by the number of bytes which were written.
 105 .Pp
 106 Objects that are not capable of seeking always write from the current
 107 position.  The value of the pointer associated with such an object
 108 is undefined.
 109 .Pp
 110 If the real user is not the super-user, then
 111 .Fn write
 112 clears the set-user-id bit on a file.
 113 This prevents penetration of system security
 114 by a user who
 115 .Dq captures
 116 a writable set-user-id file
 117 owned by the super-user.
 118 .Pp
 119 When using non-blocking I/O on objects such as sockets that are subject
 120 to flow control,
 121 .Fn write
 122 and
 123 .Fn writev
 124 may write fewer bytes than requested;
 125 the return value must be noted,
 126 and the remainder of the operation should be retried when possible.
 127 .Sh RETURN VALUES
 128 Upon successful completion the number of bytes which were written
 129 is returned.  Otherwise a -1 is returned and the global variable
 130 .Va errno
 131 is set to indicate the error.
 132 .Sh ERRORS
 133 .Fn Write ,
 134 .Fn writev ,
 135 and
 136 .Fn pwrite
 137 will fail and the file pointer will remain unchanged if:
 138 .Bl -tag -width Er
 139 .It Bq Er EBADF
 140 .Fa D
 141 is not a valid descriptor open for writing.
 142 .It Bq Er EPIPE
 143 An attempt is made to write to a pipe that is not open
 144 for reading by any process.
 145 .It Bq Er EPIPE
 146 An attempt is made to write to a socket of type
 147 .Dv SOCK_STREAM
 148 that is not connected to a peer socket.
 149 .It Bq Er EFBIG
 150 An attempt was made to write a file that exceeds the process's
 151 file size limit or the maximum file size.
 152 .It Bq Er EFAULT
 153 Part of
 154 .Fa iov
 155 or data to be written to the file
 156 points outside the process's allocated address space.
 157 .It Bq Er EINVAL
 158 The pointer associated with
 159 .Fa d
 160 was negative.
 161 .It Bq Er ENOSPC
 162 There is no free space remaining on the file system
 163 containing the file.
 164 .It Bq Er EDQUOT
 165 The user's quota of disk blocks on the file system
 166 containing the file has been exhausted.
 167 .It Bq Er EIO
 168 An I/O error occurred while reading from or writing to the file system.
 169 .It Bq Er EINTR
 170 A signal interrupted the write before it could be completed.
 171 .It Bq Er EAGAIN
 172 The file was marked for non-blocking I/O,
 173 and no data could be written immediately.
 174 .It Bq Er EROFS
 175 An attempt was made to write over a disk label area at the beginning
 176 of a disk.
 177 Use
 178 .Xr disklabel 8
 179 .Fl W
 180 to enable writing on the disk label area.
 181 .El
 182 .Pp
 183 In addition,
 184 .Fn writev
 185 may return one of the following errors:
 186 .Bl -tag -width Er
 187 .It Bq Er EDESTADDRREQ
 188 The destination is no longer available when writing to a
 189 .Ux
 190 domain datagram socket on which
 191 .Xr connect 2
 192 had been used to set a destination address.
 193 .It Bq Er EINVAL
 194 .Fa Iovcnt
 195 was less than or equal to 0, or greater than
 196 .Dv UIO_MAXIOV .
 197 .It Bq Er EINVAL
 198 One of the
 199 .Fa iov_len
 200 values in the
 201 .Fa iov
 202 array was negative.
 203 .It Bq Er EINVAL
 204 The sum of the
 205 .Fa iov_len
 206 values in the
 207 .Fa iov
 208 array overflowed a 32-bit integer.
 209 .It Bq Er ENOBUFS
 210 The mbuf pool has been completely exhausted when writing to a socket.
 211 .El
 212 .Pp
 213 The
 214 .Fn pwrite
 215 call may also return the following errors:
 216 .Bl -tag -width Er
 217 .It Bq Er EINVAL
 218 The specified file offset is invalid.
 219 .It Bq Er ESPIPE
 220 The file descriptor is associated with a pipe, socket, or FIFO.
 221 .El
 222 .Sh SEE ALSO
 223 .Xr fcntl 2 ,
 224 .Xr lseek 2 ,
 225 .Xr open 2 ,
 226 .Xr pipe 2 ,
 227 .Xr select 2
 228 .Sh STANDARDS
 229 The
 230 .Fn write
 231 function call is expected to conform to
 232 .St -p1003.1-90 .
 233 The
 234 .Fn writev
 235 and
 236 .Fn pwrite
 237 functions are expected to conform to
 238 .St -xpg4.2 .
 239 .Sh HISTORY
 240 The
 241 .Fn pwrite
 242 function call
 243 appeared in
 244 .At V.4 .
 245 The
 246 .Fn writev
 247 function call
 248 appeared in
 249 .Bx 4.2 .
 250 A
 251 .Fn write
 252 function call appeared in
 253 .At v6 .