Print this page
14249 pseudo-terminal nomenclature should reflect POSIX
Change-Id: Ib4a3cef899ff4c71b09cb0dc6878863c5e8357bc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man2/close.2
+++ new/usr/src/man/man2/close.2
1 1 .\"
2 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 3 .\" permission to reproduce portions of its copyrighted documentation.
4 4 .\" Original documentation from The Open Group can be obtained online at
5 5 .\" http://www.opengroup.org/bookstore/.
6 6 .\"
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 8 .\" Group, have given us permission to reprint portions of their
9 9 .\" documentation.
10 10 .\"
11 11 .\" In the following statement, the phrase ``this text'' refers to portions
12 12 .\" of the system documentation.
13 13 .\"
14 14 .\" Portions of this text are reprinted and reproduced in electronic form
15 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 16 .\" Standard for Information Technology -- Portable Operating System
17 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 20 .\" between these versions and the original IEEE and The Open Group
21 21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 22 .\" document. The original Standard can be obtained online at
23 23 .\" http://www.opengroup.org/unix/online.html.
24 24 .\"
25 25 .\" This notice shall appear on any product containing this material.
26 26 .\"
27 27 .\" The contents of this file are subject to the terms of the
28 28 .\" Common Development and Distribution License (the "License").
29 29 .\" You may not use this file except in compliance with the License.
30 30 .\"
31 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 32 .\" or http://www.opensolaris.org/os/licensing.
33 33 .\" See the License for the specific language governing permissions
34 34 .\" and limitations under the License.
35 35 .\"
|
↓ open down ↓ |
35 lines elided |
↑ open up ↑ |
36 36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 38 .\" If applicable, add the following below this CDDL HEADER, with the
39 39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 41 .\"
42 42 .\"
43 43 .\" Copyright 1989 AT&T
44 44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 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
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
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
79 99 When all file descriptors associated with an open file description have been
80 100 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
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
100 158 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
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
121 188 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
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
128 200 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
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
132 206 the close results in the memory object becoming unreferenced, and the memory
133 207 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
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
204 226 The following example closes the file descriptor associated with standard
205 227 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
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
213 233 #include <unistd.h>
214 234 \&...
215 235 int pfd;
216 236 \&...
217 237 close(1);
218 238 dup(pfd);
219 239 close(pfd);
220 240 \&...
221 -.fi
222 -.in -2
223 -
224 -.sp
225 -.LP
241 +.Ed
242 +.Pp
226 243 Incidentally, this is exactly what could be achieved using:
227 -
228 -.sp
229 -.in +2
230 -.nf
244 +.Bd -literal -offset Ds
231 245 dup2(pfd, 1);
232 246 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 +.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
247 257 #include <stdio.h>
248 258 #include <unistd.h>
249 259 #include <stdlib.h>
250 260
251 261 #define LOCKFILE "/etc/ptmp"
252 262 \&...
253 263 int pfd;
254 264 FILE *fpfd;
255 265 \&...
256 266 if ((fpfd = fdopen (pfd, "w")) == NULL) {
257 267 close(pfd);
258 268 unlink(LOCKFILE);
259 269 exit(1);
260 270 }
261 271 \&...
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)
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
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX