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
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
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