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