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 .\" $DragonFly: src/lib/libc/sys/write.2,v 1.5 2006/04/27 16:01:33 swildner Exp $
  31 .\"
  32 .Dd April 27, 2006
  33 .Dt WRITE 2
  34 .Os
  35 .Sh NAME
  36 .Nm write ,
  37 .Nm writev ,
  38 .Nm pwrite ,
  39 .Nm pwritev ,
  40 .Nm extpwrite ,
  41 .Nm extpwritev
  42 .Nd write output
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In sys/types.h
  47 .In sys/uio.h
  48 .In unistd.h
  49 .Ft ssize_t
  50 .Fn write "int d" "const void *buf" "size_t nbytes"
  51 .Ft ssize_t
  52 .Fn writev "int d" "const struct iovec *iov" "int iovcnt"
  53 .Ft ssize_t
  54 .Fn pwrite "int d" "const void *buf" "size_t nbytes" "off_t offset"
  55 .Ft ssize_t
  56 .Fn pwritev "int d" "const struct iovec *iov" "int iovcnt" "off_t offset"
  57 .Ft ssize_t
  58 .Fn extpwrite "int d" "const void *buf" "size_t nbytes" "int flags" "off_t offset"
  59 .Ft ssize_t
  60 .Fn extpwritev "int d" "const struct iovec *iov" "int iovcnt" "int flags" "off_t offset"
  61 .Sh DESCRIPTION
  62 .Fn Write
  63 attempts to write
  64 .Fa nbytes
  65 of data to the object referenced by the descriptor
  66 .Fa d
  67 from the buffer pointed to by
  68 .Fa buf .
  69 .Fn Writev
  70 and
  71 .Fn pwritev
  72 perform the same action, but gather the output data
  73 from the
  74 .Fa iovcnt
  75 buffers specified by the members of the
  76 .Fa iov
  77 array: iov[0], iov[1], ..., iov[iovcnt\|-\|1].
  78 .Fn Pwrite
  79 and
  80 .Fn pwritev
  81 perform the same function, but write to the specified position in
  82 the file without modifying the file pointer.
  83 .Pp
  84 For
  85 .Fn writev
  86 and
  87 .Fn pwritev ,
  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 and
 105 .Fn pwritev
 106 will always write a complete area before proceeding
 107 to the next.
 108 .Pp
 109 The
 110 .Fn extpwrite
 111 and
 112 .Fn extpwritev
 113 functions are
 114 .Dx
 115 specific and
 116 extend the specification further by allowing a flags argument
 117 to also be passed in, controlling blocking/non-blocking and other features
 118 on a call-by-call basis, ignoring the related default for the descriptor.
 119 Allowed flags are:
 120 .Bl -tag -width Er
 121 .It O_FBLOCKING
 122 Force the system call to operate in a blocking fashion.
 123 .It O_FNONBLOCKING
 124 Force the system call to operate in a non-blocking fashion.
 125 .It O_FAPPEND
 126 Force append mode for the operation.
 127 .It O_FOFFSET
 128 Force offset mode for the operation.
 129 .It O_FSYNCWRITE
 130 Force the system call to issue the write synchronously.
 131 .It O_FASYNCWRITE
 132 Force the system call to issue the write asynchronously.
 133 .El
 134 .Pp
 135 On objects capable of seeking, the
 136 .Fn write
 137 starts at a position
 138 given by the pointer associated with
 139 .Fa d ,
 140 see
 141 .Xr lseek 2 .
 142 Upon return from
 143 .Fn write ,
 144 the pointer is incremented by the number of bytes which were written.
 145 .Pp
 146 Objects that are not capable of seeking always write from the current
 147 position.  The value of the pointer associated with such an object
 148 is undefined.
 149 .Pp
 150 If the real user is not the super-user, then
 151 .Fn write
 152 clears the set-user-id bit on a file.
 153 This prevents penetration of system security
 154 by a user who
 155 .Dq captures
 156 a writable set-user-id file
 157 owned by the super-user.
 158 .Pp
 159 When using non-blocking I/O on objects such as sockets that are subject
 160 to flow control,
 161 .Fn write
 162 and
 163 .Fn writev
 164 may write fewer bytes than requested;
 165 the return value must be noted,
 166 and the remainder of the operation should be retried when possible.
 167 .Sh RETURN VALUES
 168 Upon successful completion the number of bytes which were written
 169 is returned.  Otherwise a -1 is returned and the global variable
 170 .Va errno
 171 is set to indicate the error.
 172 .Sh ERRORS
 173 .Fn Write ,
 174 .Fn writev ,
 175 .Fn pwrite ,
 176 and
 177 .Fn pwritev
 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 and
 227 .Fn pwritev
 228 may return one of the following errors:
 229 .Bl -tag -width Er
 230 .It Bq Er EDESTADDRREQ
 231 The destination is no longer available when writing to a
 232 .Ux
 233 domain datagram socket on which
 234 .Xr connect 2
 235 had been used to set a destination address.
 236 .It Bq Er EINVAL
 237 .Fa Iovcnt
 238 was less than or equal to 0, or greater than
 239 .Dv UIO_MAXIOV .
 240 .It Bq Er EINVAL
 241 One of the
 242 .Fa iov_len
 243 values in the
 244 .Fa iov
 245 array was negative.
 246 .It Bq Er EINVAL
 247 The sum of the
 248 .Fa iov_len
 249 values in the
 250 .Fa iov
 251 array overflowed a 32-bit integer.
 252 .It Bq Er ENOBUFS
 253 The mbuf pool has been completely exhausted when writing to a socket.
 254 .El
 255 .Pp
 256 The
 257 .Fn pwrite
 258 and
 259 .Fn pwritev
 260 calls may also return the following errors:
 261 .Bl -tag -width Er
 262 .It Bq Er EINVAL
 263 The specified file offset is invalid.
 264 .It Bq Er ESPIPE
 265 The file descriptor is associated with a pipe, socket, or FIFO.
 266 .El
 267 .Sh SEE ALSO
 268 .Xr fcntl 2 ,
 269 .Xr lseek 2 ,
 270 .Xr open 2 ,
 271 .Xr pipe 2 ,
 272 .Xr select 2
 273 .Sh STANDARDS
 274 The
 275 .Fn write
 276 function call is expected to conform to
 277 .St -p1003.1-90 .
 278 The
 279 .Fn writev
 280 and
 281 .Fn pwrite
 282 functions are expected to conform to
 283 .St -xpg4.2 .
 284 .Sh HISTORY
 285 The
 286 .Fn pwritev
 287 function call was added in
 288 .Dx 1.5 .
 289 The
 290 .Fn pwrite
 291 function call
 292 appeared in
 293 .At V.4 .
 294 The
 295 .Fn writev
 296 function call
 297 appeared in
 298 .Bx 4.2 .
 299 A
 300 .Fn write
 301 function call appeared in
 302 .At v6 .