Commit | Line | Data |
---|---|---|
60792775 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
15fa213a | 5 | .\" @(#)write.2 6.5 (Berkeley) %G% |
60792775 | 6 | .\" |
d341f19b | 7 | .TH WRITE 2 "" |
60792775 KM |
8 | .UC 4 |
9 | .SH NAME | |
d1c0365c | 10 | write, writev \- write output |
60792775 KM |
11 | .SH SYNOPSIS |
12 | .nf | |
e35a5c92 | 13 | .ft B |
d1c0365c JL |
14 | cc = write(d, buf, nbytes) |
15 | int cc, d; | |
e35a5c92 KM |
16 | char *buf; |
17 | int nbytes; | |
18 | .PP | |
19 | .ft B | |
20 | #include <sys/types.h> | |
21 | #include <sys/uio.h> | |
22 | .PP | |
23 | .ft B | |
d1c0365c JL |
24 | cc = writev(d, iov, iovcnt) |
25 | int cc, d; | |
e35a5c92 | 26 | struct iovec *iov; |
d1c0365c | 27 | int iovcnt; |
60792775 KM |
28 | .fi |
29 | .SH DESCRIPTION | |
e35a5c92 KM |
30 | .I Write |
31 | attempts to write | |
60792775 | 32 | .I nbytes |
e35a5c92 KM |
33 | of data to the object referenced by the descriptor |
34 | .I d | |
35 | from the buffer pointed to by | |
36 | .IR buf . | |
37 | .I Writev | |
38 | performs the same action, but gathers the output data | |
d1c0365c JL |
39 | from the |
40 | .I iovcnt | |
41 | buffers specified by the members of the | |
42 | .I iov | |
43 | array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. | |
44 | .PP | |
45 | For | |
46 | .IR writev , | |
47 | the | |
48 | .I iovec | |
49 | structure is defined as | |
50 | .PP | |
51 | .nf | |
52 | .RS | |
53 | .DT | |
54 | struct iovec { | |
55 | caddr_t iov_base; | |
56 | int iov_len; | |
57 | }; | |
58 | .RE | |
59 | .fi | |
60 | .PP | |
61 | Each | |
62 | .I iovec | |
63 | entry specifies the base address and length of an area | |
64 | in memory from which data should be written. | |
65 | .I Writev | |
66 | will always write a complete area before proceeding | |
67 | to the next. | |
60792775 | 68 | .PP |
e35a5c92 KM |
69 | On objects capable of seeking, the \fIwrite\fP starts at a position |
70 | given by the pointer associated with | |
71 | .IR d , | |
72 | see | |
73 | .IR lseek (2). | |
74 | Upon return from | |
75 | .IR write , | |
76 | the pointer is incremented by the number of bytes actually written. | |
60792775 | 77 | .PP |
e35a5c92 KM |
78 | Objects that are not capable of seeking always write from the current |
79 | position. The value of the pointer associated with such an object | |
80 | is undefined. | |
60792775 | 81 | .PP |
e35a5c92 | 82 | If the real user is not the super-user, then |
60792775 KM |
83 | .I write |
84 | clears the set-user-id bit on a file. | |
85 | This prevents penetration of system security | |
86 | by a user who | |
e35a5c92 | 87 | \*(lqcaptures\*(rq a writable set-user-id file |
60792775 | 88 | owned by the super-user. |
15fa213a MK |
89 | .PP |
90 | When using non-blocking I/O on objects such as sockets that are subject | |
91 | to flow control, | |
92 | .I write | |
93 | and | |
94 | .I writev | |
95 | may write fewer bytes than requested; | |
96 | the return value must be noted, | |
97 | and the remainder of the operation should be retried when possible. | |
e35a5c92 | 98 | .SH "RETURN VALUE |
d1c0365c JL |
99 | Upon successful completion the number of bytes actually written |
100 | is returned. Otherwise a \-1 is returned and the global variable | |
e35a5c92 KM |
101 | .I errno |
102 | is set to indicate the error. | |
103 | .SH ERRORS | |
104 | .I Write | |
d1c0365c JL |
105 | and |
106 | .I writev | |
e35a5c92 KM |
107 | will fail and the file pointer will remain unchanged if one or more |
108 | of the following are true: | |
109 | .TP 15 | |
110 | [EBADF] | |
111 | \fID\fP is not a valid descriptor open for writing. | |
112 | .TP 15 | |
113 | [EPIPE] | |
114 | An attempt is made to write to a pipe that is not open | |
115 | for reading by any process. | |
116 | .TP 15 | |
117 | [EPIPE] | |
118 | An attempt is made to write to a socket of type SOCK_STREAM | |
eff6446c | 119 | that is not connected to a peer socket. |
e35a5c92 KM |
120 | .TP 15 |
121 | [EFBIG] | |
122 | An attempt was made to write a file that exceeds the process's | |
123 | file size limit or the maximum file size. | |
124 | .TP 15 | |
125 | [EFAULT] | |
126 | Part of \fIiov\fP or data to be written to the file | |
127 | points outside the process's allocated address space. | |
fd690c8b | 128 | .TP 15 |
d1c0365c JL |
129 | [EINVAL] |
130 | The pointer associated with | |
131 | .I d | |
132 | was negative. | |
133 | .TP 15 | |
fd690c8b KM |
134 | [ENOSPC] |
135 | There is no free space remaining on the file system | |
136 | containing the file. | |
137 | .TP 15 | |
138 | [EDQUOT] | |
139 | The user's quota of disk blocks on the file system | |
140 | containing the file has been exhausted. | |
141 | .TP 15 | |
142 | [EIO] | |
143 | An I/O error occurred while reading from or writing to the file system. | |
15fa213a MK |
144 | .TP 15 |
145 | [EWOULDBLOCK] | |
146 | The file was marked for non-blocking I/O, | |
147 | and no data could be written immediately. | |
d1c0365c JL |
148 | .PP |
149 | In addition, | |
150 | .I writev | |
151 | may return one of the following errors: | |
152 | .TP 15 | |
153 | [EINVAL] | |
154 | .I Iovcnt | |
155 | was less than or equal to 0, or greater than 16. | |
156 | .TP 15 | |
157 | [EINVAL] | |
158 | One of the | |
159 | .I iov_len | |
160 | values in the | |
161 | .I iov | |
162 | array was negative. | |
163 | .TP 15 | |
164 | [EINVAL] | |
165 | The sum of the | |
166 | .I iov_len | |
167 | values in the | |
168 | .I iov | |
169 | array overflowed a 32-bit integer. | |
60792775 | 170 | .SH "SEE ALSO" |
15fa213a | 171 | fcntl(2), lseek(2), open(2), pipe(2), select(2) |