bsd/man/man2/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.7 2001/12/14 18:34:02 ru Exp $
  34 .\"
  35 .Dd April 2, 1994
  36 .Dt WRITE 2
  37 .Os
  38 .Sh NAME
  39 .Nm pwrite ,
  40 .Nm write ,
  41 .Nm writev
  42 .Nd write output
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In unistd.h
  47 .Ft ssize_t
  48 .Fo pwrite
  49 .Fa "int fildes"
  50 .Fa "const void *buf"
  51 .Fa "size_t nbyte"
  52 .Fa "off_t offset"
  53 .Fc
  54 .Ft ssize_t
  55 .Fo write
  56 .Fa "int fildes"
  57 .Fa "const void *buf"
  58 .Fa "size_t nbyte"
  59 .Fc
  60 .In sys/uio.h
  61 .Ft ssize_t
  62 .Fo writev
  63 .Fa "int fildes"
  64 .Fa "const struct iovec *iov"
  65 .Fa "int iovcnt"
  66 .Fc
  67 .Sh DESCRIPTION
  68 .Fn Write
  69 attempts to write
  70 .Fa nbyte
  71 of data to the object referenced by the descriptor
  72 .Fa fildes
  73 from the buffer pointed to by
  74 .Fa buf .
  75 .Fn Writev
  76 performs the same action, but gathers the output data
  77 from the
  78 .Fa iovcnt
  79 buffers specified by the members of the
  80 .Fa iov
  81 array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
  82 .Fn Pwrite
  83 performs the same function, but writes to the specified position in
  84 the file without modifying the file pointer.
  85 .Pp
  86 For
  87 .Fn writev ,
  88 the
  89 .Fa iovec
  90 structure is defined as:
  91 .Pp
  92 .Bd -literal -offset indent -compact
  93 struct iovec {
  94         char   *iov_base;  /* Base address. */
  95         size_t iov_len;    /* Length. */
  96 };
  97 .Ed
  98 .Pp
  99 Each
 100 .Fa iovec
 101 entry specifies the base address and length of an area
 102 in memory from which data should be written.
 103 .Fn Writev
 104 will always write a complete area before proceeding
 105 to the next.
 106 .Pp
 107 On objects capable of seeking, the
 108 .Fn write
 109 starts at a position
 110 given by the pointer associated with
 111 .Fa fildes ,
 112 see
 113 .Xr lseek 2 .
 114 Upon return from
 115 .Fn write ,
 116 the pointer is incremented by the number of bytes which were written.
 117 .Pp
 118 Objects that are not capable of seeking always write from the current
 119 position.  The value of the pointer associated with such an object
 120 is undefined.
 121 .Pp
 122 If the real user is not the super-user, then
 123 .Fn write
 124 clears the set-user-id bit on a file.
 125 This prevents penetration of system security
 126 by a user who
 127 .Dq captures
 128 a writable set-user-id file
 129 owned by the super-user.
 130 .Pp
 131 When using non-blocking I/O on objects, such as sockets,
 132 that are subject to flow control,
 133 .Fn write
 134 and
 135 .Fn writev
 136 may write fewer bytes than requested;
 137 the return value must be noted,
 138 and the remainder of the operation should be retried when possible.
 139 .Sh RETURN VALUES
 140 Upon successful completion the number of bytes
 141 which were written is returned.
 142 Otherwise, a -1 is returned and the global variable
 143 .Va errno
 144 is set to indicate the error.
 145 .Sh ERRORS
 146 The
 147 .Fn write ,
 148 .Fn writev ,
 149 and
 150 .Fn pwrite
 151 system calls will fail and the file pointer will remain unchanged if:
 152 .Bl -tag -width Er
 153 .\" ===========
 154 .It Bq Er EDQUOT
 155 The user's quota of disk blocks on the file system
 156 containing the file is exhausted.
 157 .\" ===========
 158 .It Bq Er EFAULT
 159 Part of
 160 .Fa iov
 161 or data to be written to the file
 162 points outside the process's allocated address space.
 163 .\" ===========
 164 .It Bq Er EINVAL
 165 The pointer associated with
 166 .Fa fildes
 167 is negative.
 168 .El
 169 .Pp
 170 The
 171 .Fn write
 172 and
 173 .Fn pwrite
 174 system calls will fail and the file pointer will remain unchanged if:
 175 .Bl -tag -width Er
 176 .\" ===========
 177 .It Bq Er EAGAIN
 178 The file is marked for non-blocking I/O,
 179 and no data could be written immediately.
 180 .\" ===========
 181 .It Bq Er EBADF
 182 .Fa fildes
 183 is not a valid file descriptor open for writing.
 184 .\" ===========
 185 .It Bq Er ECONNRESET
 186 A write is attempted on a socket that is not connected.
 187 .\" ===========
 188 .It Bq Er EFBIG
 189 An attempt is made to write a file that exceeds the process's
 190 file size limit or the maximum file size.
 191 .\" ===========
 192 .It Bq Er EFBIG
 193 The file is a regular file,
 194 .Fa nbyte
 195 is greater than 0,
 196 and the starting position is greater than or equal
 197 to the offset maximum established in the open file description
 198 associated with
 199 .Fa fildes .
 200 .\" ===========
 201 .It Bq Er EINTR
 202 A signal interrupts the write before it could be completed.
 203 .\" ===========
 204 .It Bq Er EIO
 205 An I/O error occurs while reading from or writing to the file system.
 206 .\" ===========
 207 .It Bq Er ENETDOWN
 208 A write is attempted on a socket
 209 and the local network interface used to reach the destination is down.
 210 .\" ===========
 211 .It Bq Er ENETUNREACH
 212 A write is attempted on a socket and no route to the network is present.
 213 .\" ===========
 214 .It Bq Er ENOSPC
 215 There is no free space remaining on the file system containing the file.
 216 .\" ===========
 217 .It Bq Er ENXIO
 218 A request is made of a nonexistent device,
 219 or the request is outside the capabilities of the device.
 220 .\" ===========
 221 .It Bq Er EPIPE
 222 An attempt is made to write to a pipe that is not open
 223 for reading by any process.
 224 .\" ===========
 225 .It Bq Er EPIPE
 226 An attempt is made to write to a socket of type
 227 .Dv SOCK_STREAM
 228 that is not connected to a peer socket.
 229 .El
 230 .Pp
 231 The
 232 .Fn write
 233 and
 234 .Fn writev
 235 calls may also return the following errors:
 236 .Bl -tag -width Er
 237 .\" ===========
 238 .It Bq Er EAGAIN
 239 See EWOULDBLOCK, below.
 240 .\" ===========
 241 .It Bq Er EWOULDBLOCK
 242 The file descriptor is for a socket, is marked O_NONBLOCK,
 243 and write would block.
 244 The exact error code depends on the protocol,
 245 but EWOULDBLOCK is more common.
 246 .El
 247 .Pp
 248 In addition,
 249 .Fn writev
 250 may return one of the following errors:
 251 .Bl -tag -width Er
 252 .\" ===========
 253 .It Bq Er EDESTADDRREQ
 254 The destination is no longer available when writing to a
 255 .Ux
 256 domain datagram socket on which
 257 .Xr connect 2
 258 had been used to set a destination address.
 259 .\" ===========
 260 .It Bq Er EINVAL
 261 .Fa Iovcnt
 262 is less than or equal to 0, or greater than
 263 .Dv UIO_MAXIOV .
 264 .\" ===========
 265 .It Bq Er EINVAL
 266 One of the
 267 .Fa iov_len
 268 values in the
 269 .Fa iov
 270 array is negative.
 271 .\" ===========
 272 .It Bq Er EINVAL
 273 The sum of the
 274 .Fa iov_len
 275 values in the
 276 .Fa iov
 277 array overflows a 32-bit integer.
 278 .\" ===========
 279 .It Bq Er ENOBUFS
 280 The mbuf pool has been completely exhausted when writing to a socket.
 281 .El
 282 .Pp
 283 The
 284 .Fn pwrite
 285 call may also return the following errors:
 286 .Bl -tag -width Er
 287 .\" ===========
 288 .It Bq Er EINVAL
 289 The specified file offset is invalid.
 290 .\" ===========
 291 .It Bq Er ESPIPE
 292 The file descriptor is associated with a pipe, socket, or FIFO.
 293 .El
 294 .Sh LEGACY SYNOPSIS
 295 .Fd #include <sys/types.h>
 296 .Fd #include <sys/uio.h>
 297 .Fd #include <unistd.h>
 298 .Pp
 299 These include files are needed for all three functions.
 300 .Sh SEE ALSO
 301 .Xr fcntl 2 ,
 302 .Xr lseek 2 ,
 303 .Xr open 2 ,
 304 .Xr pipe 2 ,
 305 .Xr select 2 ,
 306 .Xr compat 5
 307 .Sh STANDARDS
 308 The
 309 .Fn write
 310 function call is expected to conform to
 311 .St -p1003.1-90 .
 312 The
 313 .Fn writev
 314 and
 315 .Fn pwrite
 316 functions are expected to conform to
 317 .St -xpg4.2 .
 318 .Sh HISTORY
 319 The
 320 .Fn pwrite
 321 function call
 322 appeared in
 323 .At V.4 .
 324 The
 325 .Fn writev
 326 function call
 327 appeared in
 328 .Bx 4.2 .
 329 A
 330 .Fn write
 331 function call appeared in
 332 .At v6 .