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 .\"
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)