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 | .\" | |
d1c0365c | 5 | .\" @(#)write.2 6.4 (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. |
e35a5c92 | 89 | .SH "RETURN VALUE |
d1c0365c JL |
90 | Upon successful completion the number of bytes actually written |
91 | is returned. Otherwise a \-1 is returned and the global variable | |
e35a5c92 KM |
92 | .I errno |
93 | is set to indicate the error. | |
94 | .SH ERRORS | |
95 | .I Write | |
d1c0365c JL |
96 | and |
97 | .I writev | |
e35a5c92 KM |
98 | will fail and the file pointer will remain unchanged if one or more |
99 | of the following are true: | |
100 | .TP 15 | |
101 | [EBADF] | |
102 | \fID\fP is not a valid descriptor open for writing. | |
103 | .TP 15 | |
104 | [EPIPE] | |
105 | An attempt is made to write to a pipe that is not open | |
106 | for reading by any process. | |
107 | .TP 15 | |
108 | [EPIPE] | |
109 | An attempt is made to write to a socket of type SOCK_STREAM | |
eff6446c | 110 | that is not connected to a peer socket. |
e35a5c92 KM |
111 | .TP 15 |
112 | [EFBIG] | |
113 | An attempt was made to write a file that exceeds the process's | |
114 | file size limit or the maximum file size. | |
115 | .TP 15 | |
116 | [EFAULT] | |
117 | Part of \fIiov\fP or data to be written to the file | |
118 | points outside the process's allocated address space. | |
fd690c8b | 119 | .TP 15 |
d1c0365c JL |
120 | [EINVAL] |
121 | The pointer associated with | |
122 | .I d | |
123 | was negative. | |
124 | .TP 15 | |
fd690c8b KM |
125 | [ENOSPC] |
126 | There is no free space remaining on the file system | |
127 | containing the file. | |
128 | .TP 15 | |
129 | [EDQUOT] | |
130 | The user's quota of disk blocks on the file system | |
131 | containing the file has been exhausted. | |
132 | .TP 15 | |
133 | [EIO] | |
134 | An I/O error occurred while reading from or writing to the file system. | |
d1c0365c JL |
135 | .PP |
136 | In addition, | |
137 | .I writev | |
138 | may return one of the following errors: | |
139 | .TP 15 | |
140 | [EINVAL] | |
141 | .I Iovcnt | |
142 | was less than or equal to 0, or greater than 16. | |
143 | .TP 15 | |
144 | [EINVAL] | |
145 | One of the | |
146 | .I iov_len | |
147 | values in the | |
148 | .I iov | |
149 | array was negative. | |
150 | .TP 15 | |
151 | [EINVAL] | |
152 | The sum of the | |
153 | .I iov_len | |
154 | values in the | |
155 | .I iov | |
156 | array overflowed a 32-bit integer. | |
60792775 | 157 | .SH "SEE ALSO" |
e35a5c92 | 158 | lseek(2), open(2), pipe(2) |