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$
  30 .\"
  31 .Dd March 30, 2020
  32 .Dt WRITE 2
  33 .Os
  34 .Sh NAME
  35 .Nm write ,
  36 .Nm writev ,
  37 .Nm pwrite ,
  38 .Nm pwritev
  39 .Nd write output
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In unistd.h
  44 .Ft ssize_t
  45 .Fn write "int fd" "const void *buf" "size_t nbytes"
  46 .Ft ssize_t
  47 .Fn pwrite "int fd" "const void *buf" "size_t nbytes" "off_t offset"
  48 .In sys/uio.h
  49 .Ft ssize_t
  50 .Fn writev "int fd" "const struct iovec *iov" "int iovcnt"
  51 .Ft ssize_t
  52 .Fn pwritev "int fd" "const struct iovec *iov" "int iovcnt" "off_t offset"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn write
  56 system call
  57 attempts to write
  58 .Fa nbytes
  59 of data to the object referenced by the descriptor
  60 .Fa fd
  61 from the buffer pointed to by
  62 .Fa buf .
  63 The
  64 .Fn writev
  65 system call
  66 performs the same action, but gathers the output data
  67 from the
  68 .Fa iovcnt
  69 buffers specified by the members of the
  70 .Fa iov
  71 array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
  72 The
  73 .Fn pwrite
  74 and
  75 .Fn pwritev
  76 system calls
  77 perform the same functions, but write to the specified position in
  78 the file without modifying the file pointer.
  79 .Pp
  80 For
  81 .Fn writev
  82 and
  83 .Fn pwritev ,
  84 the
  85 .Fa iovec
  86 structure is defined as:
  87 .Pp
  88 .Bd -literal -offset indent -compact
  89 struct iovec {
  90         void   *iov_base;  /* Base address. */
  91         size_t iov_len;    /* Length. */
  92 };
  93 .Ed
  94 .Pp
  95 Each
  96 .Fa iovec
  97 entry specifies the base address and length of an area
  98 in memory from which data should be written.
  99 The
 100 .Fn writev
 101 system call
 102 will always write a complete area before proceeding
 103 to the next.
 104 .Pp
 105 On objects capable of seeking, the
 106 .Fn write
 107 starts at a position
 108 given by the pointer associated with
 109 .Fa fd ,
 110 see
 111 .Xr lseek 2 .
 112 Upon return from
 113 .Fn write ,
 114 the pointer is incremented by the number of bytes which were written.
 115 .Pp
 116 Objects that are not capable of seeking always write from the current
 117 position.
 118 The value of the pointer associated with such an object
 119 is undefined.
 120 .Pp
 121 If the real user is not the super-user, then
 122 .Fn write
 123 clears the set-user-id bit on a file.
 124 This prevents penetration of system security
 125 by a user who
 126 .Dq captures
 127 a writable set-user-id file
 128 owned by the super-user.
 129 .Pp
 130 When using non-blocking I/O on objects such as sockets that are subject
 131 to flow control,
 132 .Fn write
 133 and
 134 .Fn writev
 135 may write fewer bytes than requested;
 136 the return value must be noted,
 137 and the remainder of the operation should be retried when possible.
 138 .Sh RETURN VALUES
 139 Upon successful completion the number of bytes which were written
 140 is returned.
 141 Otherwise a -1 is returned and the global variable
 142 .Va errno
 143 is set to indicate the error.
 144 .Sh ERRORS
 145 The
 146 .Fn write ,
 147 .Fn writev ,
 148 .Fn pwrite
 149 and
 150 .Fn pwritev
 151 system calls
 152 will fail and the file pointer will remain unchanged if:
 153 .Bl -tag -width Er
 154 .It Bq Er EBADF
 155 The
 156 .Fa fd
 157 argument
 158 is not a valid descriptor open for writing.
 159 .It Bq Er EPIPE
 160 An attempt is made to write to a pipe that is not open
 161 for reading by any process.
 162 .It Bq Er EPIPE
 163 An attempt is made to write to a socket of type
 164 .Dv SOCK_STREAM
 165 that is not connected to a peer socket.
 166 .It Bq Er EFBIG
 167 An attempt was made to write a file that exceeds the process's
 168 file size limit or the maximum file size.
 169 .It Bq Er EFAULT
 170 Part of
 171 .Fa iov
 172 or data to be written to the file
 173 points outside the process's allocated address space.
 174 .It Bq Er EINVAL
 175 The pointer associated with
 176 .Fa fd
 177 was negative.
 178 .It Bq Er ENOSPC
 179 There is no free space remaining on the file system
 180 containing the file.
 181 .It Bq Er EDQUOT
 182 The user's quota of disk blocks on the file system
 183 containing the file has been exhausted.
 184 .It Bq Er EIO
 185 An I/O error occurred while reading from or writing to the file system.
 186 .It Bq Er EINTR
 187 A signal interrupted the write before it could be completed.
 188 .It Bq Er EAGAIN
 189 The file was marked for non-blocking I/O,
 190 and no data could be written immediately.
 191 .It Bq Er EROFS
 192 An attempt was made to write over a disk label area at the beginning
 193 of a slice.
 194 Use
 195 .Xr disklabel 8
 196 .Fl W
 197 to enable writing on the disk label area.
 198 .It Bq Er EINVAL
 199 The value
 200 .Fa nbytes
 201 is greater than
 202 .Dv SSIZE_MAX
 203 (or greater than
 204 .Dv INT_MAX ,
 205 if the sysctl
 206 .Va debug.iosize_max_clamp
 207 is non-zero).
 208 .It Bq Er EINTEGRITY
 209 The backing store for
 210 .Fa fd
 211 detected corrupted data while reading.
 212 (For example, writing a partial filesystem block may require first reading
 213 the existing block which may trigger this error.)
 214 .El
 215 .Pp
 216 In addition,
 217 .Fn writev
 218 and
 219 .Fn pwritev
 220 may return one of the following errors:
 221 .Bl -tag -width Er
 222 .It Bq Er EDESTADDRREQ
 223 The destination is no longer available when writing to a
 224 .Ux
 225 domain datagram socket on which
 226 .Xr connect 2
 227 had been used to set a destination address.
 228 .It Bq Er EINVAL
 229 The
 230 .Fa iovcnt
 231 argument
 232 was less than or equal to 0, or greater than
 233 .Dv IOV_MAX .
 234 .It Bq Er EINVAL
 235 One of the
 236 .Fa iov_len
 237 values in the
 238 .Fa iov
 239 array was negative.
 240 .It Bq Er EINVAL
 241 The sum of the
 242 .Fa iov_len
 243 values in the
 244 .Fa iov
 245 array overflowed a 32-bit integer.
 246 .It Bq Er ENOBUFS
 247 The mbuf pool has been completely exhausted when writing to a socket.
 248 .El
 249 .Pp
 250 The
 251 .Fn pwrite
 252 and
 253 .Fn pwritev
 254 system calls may also return the following errors:
 255 .Bl -tag -width Er
 256 .It Bq Er EINVAL
 257 The
 258 .Fa offset
 259 value was negative.
 260 .It Bq Er ESPIPE
 261 The file descriptor is associated with a pipe, socket, or FIFO.
 262 .El
 263 .Sh SEE ALSO
 264 .Xr fcntl 2 ,
 265 .Xr lseek 2 ,
 266 .Xr open 2 ,
 267 .Xr pipe 2 ,
 268 .Xr select 2
 269 .Sh STANDARDS
 270 The
 271 .Fn write
 272 system call is expected to conform to
 273 .St -p1003.1-90 .
 274 The
 275 .Fn writev
 276 and
 277 .Fn pwrite
 278 system calls are expected to conform to
 279 .St -xpg4.2 .
 280 .Sh HISTORY
 281 The
 282 .Fn pwritev
 283 system call appeared in
 284 .Fx 6.0 .
 285 The
 286 .Fn pwrite
 287 function appeared in
 288 .At V.4 .
 289 The
 290 .Fn writev
 291 system call appeared in
 292 .Bx 4.2 .
 293 The
 294 .Fn write
 295 function appeared in
 296 .At v1 .