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