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