26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH CLOSE 2 "Oct 18, 2005"
48 .SH NAME
49 close \- close a file descriptor
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <unistd.h>
54
55 \fBint\fR \fBclose\fR(\fBint\fR \fIfildes\fR);
56 .fi
57
58 .SH DESCRIPTION
59 .sp
60 .LP
61 The \fBclose()\fR function deallocates the file descriptor indicated by
62 \fIfildes\fR. To deallocate means to make the file descriptor available for
63 return by subsequent calls to \fBopen\fR(2) or other functions that allocate
64 file descriptors. All outstanding record locks owned by the process on the file
65 associated with the file descriptor will be removed (that is, unlocked).
66 .sp
67 .LP
68 If \fBclose()\fR is interrupted by a signal that is to be caught, it will
69 return \fB\(mi1\fR with \fBerrno\fR set to \fBEINTR\fR and the state of
70 \fIfildes\fR is unspecified. If an I/O error occurred while reading from or
71 writing to the file system during \fBclose()\fR, it returns -1, sets
72 \fBerrno\fR to \fBEIO\fR, and the state of \fIfildes\fR is unspecified.
73 .sp
74 .LP
75 When all file descriptors associated with a pipe or \fBFIFO\fR special file are
76 closed, any data remaining in the pipe or \fBFIFO\fR will be discarded.
77 .sp
78 .LP
79 When all file descriptors associated with an open file description have been
80 closed the open file description will be freed.
81 .sp
82 .LP
83 If the link count of the file is 0, when all file descriptors associated with
84 the file are closed, the space occupied by the file will be freed and the file
85 will no longer be accessible.
86 .sp
87 .LP
88 If a streams-based (see \fBIntro\fR(2)) \fIfildes\fR is closed and the calling
89 process was previously registered to receive a \fBSIGPOLL\fR signal (see
90 \fBsignal\fR(3C)) for events associated with that stream (see \fBI_SETSIG\fR in
91 \fBstreamio\fR(7I)), the calling process will be unregistered for events
92 associated with the stream. The last \fBclose()\fR for a stream causes the
93 stream associated with \fIfildes\fR to be dismantled. If \fBO_NONBLOCK\fR and
94 \fBO_NDELAY\fR are not set and there have been no signals posted for the
95 stream, and if there is data on the module's write queue, \fBclose()\fR waits
96 up to 15 seconds (for each module and driver) for any output to drain before
97 dismantling the stream. The time delay can be changed via an \fBI_SETCLTIME\fR
98 \fBioctl\fR(2) request (see \fBstreamio\fR(7I)). If the \fBO_NONBLOCK\fR or
99 \fBO_NDELAY\fR flag is set, or if there are any pending signals, \fBclose()\fR
100 does not wait for output to drain, and dismantles the stream immediately.
101 .sp
102 .LP
103 If \fIfildes\fR is associated with one end of a pipe, the last \fBclose()\fR
104 causes a hangup to occur on the other end of the pipe. In addition, if the
105 other end of the pipe has been named by \fBfattach\fR(3C), then the last
106 \fBclose()\fR forces the named end to be detached by \fBfdetach\fR(3C). If the
107 named end has no open file descriptors associated with it and gets detached,
108 the stream associated with that end is also dismantled.
109 .sp
110 .LP
111 If \fIfildes\fR refers to the master side of a pseudo-terminal, a \fBSIGHUP\fR
112 signal is sent to the session leader, if any, for which the slave side of the
113 pseudo-terminal is the controlling terminal. It is unspecified whether closing
114 the master side of the pseudo-terminal flushes all queued input and output.
115 .sp
116 .LP
117 If \fIfildes\fR refers to the slave side of a streams-based pseudo-terminal, a
118 zero-length message may be sent to the master.
119 .sp
120 .LP
121 When there is an outstanding cancelable asynchronous I/O operation against
122 \fIfildes\fR when \fBclose()\fR is called, that I/O operation is canceled. An
123 I/O operation that is not canceled completes as if the \fBclose()\fR operation
124 had not yet occurred. All operations that are not canceled will complete as if
125 the \fBclose()\fR blocked until the operations completed.
126 .sp
127 .LP
128 If a shared memory object or a memory mapped file remains referenced at the
129 last close (that is, a process has it mapped), then the entire contents of the
130 memory object will persist until the memory object becomes unreferenced. If
131 this is the last close of a shared memory object or a memory mapped file and
132 the close results in the memory object becoming unreferenced, and the memory
133 object has been unlinked, then the memory object will be removed.
134 .sp
135 .LP
136 If \fIfildes\fR refers to a socket, \fBclose()\fR causes the socket to be
137 destroyed. If the socket is connection-mode, and the \fBSO_LINGER\fR option is
138 set for the socket with non-zero linger time, and the socket has untransmitted
139 data, then \fBclose()\fR will block for up to the current linger interval until
140 all data is transmitted.
141 .SH RETURN VALUES
142 .sp
143 .LP
144 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
145 returned and \fBerrno\fR is set to indicate the error.
146 .SH ERRORS
147 .sp
148 .LP
149 The \fBclose()\fR function will fail if:
150 .sp
151 .ne 2
152 .na
153 \fB\fBEBADF\fR\fR
154 .ad
155 .RS 11n
156 The \fIfildes\fR argument is not a valid file descriptor.
157 .RE
158
159 .sp
160 .ne 2
161 .na
162 \fB\fBEINTR\fR\fR
163 .ad
164 .RS 11n
165 The \fBclose()\fR function was interrupted by a signal.
166 .RE
167
168 .sp
169 .ne 2
170 .na
171 \fB\fBENOLINK\fR\fR
172 .ad
173 .RS 11n
174 The \fIfildes\fR argument is on a remote machine and the link to that machine
175 is no longer active.
176 .RE
177
178 .sp
179 .ne 2
180 .na
181 \fB\fBENOSPC\fR\fR
182 .ad
183 .RS 11n
184 There was no free space remaining on the device containing the file.
185 .RE
186
187 .sp
188 .LP
189 The \fBclose()\fR function may fail if:
190 .sp
191 .ne 2
192 .na
193 \fB\fBEIO\fR\fR
194 .ad
195 .RS 7n
196 An I/O error occurred while reading from or writing to the file system.
197 .RE
198
199 .SH EXAMPLES
200 .LP
201 \fBExample 1 \fRReassign a file descriptor.
202 .sp
203 .LP
204 The following example closes the file descriptor associated with standard
205 output for the current process, re-assigns standard output to a new file
206 descriptor, and closes the original file descriptor to clean up. This example
207 assumes that the file descriptor 0, which is the descriptor for standard input,
208 is not closed.
209
210 .sp
211 .in +2
212 .nf
213 #include <unistd.h>
214 \&...
215 int pfd;
216 \&...
217 close(1);
218 dup(pfd);
219 close(pfd);
220 \&...
221 .fi
222 .in -2
223
224 .sp
225 .LP
226 Incidentally, this is exactly what could be achieved using:
227
228 .sp
229 .in +2
230 .nf
231 dup2(pfd, 1);
232 close(pfd);
233 .fi
234 .in -2
235
236 .LP
237 \fBExample 2 \fRClose a file descriptor.
238 .sp
239 .LP
240 In the following example, \fBclose()\fR is used to close a file descriptor
241 after an unsuccessful attempt is made to associate that file descriptor with a
242 stream.
243
244 .sp
245 .in +2
246 .nf
247 #include <stdio.h>
248 #include <unistd.h>
249 #include <stdlib.h>
250
251 #define LOCKFILE "/etc/ptmp"
252 \&...
253 int pfd;
254 FILE *fpfd;
255 \&...
256 if ((fpfd = fdopen (pfd, "w")) == NULL) {
257 close(pfd);
258 unlink(LOCKFILE);
259 exit(1);
260 }
261 \&...
262 .fi
263 .in -2
264
265 .SH USAGE
266 .sp
267 .LP
268 An application that used the \fBstdio\fR function \fBfopen\fR(3C) to open a
269 file should use the corresponding \fBfclose\fR(3C) function rather than
270 \fBclose()\fR.
271 .SH ATTRIBUTES
272 .sp
273 .LP
274 See \fBattributes\fR(5) for descriptions of the following attributes:
275 .sp
276
277 .sp
278 .TS
279 box;
280 c | c
281 l | l .
282 ATTRIBUTE TYPE ATTRIBUTE VALUE
283 _
284 Interface Stability Standard
285 _
286 MT-Level Async-Signal-Safe
287 .TE
288
289 .SH SEE ALSO
290 .sp
291 .LP
292 \fBIntro\fR(2), \fBcreat\fR(2), \fBdup\fR(2), \fBexec\fR(2), \fBfcntl\fR(2),
293 \fBioctl\fR(2), \fBopen\fR(2) \fBpipe\fR(2), \fBfattach\fR(3C),
294 \fBfclose\fR(3C), \fBfdetach\fR(3C), \fBfopen\fR(3C), \fBsignal\fR(3C),
295 \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5),
296 \fBstreamio\fR(7I)
|
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
46 .\" Copyright 2022 Oxide Computer Company
47 .\"
48 .Dd February 5, 2022
49 .Dt CLOSE 2
50 .Os
51 .Sh NAME
52 .Nm close
53 .Nd close a file descriptor
54 .Sh SYNOPSIS
55 .In unistd.h
56 .Ft int
57 .Fo close
58 .Fa "int fildes"
59 .Fc
60 .Sh DESCRIPTION
61 The
62 .Fn close
63 function deallocates the file descriptor indicated by
64 .Fa fildes .
65 To deallocate means to make the file descriptor available for return by
66 subsequent calls to
67 .Xr open 2
68 or other functions that allocate file descriptors.
69 All outstanding record locks owned by the process on the file associated with
70 the file descriptor will be removed
71 .Pq "that is, unlocked" .
72 .Pp
73 If
74 .Fn close
75 is interrupted by a signal that is to be caught, it will return
76 .Sy -1
77 with
78 .Va errno
79 set to
80 .Er EINTR
81 and the state of
82 .Fa fildes
83 is unspecified.
84 If an I/O error occurred while reading from or writing to the file system during
85 .Fn close ,
86 it returns
87 .Sy -1 ,
88 sets
89 .Va errno
90 to
91 .Er EIO ,
92 and the state of
93 .Fa fildes
94 is unspecified.
95 .Pp
96 When all file descriptors associated with a pipe or FIFO special file are
97 closed, any data remaining in the pipe or FIFO will be discarded.
98 .Pp
99 When all file descriptors associated with an open file description have been
100 closed the open file description will be freed.
101 .Pp
102 If the link count of the file is
103 .Sy 0 ,
104 when all file descriptors associated with the file are closed, the space
105 occupied by the file will be freed and the file will no longer be accessible.
106 .Pp
107 If a streams-based
108 .Po
109 see
110 .Xr Intro 2
111 .Pc
112 .Fa fildes
113 is closed and the calling process was previously registered to receive a
114 .Dv SIGPOLL
115 signal
116 .Po
117 see
118 .Xr signal 3C
119 .Pc
120 for events associated with that stream
121 .Po
122 see
123 .Dv I_SETSIG
124 in
125 .Xr streamio 7I
126 .Pc ,
127 the calling process will be unregistered for events associated with the stream.
128 The last
129 .Fn close
130 for a stream causes the stream associated with
131 .Fa fildes
132 to be dismantled.
133 If
134 .Dv O_NONBLOCK
135 and
136 .Dv O_NDELAY
137 are not set and there have been no signals posted for the stream, and if there
138 is data on the module's write queue,
139 .Fn close
140 waits up to 15 seconds
141 .Pq for each module and driver
142 for any output to drain
143 before dismantling the stream.
144 The time delay can be changed via an
145 .Dv I_SETCLTIME
146 .Xr ioctl 2
147 request
148 .Po
149 see
150 .Xr streamio 7I
151 .Pc .
152 If the
153 .Dv O_NONBLOCK
154 or
155 .Dv O_NDELAY
156 flag is set, or if there are any pending signals,
157 .Fn close
158 does not wait for output to drain, and dismantles the stream immediately.
159 .Pp
160 If
161 .Fa fildes
162 is associated with one end of a pipe, the last
163 .Fn close
164 causes a hangup to occur on the other end of the pipe.
165 In addition, if the other end of the pipe has been named by
166 .Xr fattach 3C ,
167 then the last
168 .Fn close
169 forces the named end to be detached by
170 .Xr fdetach 3C .
171 If the named end has no open file descriptors associated with it and gets
172 detached, the stream associated with that end is also dismantled.
173 .Pp
174 If
175 .Fa fildes
176 refers to the manager side of a pseudo-terminal, a
177 .Dv SIGHUP
178 signal is sent to the session leader, if any, for which the subsidiary side of
179 the pseudo-terminal is the controlling terminal.
180 It is unspecified whether closing the manager side of the pseudo-terminal
181 flushes all queued input and output.
182 .Pp
183 If
184 .Fa fildes
185 refers to the subsidiary side of a streams-based pseudo-terminal, a zero-length
186 message may be sent to the manager.
187 .Pp
188 When there is an outstanding cancelable asynchronous I/O operation against
189 .Fa fildes
190 when
191 .Fn close
192 is called, that I/O operation is canceled.
193 An I/O operation that is not canceled completes as if the
194 .Fn close
195 operation had not yet occurred.
196 All operations that are not canceled will complete as if the
197 .Fn close
198 blocked until the operations completed.
199 .Pp
200 If a shared memory object or a memory mapped file remains referenced at the
201 last close
202 .Pq "that is, a process has it mapped" ,
203 then the entire contents of the memory object will persist until the memory
204 object becomes unreferenced.
205 If this is the last close of a shared memory object or a memory mapped file and
206 the close results in the memory object becoming unreferenced, and the memory
207 object has been unlinked, then the memory object will be removed.
208 .Pp
209 If
210 .Fa fildes
211 refers to a socket,
212 .Fn close
213 causes the socket to be destroyed.
214 If the socket is connection-mode, and the
215 .Dv SO_LINGER
216 option is set for the socket with non-zero linger time, and the socket has
217 untransmitted data, then
218 .Fn close
219 will block for up to the current linger interval until all data is transmitted.
220 .Sh RETURN VALUES
221 .Rv -std close
222 .Sh EXAMPLES
223 .Sy Example 1
224 Reassign a file descriptor.
225 .Pp
226 The following example closes the file descriptor associated with standard
227 output for the current process, re-assigns standard output to a new file
228 descriptor, and closes the original file descriptor to clean up.
229 This example assumes that the file descriptor
230 .Sy 0 ,
231 which is the descriptor for standard input, is not closed.
232 .Bd -literal -offset Ds
233 #include <unistd.h>
234 \&...
235 int pfd;
236 \&...
237 close(1);
238 dup(pfd);
239 close(pfd);
240 \&...
241 .Ed
242 .Pp
243 Incidentally, this is exactly what could be achieved using:
244 .Bd -literal -offset Ds
245 dup2(pfd, 1);
246 close(pfd);
247 .Ed
248 .Pp
249 .Sy Example 2
250 Close a file descriptor.
251 .Pp
252 In the following example,
253 .Fn close
254 is used to close a file descriptor after an unsuccessful attempt is made to
255 associate that file descriptor with a stream.
256 .Bd -literal -offset Ds
257 #include <stdio.h>
258 #include <unistd.h>
259 #include <stdlib.h>
260
261 #define LOCKFILE "/etc/ptmp"
262 \&...
263 int pfd;
264 FILE *fpfd;
265 \&...
266 if ((fpfd = fdopen (pfd, "w")) == NULL) {
267 close(pfd);
268 unlink(LOCKFILE);
269 exit(1);
270 }
271 \&...
272 .Ed
273 .Sh ERRORS
274 The
275 .Fn close
276 function will fail if:
277 .Bl -tag -width Er
278 .It Er EBADF
279 The
280 .Fa fildes
281 argument is not a valid file descriptor.
282 .It Er EINTR
283 The
284 .Fn close
285 function was interrupted by a signal.
286 .It Er ENOLINK
287 The
288 .Fa fildes
289 argument is on a remote machine and the link to that machine is no longer
290 active.
291 .It Er ENOSPC
292 There was no free space remaining on the device containing the file.
293 .El
294 .Pp
295 The
296 .Fn close
297 function may fail if:
298 .Bl -tag -width Er
299 .It Er EIO
300 An I/O error occurred while reading from or writing to the file system.
301 .El
302 .Sh USAGE
303 An application that used the
304 .Xr stdio 3C
305 function
306 .Xr fopen 3C
307 to open a file should use the corresponding
308 .Xr fclose 3C
309 function rather than
310 .Fn close .
311 .Sh INTERFACE STABILITY
312 .Sy Committed
313 .Sh MT-LEVEL
314 .Sy Async-Signal-Safe
315 .Sh SEE ALSO
316 .Xr creat 2 ,
317 .Xr dup 2 ,
318 .Xr exec 2 ,
319 .Xr fcntl 2 ,
320 .Xr Intro 2 ,
321 .Xr ioctl 2 ,
322 .Xr open 2 ,
323 .Xr pipe 2 ,
324 .Xr fattach 3C ,
325 .Xr fclose 3C ,
326 .Xr fdetach 3C ,
327 .Xr fopen 3C ,
328 .Xr signal 3C ,
329 .Xr signal.h 3HEAD ,
330 .Xr attributes 5 ,
331 .Xr standards 5 ,
332 .Xr streamio 7I
|