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 .\" 4. 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 September 11, 2013
  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 sys/types.h
  44 .In unistd.h
  45 .Ft ssize_t
  46 .Fn write "int fd" "const void *buf" "size_t nbytes"
  47 .Ft ssize_t
  48 .Fn pwrite "int fd" "const void *buf" "size_t nbytes" "off_t offset"
  49 .In sys/uio.h
  50 .Ft ssize_t
  51 .Fn writev "int fd" "const struct iovec *iov" "int iovcnt"
  52 .Ft ssize_t
  53 .Fn pwritev "int fd" "const struct iovec *iov" "int iovcnt" "off_t offset"
  54 .Sh DESCRIPTION
  55 The
  56 .Fn write
  57 system call
  58 attempts to write
  59 .Fa nbytes
  60 of data to the object referenced by the descriptor
  61 .Fa fd
  62 from the buffer pointed to by
  63 .Fa buf .
  64 The
  65 .Fn writev
  66 system call
  67 performs the same action, but gathers the output data
  68 from the
  69 .Fa iovcnt
  70 buffers specified by the members of the
  71 .Fa iov
  72 array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
  73 The
  74 .Fn pwrite
  75 and
  76 .Fn pwritev
  77 system calls
  78 perform the same functions, but write to the specified position in
  79 the file without modifying the file pointer.
  80 .Pp
  81 For
  82 .Fn writev
  83 and
  84 .Fn pwritev ,
  85 the
  86 .Fa iovec
  87 structure is defined as:
  88 .Pp
  89 .Bd -literal -offset indent -compact
  90 struct iovec {
  91         void   *iov_base;  /* Base address. */
  92         size_t iov_len;    /* Length. */
  93 };
  94 .Ed
  95 .Pp
  96 Each
  97 .Fa iovec
  98 entry specifies the base address and length of an area
  99 in memory from which data should be written.
 100 The
 101 .Fn writev
 102 system call
 103 will always write a complete area before proceeding
 104 to the next.
 105 .Pp
 106 On objects capable of seeking, the
 107 .Fn write
 108 starts at a position
 109 given by the pointer associated with
 110 .Fa fd ,
 111 see
 112 .Xr lseek 2 .
 113 Upon return from
 114 .Fn write ,
 115 the pointer is incremented by the number of bytes which were written.
 116 .Pp
 117 Objects that are not capable of seeking always write from the current
 118 position.
 119 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 that are subject
 132 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 which were written
 141 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 .Fn pwrite
 150 and
 151 .Fn pwritev
 152 system calls
 153 will fail and the file pointer will remain unchanged if:
 154 .Bl -tag -width Er
 155 .It Bq Er EBADF
 156 The
 157 .Fa fd
 158 argument
 159 is not a valid descriptor open for writing.
 160 .It Bq Er EPIPE
 161 An attempt is made to write to a pipe that is not open
 162 for reading by any process.
 163 .It Bq Er EPIPE
 164 An attempt is made to write to a socket of type
 165 .Dv SOCK_STREAM
 166 that is not connected to a peer socket.
 167 .It Bq Er EFBIG
 168 An attempt was made to write a file that exceeds the process's
 169 file size limit or the maximum file size.
 170 .It Bq Er EFAULT
 171 Part of
 172 .Fa iov
 173 or data to be written to the file
 174 points outside the process's allocated address space.
 175 .It Bq Er EINVAL
 176 The pointer associated with
 177 .Fa fd
 178 was negative.
 179 .It Bq Er ENOSPC
 180 There is no free space remaining on the file system
 181 containing the file.
 182 .It Bq Er EDQUOT
 183 The user's quota of disk blocks on the file system
 184 containing the file has been exhausted.
 185 .It Bq Er EIO
 186 An I/O error occurred while reading from or writing to the file system.
 187 .It Bq Er EINTR
 188 A signal interrupted the write before it could be completed.
 189 .It Bq Er EAGAIN
 190 The file was marked for non-blocking I/O,
 191 and no data could be written immediately.
 192 .It Bq Er EROFS
 193 An attempt was made to write over a disk label area at the beginning
 194 of a slice.
 195 Use
 196 .Xr disklabel 8
 197 .Fl W
 198 to enable writing on the disk label area.
 199 .It Bq Er EINVAL
 200 The value
 201 .Fa nbytes
 202 is greater than
 203 .Dv INT_MAX .
 204 .El
 205 .Pp
 206 In addition,
 207 .Fn writev
 208 and
 209 .Fn pwritev
 210 may return one of the following errors:
 211 .Bl -tag -width Er
 212 .It Bq Er EDESTADDRREQ
 213 The destination is no longer available when writing to a
 214 .Ux
 215 domain datagram socket on which
 216 .Xr connect 2
 217 had been used to set a destination address.
 218 .It Bq Er EINVAL
 219 The
 220 .Fa iovcnt
 221 argument
 222 was less than or equal to 0, or greater than
 223 .Dv IOV_MAX .
 224 .It Bq Er EINVAL
 225 One of the
 226 .Fa iov_len
 227 values in the
 228 .Fa iov
 229 array was negative.
 230 .It Bq Er EINVAL
 231 The sum of the
 232 .Fa iov_len
 233 values in the
 234 .Fa iov
 235 array overflowed a 32-bit integer.
 236 .It Bq Er ENOBUFS
 237 The mbuf pool has been completely exhausted when writing to a socket.
 238 .El
 239 .Pp
 240 The
 241 .Fn pwrite
 242 and
 243 .Fn pwritev
 244 system calls may also return the following errors:
 245 .Bl -tag -width Er
 246 .It Bq Er EINVAL
 247 The
 248 .Fa offset
 249 value was negative.
 250 .It Bq Er ESPIPE
 251 The file descriptor is associated with a pipe, socket, or FIFO.
 252 .El
 253 .Sh SEE ALSO
 254 .Xr fcntl 2 ,
 255 .Xr lseek 2 ,
 256 .Xr open 2 ,
 257 .Xr pipe 2 ,
 258 .Xr select 2
 259 .Sh STANDARDS
 260 The
 261 .Fn write
 262 system call is expected to conform to
 263 .St -p1003.1-90 .
 264 The
 265 .Fn writev
 266 and
 267 .Fn pwrite
 268 system calls are expected to conform to
 269 .St -xpg4.2 .
 270 .Sh HISTORY
 271 The
 272 .Fn pwritev
 273 system call appeared in
 274 .Fx 6.0 .
 275 The
 276 .Fn pwrite
 277 function appeared in
 278 .At V.4 .
 279 The
 280 .Fn writev
 281 system call appeared in
 282 .Bx 4.2 .
 283 The
 284 .Fn write
 285 function appeared in
 286 .At v6 .