| blob | bc49672a98277fe243bce9053073f1791f34dd45 |
1 .TH FCNTL 2
2 .SH NAME
3 fcntl \- miscellaneous file descriptor control functions
4 .SH SYNOPSIS
5 .nf
6 .ft B
7 #include <fcntl.h>
9 int fcntl(int \fIfd\fP, int \fIcmd\fP, \fR[\fP\fIdata\fP\fR]\fP)
10 .ft P
11 .fi
12 .SH DESCRIPTION
13 .de SP
14 .if t .sp 0.4
15 .if n .sp
16 ..
17 .B Fcntl()
18 performs several file descriptor related functions, like duplicating a file
19 descriptor, setting the "close on exec" attribute, etc. The
20 .I fd
21 argument is the file descriptor to operate on,
22 .I cmd
23 is the command code of the operation to perform, and
24 .I data
25 is an optional argument to give or receive parameters. The command
26 codes and other symbols and types are declared in <fcntl.h>. The commands
27 are:
28 .SP
29 .BI "fcntl(" fd ", F_DUPFD, int " fd2 ")"
30 .RS
31 Returns a new file descriptor that is a duplicate of file descriptor
32 .IR fd .
33 It shares the same file pointer and the same file status flags, but has
34 separate file descriptor flags that are initially off. The value of the
35 duplicate file descriptor is the first free file descriptor greater than
36 or equal to
37 .IR fd2 .
38 .RE
39 .SP
40 .BI "fcntl(" fd ", F_GETFD)"
41 .RS
42 Returns the file descriptor flags associated with file descriptor
43 .IR fd .
44 The flags are the "close on exec" flag
45 .B FD_CLOEXEC
46 that, when set, causes the file descriptor to be closed when the process
47 executes another program. The Minix-vmd specific
48 .B FD_ASYNCHIO
49 flag marks a file descriptor for asynchronous I/O operation.
50 .RE
51 .SP
52 .BI "fcntl(" fd ", F_SETFD, int " flags ")"
53 .RS
54 Set the file descriptor flags of
55 .I fd
56 to
57 .IR flags .
58 .RE
59 .SP
60 .BI "fcntl(" fd ", F_GETFL)"
61 .RS
62 Return the file status flags and file access modes associated with the file
63 associated with file descriptor
64 .IR fd .
65 The file status flags are
66 .B O_NONBLOCK
67 (non blocking I/O) and
68 .B O_APPEND
69 (append mode). The file access modes are
70 .B O_RDONLY
71 (read-only),
72 .B O_WRONLY
73 (write-only) and
74 .B O_RDWR
75 (read-write). These flags are also used in the second argument of
76 .BR open (2).
77 .RE
78 .SP
79 .BI "fcntl(" fd ", F_SETFL, int " flags ")"
80 .RS
81 Set the file status flags of the file referenced by
82 .I fd
83 to
84 .IR flags .
85 Only
86 .B O_NONBLOCK
87 and
88 .B O_APPEND
89 may be changed. Access mode flags are ignored.
90 .RE
91 .SP
92 The next four commands use a parameter of type
93 .B struct flock
94 that is defined in <fcntl.h> as:
95 .SP
96 .RS
97 .nf
98 .ta +4n +8n +12n
99 struct flock {
100 short l_type; /* F_RDLCK, F_WRLCK, or F_UNLCK */
101 short l_whence; /* SEEK_SET, SEEK_CUR, or SEEK_END */
102 off_t l_start; /* byte offset to start of segment */
103 off_t l_len; /* length of segment */
104 pid_t l_pid; /* process id of the locks' owner */
105 };
106 .fi
107 .RE
108 .SP
109 This structure describes a segment of a file.
110 .B L_type
111 is the lock operation performed on the file segment:
112 .B F_RDLCK
113 to set a read lock,
114 .B F_WRLCK
115 to set a write lock, and
116 .B F_UNLCK
117 to remove a lock. Several processes may have a read lock on a segment, but
118 only one process can have a write lock.
119 .B L_whence
120 tells if the
121 .B l_start
122 offset must be interpreted from the start of the file
123 .RB ( SEEK_SET ),
124 the current file position
125 .RB ( SEEK_CUR ),
126 or the end of the file
127 .RB ( SEEK_END ).
128 This is analogous to the third parameter of
129 .BR lseek (2).
130 These
131 .B SEEK_*
132 symbols are declared in <unistd.h>.
133 .B L_start
134 is the starting offset of the segment of the file.
135 .B L_end
136 is the length of the segment. If zero then the segment extends until end of
137 file.
138 .B L_pid
139 is the process-id of the process currently holding a lock on the segment.
140 It is returned by
141 .BR F_GETLK .
142 .SP
143 .BI "fcntl(" fd ", F_GETLK, struct flock *" lkp ")"
144 .RS
145 Find out if some other process has a lock on a segment of the file
146 associated by file descriptor
147 .I fd
148 that overlaps with the segment described by the
149 .B flock
150 structure pointed to by
151 .IR lkp .
152 If the segment is not locked then
153 .B l_type
154 is set to
155 .BR F_UNLCK .
156 Otherwise an
157 .B flock
158 structure is returned through
159 .I lkp
160 that describes the lock held by the other process.
161 .B L_start
162 is set relative to the start of the file.
163 .RE
164 .SP
165 .BI "fcntl(" fd ", F_SETLK, struct flock *" lkp ")"
166 .RS
167 Register a lock on a segment of the file associated with file descriptor
168 .IR fd .
169 The file segment is described by the
170 .B struct flock
171 pointed to by
172 .IR lkp .
173 This call returns an error if any part of the segment is already locked.
174 .RE
175 .SP
176 .BI "fcntl(" fd ", F_SETLKW, struct flock *" lkp ")"
177 .RS
178 Register a lock on a segment of the file associated with file descriptor
179 .IR fd .
180 The file segment is described by the
181 .B struct flock
182 pointed to by
183 .IR lkp .
184 This call blocks waiting for the lock to be released if any part of the
185 segment is already locked.
186 .RE
187 .SP
188 .BI "fcntl(" fd ", F_FREESP, struct flock *" lkp ")"
189 .RS
190 This call frees a segment of disk space occupied by the
191 file associated with file descriptor
192 .IR fd .
193 The segment is described by the
194 .B struct flock
195 pointed to by
196 .IR lkp .
197 The file is truncated in length to the byte position indicated by
198 .B l_start
199 if
200 .B l_len
201 is zero. If
202 .B l_len
203 is nonzero then the file keeps its size, but the freed bytes now read as
204 zeros. (Other than sharing the flock structure, this call has nothing to do
205 with locking.) (This call is common among UNIX(-like) systems.)
206 .RE
207 .SP
208 .BI "fcntl(" fd ", F_SEEK, u64_t " pos ")"
209 .RS
210 This Minix-vmd specific call sets the file position of the file associated
211 with file descriptor
212 .I fd
213 to the byte offset indicated by the 64-bit number
214 .IR pos .
215 This is analogous to the call
216 .SP
217 .RS
218 .BI "lseek(" fd ", " pos ", SEEK_SET)"
219 .RE
220 .SP
221 except that
222 .B F_SEEK
223 can be used on devices larger than 4 gigabyte.
224 .RE
225 .SH "SEE ALSO"
226 .BR open (2),
227 .BR dup (2),
228 .BR lseek (2),
229 .BR ftruncate (3),
230 .BR int64 (3).
231 .SH DIAGNOSTICS
232 .B Fcntl
233 returns a file descriptor, flags, or
234 .B 0
235 to indicate success. On error
236 .B \-1
237 is returned, with
238 .B errno
239 set to the appropriate error code. The most notable errors are:
240 .TP 5
241 .B EINTR
242 If a blocked
243 .B F_SETLKW
244 operation is interrupted by a signal that is caught.
245 .TP
246 .B EAGAIN
247 By
248 .B F_SETLK
249 if a segment cannot be locked.
250 .TP
251 .B EBADF
252 A bad file descriptor in general, or an attempt to place a write lock on a
253 file that is not open for writing, etc.
254 .TP
255 .B ENOLCK
256 No locks available, the file system code has run out of internal table
257 space.
258 .SH AUTHOR
259 Kees J. Bot <kjb@cs.vu.nl>
261 .\"
262 .\" $PchId: fcntl.2,v 1.2 2000/08/11 19:39:51 philip Exp $