close.2 (66492cf01c4f0eb178cb6e056451d04be61a0374) close.2 (1fa2a66491e7d8ae0be84e7da4da8e812480c710)
1.\"
2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3.\" permission to reproduce portions of its copyrighted documentation.
4.\" Original documentation from The Open Group can be obtained online at
5.\" http://www.opengroup.org/bookstore/.
6.\"
7.\" The Institute of Electrical and Electronics Engineers and The Open
8.\" Group, have given us permission to reprint portions of their

--- 29 unchanged lines hidden (view full) ---

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.
1.\"
2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3.\" permission to reproduce portions of its copyrighted documentation.
4.\" Original documentation from The Open Group can be obtained online at
5.\" http://www.opengroup.org/bookstore/.
6.\"
7.\" The Institute of Electrical and Electronics Engineers and The Open
8.\" Group, have given us permission to reprint portions of their

--- 29 unchanged lines hidden (view full) ---

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
46.\"
47.\"
47.TH CLOSE 2 "Oct 18, 2005"
48.SH NAME
49close \- 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
61The \fBclose()\fR function deallocates the file descriptor indicated by
62\fIfildes\fR. To deallocate means to make the file descriptor available for
63return by subsequent calls to \fBopen\fR(2) or other functions that allocate
64file descriptors. All outstanding record locks owned by the process on the file
65associated with the file descriptor will be removed (that is, unlocked).
66.sp
67.LP
68If \fBclose()\fR is interrupted by a signal that is to be caught, it will
69return \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
71writing 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
75When all file descriptors associated with a pipe or \fBFIFO\fR special file are
76closed, any data remaining in the pipe or \fBFIFO\fR will be discarded.
77.sp
78.LP
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
61The
62.Fn close
63function deallocates the file descriptor indicated by
64.Fa fildes .
65To deallocate means to make the file descriptor available for return by
66subsequent calls to
67.Xr open 2
68or other functions that allocate file descriptors.
69All outstanding record locks owned by the process on the file associated with
70the file descriptor will be removed
71.Pq "that is, unlocked" .
72.Pp
73If
74.Fn close
75is interrupted by a signal that is to be caught, it will return
76.Sy -1
77with
78.Va errno
79set to
80.Er EINTR
81and the state of
82.Fa fildes
83is unspecified.
84If an I/O error occurred while reading from or writing to the file system during
85.Fn close ,
86it returns
87.Sy -1 ,
88sets
89.Va errno
90to
91.Er EIO ,
92and the state of
93.Fa fildes
94is unspecified.
95.Pp
96When all file descriptors associated with a pipe or FIFO special file are
97closed, any data remaining in the pipe or FIFO will be discarded.
98.Pp
79When all file descriptors associated with an open file description have been
80closed the open file description will be freed.
99When all file descriptors associated with an open file description have been
100closed the open file description will be freed.
81.sp
82.LP
83If the link count of the file is 0, when all file descriptors associated with
84the file are closed, the space occupied by the file will be freed and the file
85will no longer be accessible.
86.sp
87.LP
88If a streams-based (see \fBIntro\fR(2)) \fIfildes\fR is closed and the calling
89process 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
92associated with the stream. The last \fBclose()\fR for a stream causes the
93stream 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
95stream, and if there is data on the module's write queue, \fBclose()\fR waits
96up to 15 seconds (for each module and driver) for any output to drain before
97dismantling 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
101.Pp
102If the link count of the file is
103.Sy 0 ,
104when all file descriptors associated with the file are closed, the space
105occupied by the file will be freed and the file will no longer be accessible.
106.Pp
107If a streams-based
108.Po
109see
110.Xr Intro 2
111.Pc
112.Fa fildes
113is closed and the calling process was previously registered to receive a
114.Dv SIGPOLL
115signal
116.Po
117see
118.Xr signal 3C
119.Pc
120for events associated with that stream
121.Po
122see
123.Dv I_SETSIG
124in
125.Xr streamio 7I
126.Pc ,
127the calling process will be unregistered for events associated with the stream.
128The last
129.Fn close
130for a stream causes the stream associated with
131.Fa fildes
132to be dismantled.
133If
134.Dv O_NONBLOCK
135and
136.Dv O_NDELAY
137are not set and there have been no signals posted for the stream, and if there
138is data on the module's write queue,
139.Fn close
140waits up to 15 seconds
141.Pq for each module and driver
142for any output to drain
143before dismantling the stream.
144The time delay can be changed via an
145.Dv I_SETCLTIME
146.Xr ioctl 2
147request
148.Po
149see
150.Xr streamio 7I
151.Pc .
152If the
153.Dv O_NONBLOCK
154or
155.Dv O_NDELAY
156flag is set, or if there are any pending signals,
157.Fn close
100does not wait for output to drain, and dismantles the stream immediately.
158does not wait for output to drain, and dismantles the stream immediately.
101.sp
102.LP
103If \fIfildes\fR is associated with one end of a pipe, the last \fBclose()\fR
104causes a hangup to occur on the other end of the pipe. In addition, if the
105other 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
107named end has no open file descriptors associated with it and gets detached,
108the stream associated with that end is also dismantled.
109.sp
110.LP
111If \fIfildes\fR refers to the master side of a pseudo-terminal, a \fBSIGHUP\fR
112signal is sent to the session leader, if any, for which the slave side of the
113pseudo-terminal is the controlling terminal. It is unspecified whether closing
114the master side of the pseudo-terminal flushes all queued input and output.
115.sp
116.LP
117If \fIfildes\fR refers to the slave side of a streams-based pseudo-terminal, a
118zero-length message may be sent to the master.
119.sp
120.LP
159.Pp
160If
161.Fa fildes
162is associated with one end of a pipe, the last
163.Fn close
164causes a hangup to occur on the other end of the pipe.
165In addition, if the other end of the pipe has been named by
166.Xr fattach 3C ,
167then the last
168.Fn close
169forces the named end to be detached by
170.Xr fdetach 3C .
171If the named end has no open file descriptors associated with it and gets
172detached, the stream associated with that end is also dismantled.
173.Pp
174If
175.Fa fildes
176refers to the manager side of a pseudo-terminal, a
177.Dv SIGHUP
178signal is sent to the session leader, if any, for which the subsidiary side of
179the pseudo-terminal is the controlling terminal.
180It is unspecified whether closing the manager side of the pseudo-terminal
181flushes all queued input and output.
182.Pp
183If
184.Fa fildes
185refers to the subsidiary side of a streams-based pseudo-terminal, a zero-length
186message may be sent to the manager.
187.Pp
121When there is an outstanding cancelable asynchronous I/O operation against
188When 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
123I/O operation that is not canceled completes as if the \fBclose()\fR operation
124had not yet occurred. All operations that are not canceled will complete as if
125the \fBclose()\fR blocked until the operations completed.
126.sp
127.LP
189.Fa fildes
190when
191.Fn close
192is called, that I/O operation is canceled.
193An I/O operation that is not canceled completes as if the
194.Fn close
195operation had not yet occurred.
196All operations that are not canceled will complete as if the
197.Fn close
198blocked until the operations completed.
199.Pp
128If a shared memory object or a memory mapped file remains referenced at the
200If a shared memory object or a memory mapped file remains referenced at the
129last close (that is, a process has it mapped), then the entire contents of the
130memory object will persist until the memory object becomes unreferenced. If
131this is the last close of a shared memory object or a memory mapped file and
201last close
202.Pq "that is, a process has it mapped" ,
203then the entire contents of the memory object will persist until the memory
204object becomes unreferenced.
205If this is the last close of a shared memory object or a memory mapped file and
132the close results in the memory object becoming unreferenced, and the memory
133object has been unlinked, then the memory object will be removed.
206the close results in the memory object becoming unreferenced, and the memory
207object has been unlinked, then the memory object will be removed.
134.sp
135.LP
136If \fIfildes\fR refers to a socket, \fBclose()\fR causes the socket to be
137destroyed. If the socket is connection-mode, and the \fBSO_LINGER\fR option is
138set for the socket with non-zero linger time, and the socket has untransmitted
139data, then \fBclose()\fR will block for up to the current linger interval until
140all data is transmitted.
141.SH RETURN VALUES
142.sp
143.LP
144Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
145returned and \fBerrno\fR is set to indicate the error.
146.SH ERRORS
147.sp
148.LP
149The \fBclose()\fR function will fail if:
150.sp
151.ne 2
152.na
153\fB\fBEBADF\fR\fR
154.ad
155.RS 11n
156The \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
165The \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
174The \fIfildes\fR argument is on a remote machine and the link to that machine
175is no longer active.
176.RE
177
178.sp
179.ne 2
180.na
181\fB\fBENOSPC\fR\fR
182.ad
183.RS 11n
184There was no free space remaining on the device containing the file.
185.RE
186
187.sp
188.LP
189The \fBclose()\fR function may fail if:
190.sp
191.ne 2
192.na
193\fB\fBEIO\fR\fR
194.ad
195.RS 7n
196An 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
208.Pp
209If
210.Fa fildes
211refers to a socket,
212.Fn close
213causes the socket to be destroyed.
214If the socket is connection-mode, and the
215.Dv SO_LINGER
216option is set for the socket with non-zero linger time, and the socket has
217untransmitted data, then
218.Fn close
219will 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
224Reassign a file descriptor.
225.Pp
204The following example closes the file descriptor associated with standard
205output for the current process, re-assigns standard output to a new file
226The following example closes the file descriptor associated with standard
227output for the current process, re-assigns standard output to a new file
206descriptor, and closes the original file descriptor to clean up. This example
207assumes that the file descriptor 0, which is the descriptor for standard input,
208is not closed.
209
210.sp
211.in +2
212.nf
228descriptor, and closes the original file descriptor to clean up.
229This example assumes that the file descriptor
230.Sy 0 ,
231which is the descriptor for standard input, is not closed.
232.Bd -literal -offset Ds
213#include <unistd.h>
214\&...
215int pfd;
216\&...
217close(1);
218dup(pfd);
219close(pfd);
220\&...
233#include <unistd.h>
234\&...
235int pfd;
236\&...
237close(1);
238dup(pfd);
239close(pfd);
240\&...
221.fi
222.in -2
223
224.sp
225.LP
241.Ed
242.Pp
226Incidentally, this is exactly what could be achieved using:
243Incidentally, this is exactly what could be achieved using:
227
228.sp
229.in +2
230.nf
244.Bd -literal -offset Ds
231dup2(pfd, 1);
232close(pfd);
245dup2(pfd, 1);
246close(pfd);
233.fi
234.in -2
235
236.LP
237\fBExample 2 \fRClose a file descriptor.
238.sp
239.LP
240In the following example, \fBclose()\fR is used to close a file descriptor
241after an unsuccessful attempt is made to associate that file descriptor with a
242stream.
243
244.sp
245.in +2
246.nf
247.Ed
248.Pp
249.Sy Example 2
250Close a file descriptor.
251.Pp
252In the following example,
253.Fn close
254is used to close a file descriptor after an unsuccessful attempt is made to
255associate that file descriptor with a stream.
256.Bd -literal -offset Ds
247#include <stdio.h>
248#include <unistd.h>
249#include <stdlib.h>
250
251#define LOCKFILE "/etc/ptmp"
252\&...
253int pfd;
254FILE *fpfd;
255\&...
256if ((fpfd = fdopen (pfd, "w")) == NULL) {
257 close(pfd);
258 unlink(LOCKFILE);
259 exit(1);
260}
261\&...
257#include <stdio.h>
258#include <unistd.h>
259#include <stdlib.h>
260
261#define LOCKFILE "/etc/ptmp"
262\&...
263int pfd;
264FILE *fpfd;
265\&...
266if ((fpfd = fdopen (pfd, "w")) == NULL) {
267 close(pfd);
268 unlink(LOCKFILE);
269 exit(1);
270}
271\&...
262.fi
263.in -2
264
265.SH USAGE
266.sp
267.LP
268An application that used the \fBstdio\fR function \fBfopen\fR(3C) to open a
269file should use the corresponding \fBfclose\fR(3C) function rather than
270\fBclose()\fR.
271.SH ATTRIBUTES
272.sp
273.LP
274See \fBattributes\fR(5) for descriptions of the following attributes:
275.sp
276
277.sp
278.TS
279box;
280c | c
281l | l .
282ATTRIBUTE TYPE ATTRIBUTE VALUE
283_
284Interface Stability Standard
285_
286MT-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)
272.Ed
273.Sh ERRORS
274The
275.Fn close
276function will fail if:
277.Bl -tag -width Er
278.It Er EBADF
279The
280.Fa fildes
281argument is not a valid file descriptor.
282.It Er EINTR
283The
284.Fn close
285function was interrupted by a signal.
286.It Er ENOLINK
287The
288.Fa fildes
289argument is on a remote machine and the link to that machine is no longer
290active.
291.It Er ENOSPC
292There was no free space remaining on the device containing the file.
293.El
294.Pp
295The
296.Fn close
297function may fail if:
298.Bl -tag -width Er
299.It Er EIO
300An I/O error occurred while reading from or writing to the file system.
301.El
302.Sh USAGE
303An application that used the
304.Xr stdio 3C
305function
306.Xr fopen 3C
307to open a file should use the corresponding
308.Xr fclose 3C
309function 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