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