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