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.man.txt
+++ new/usr/src/man/man2/close.2.man.txt
1 1 CLOSE(2) System Calls CLOSE(2)
2 2
3 3 NAME
4 - close - close a file descriptor
4 + close - close a file descriptor
5 5
6 6 SYNOPSIS
7 - #include <unistd.h>
7 + #include <unistd.h>
8 8
9 - int close(int fildes);
9 + int
10 + close(int fildes);
10 11
11 -
12 12 DESCRIPTION
13 - The close() function deallocates the file descriptor indicated by
14 - fildes. To deallocate means to make the file descriptor available for
15 - return by subsequent calls to open(2) or other functions that allocate
16 - file descriptors. All outstanding record locks owned by the process on
17 - the file associated with the file descriptor will be removed (that is,
18 - unlocked).
13 + The close() function deallocates the file descriptor indicated by fildes.
14 + To deallocate means to make the file descriptor available for return by
15 + subsequent calls to open(2) or other functions that allocate file
16 + descriptors. All outstanding record locks owned by the process on the
17 + file associated with the file descriptor will be removed (that is,
18 + unlocked).
19 19
20 + If close() is interrupted by a signal that is to be caught, it will
21 + return -1 with errno set to EINTR and the state of fildes is unspecified.
22 + If an I/O error occurred while reading from or writing to the file system
23 + during close(), it returns -1, sets errno to EIO, and the state of fildes
24 + is unspecified.
20 25
21 - If close() is interrupted by a signal that is to be caught, it will
22 - return -1 with errno set to EINTR and the state of fildes is
23 - unspecified. If an I/O error occurred while reading from or writing to
24 - the file system during close(), it returns -1, sets errno to EIO, and
25 - the state of fildes is unspecified.
26 + When all file descriptors associated with a pipe or FIFO special file are
27 + closed, any data remaining in the pipe or FIFO will be discarded.
26 28
29 + When all file descriptors associated with an open file description have
30 + been closed the open file description will be freed.
27 31
28 - When all file descriptors associated with a pipe or FIFO special file
29 - are closed, any data remaining in the pipe or FIFO will be discarded.
32 + If the link count of the file is 0, when all file descriptors associated
33 + with the file are closed, the space occupied by the file will be freed
34 + and the file will no longer be accessible.
30 35
36 + If a streams-based (see Intro(2)) fildes is closed and the calling
37 + process was previously registered to receive a SIGPOLL signal (see
38 + signal(3C)) for events associated with that stream (see I_SETSIG in
39 + streamio(7I)), the calling process will be unregistered for events
40 + associated with the stream. The last close() for a stream causes the
41 + stream associated with fildes to be dismantled. If O_NONBLOCK and
42 + O_NDELAY are not set and there have been no signals posted for the
43 + stream, and if there is data on the module's write queue, close() waits
44 + up to 15 seconds (for each module and driver) for any output to drain
45 + before dismantling the stream. The time delay can be changed via an
46 + I_SETCLTIME ioctl(2) request (see streamio(7I)). If the O_NONBLOCK or
47 + O_NDELAY flag is set, or if there are any pending signals, close() does
48 + not wait for output to drain, and dismantles the stream immediately.
31 49
32 - When all file descriptors associated with an open file description have
33 - been closed the open file description will be freed.
50 + If fildes is associated with one end of a pipe, the last close() causes a
51 + hangup to occur on the other end of the pipe. In addition, if the other
52 + end of the pipe has been named by fattach(3C), then the last close()
53 + forces the named end to be detached by fdetach(3C). If the named end has
54 + no open file descriptors associated with it and gets detached, the stream
55 + associated with that end is also dismantled.
34 56
57 + If fildes refers to the manager side of a pseudo-terminal, a SIGHUP
58 + signal is sent to the session leader, if any, for which the subsidiary
59 + side of the pseudo-terminal is the controlling terminal. It is
60 + unspecified whether closing the manager side of the pseudo-terminal
61 + flushes all queued input and output.
35 62
36 - If the link count of the file is 0, when all file descriptors
37 - associated with the file are closed, the space occupied by the file
38 - will be freed and the file will no longer be accessible.
63 + If fildes refers to the subsidiary side of a streams-based pseudo-
64 + terminal, a zero-length message may be sent to the manager.
39 65
66 + When there is an outstanding cancelable asynchronous I/O operation
67 + against fildes when close() is called, that I/O operation is canceled.
68 + An I/O operation that is not canceled completes as if the close()
69 + operation had not yet occurred. All operations that are not canceled
70 + will complete as if the close() blocked until the operations completed.
40 71
41 - If a streams-based (see Intro(2)) fildes is closed and the calling
42 - process was previously registered to receive a SIGPOLL signal (see
43 - signal(3C)) for events associated with that stream (see I_SETSIG in
44 - streamio(7I)), the calling process will be unregistered for events
45 - associated with the stream. The last close() for a stream causes the
46 - stream associated with fildes to be dismantled. If O_NONBLOCK and
47 - O_NDELAY are not set and there have been no signals posted for the
48 - stream, and if there is data on the module's write queue, close() waits
49 - up to 15 seconds (for each module and driver) for any output to drain
50 - before dismantling the stream. The time delay can be changed via an
51 - I_SETCLTIME ioctl(2) request (see streamio(7I)). If the O_NONBLOCK or
52 - O_NDELAY flag is set, or if there are any pending signals, close() does
53 - not wait for output to drain, and dismantles the stream immediately.
72 + If a shared memory object or a memory mapped file remains referenced at
73 + the last close (that is, a process has it mapped), then the entire
74 + contents of the memory object will persist until the memory object
75 + becomes unreferenced. If this is the last close of a shared memory
76 + object or a memory mapped file and the close results in the memory object
77 + becoming unreferenced, and the memory object has been unlinked, then the
78 + memory object will be removed.
54 79
80 + If fildes refers to a socket, close() causes the socket to be destroyed.
81 + If the socket is connection-mode, and the SO_LINGER option is set for the
82 + socket with non-zero linger time, and the socket has untransmitted data,
83 + then close() will block for up to the current linger interval until all
84 + data is transmitted.
55 85
56 - If fildes is associated with one end of a pipe, the last close() causes
57 - a hangup to occur on the other end of the pipe. In addition, if the
58 - other end of the pipe has been named by fattach(3C), then the last
59 - close() forces the named end to be detached by fdetach(3C). If the
60 - named end has no open file descriptors associated with it and gets
61 - detached, the stream associated with that end is also dismantled.
62 -
63 -
64 - If fildes refers to the master side of a pseudo-terminal, a SIGHUP
65 - signal is sent to the session leader, if any, for which the slave side
66 - of the pseudo-terminal is the controlling terminal. It is unspecified
67 - whether closing the master side of the pseudo-terminal flushes all
68 - queued input and output.
69 -
70 -
71 - If fildes refers to the slave side of a streams-based pseudo-terminal,
72 - a zero-length message may be sent to the master.
73 -
74 -
75 - When there is an outstanding cancelable asynchronous I/O operation
76 - against fildes when close() is called, that I/O operation is canceled.
77 - An I/O operation that is not canceled completes as if the close()
78 - operation had not yet occurred. All operations that are not canceled
79 - will complete as if the close() blocked until the operations completed.
80 -
81 -
82 - If a shared memory object or a memory mapped file remains referenced at
83 - the last close (that is, a process has it mapped), then the entire
84 - contents of the memory object will persist until the memory object
85 - becomes unreferenced. If this is the last close of a shared memory
86 - object or a memory mapped file and the close results in the memory
87 - object becoming unreferenced, and the memory object has been unlinked,
88 - then the memory object will be removed.
89 -
90 -
91 - If fildes refers to a socket, close() causes the socket to be
92 - destroyed. If the socket is connection-mode, and the SO_LINGER option
93 - is set for the socket with non-zero linger time, and the socket has
94 - untransmitted data, then close() will block for up to the current
95 - linger interval until all data is transmitted.
96 -
97 86 RETURN VALUES
98 - Upon successful completion, 0 is returned. Otherwise, -1 is returned
99 - and errno is set to indicate the error.
87 + The close() function returns the value 0 if successful; otherwise the
88 + value -1 is returned and the global variable errno is set to indicate the
89 + error.
100 90
101 -ERRORS
102 - The close() function will fail if:
103 -
104 - EBADF
105 - The fildes argument is not a valid file descriptor.
106 -
107 -
108 - EINTR
109 - The close() function was interrupted by a signal.
110 -
111 -
112 - ENOLINK
113 - The fildes argument is on a remote machine and the link to
114 - that machine is no longer active.
115 -
116 -
117 - ENOSPC
118 - There was no free space remaining on the device containing
119 - the file.
120 -
121 -
122 -
123 - The close() function may fail if:
124 -
125 - EIO
126 - An I/O error occurred while reading from or writing to the file
127 - system.
128 -
129 -
130 91 EXAMPLES
131 - Example 1 Reassign a file descriptor.
92 + Example 1 Reassign a file descriptor.
132 93
94 + The following example closes the file descriptor associated with standard
95 + output for the current process, re-assigns standard output to a new file
96 + descriptor, and closes the original file descriptor to clean up. This
97 + example assumes that the file descriptor 0, which is the descriptor for
98 + standard input, is not closed.
133 99
134 - The following example closes the file descriptor associated with
135 - standard output for the current process, re-assigns standard output to
136 - a new file descriptor, and closes the original file descriptor to clean
137 - up. This example assumes that the file descriptor 0, which is the
138 - descriptor for standard input, is not closed.
100 + #include <unistd.h>
101 + ...
102 + int pfd;
103 + ...
104 + close(1);
105 + dup(pfd);
106 + close(pfd);
107 + ...
139 108
109 + Incidentally, this is exactly what could be achieved using:
140 110
141 - #include <unistd.h>
142 - ...
143 - int pfd;
144 - ...
145 - close(1);
146 - dup(pfd);
147 - close(pfd);
148 - ...
111 + dup2(pfd, 1);
112 + close(pfd);
149 113
114 + Example 2 Close a file descriptor.
150 115
116 + In the following example, close() is used to close a file descriptor
117 + after an unsuccessful attempt is made to associate that file descriptor
118 + with a stream.
151 119
152 - Incidentally, this is exactly what could be achieved using:
120 + #include <stdio.h>
121 + #include <unistd.h>
122 + #include <stdlib.h>
153 123
124 + #define LOCKFILE "/etc/ptmp"
125 + ...
126 + int pfd;
127 + FILE *fpfd;
128 + ...
129 + if ((fpfd = fdopen (pfd, "w")) == NULL) {
130 + close(pfd);
131 + unlink(LOCKFILE);
132 + exit(1);
133 + }
134 + ...
154 135
155 - dup2(pfd, 1);
156 - close(pfd);
136 +ERRORS
137 + The close() function will fail if:
157 138
139 + EBADF The fildes argument is not a valid file descriptor.
158 140
159 - Example 2 Close a file descriptor.
141 + EINTR The close() function was interrupted by a signal.
160 142
143 + ENOLINK The fildes argument is on a remote machine and the
144 + link to that machine is no longer active.
161 145
162 - In the following example, close() is used to close a file descriptor
163 - after an unsuccessful attempt is made to associate that file descriptor
164 - with a stream.
146 + ENOSPC There was no free space remaining on the device
147 + containing the file.
165 148
149 + The close() function may fail if:
166 150
167 - #include <stdio.h>
168 - #include <unistd.h>
169 - #include <stdlib.h>
151 + EIO An I/O error occurred while reading from or writing to
152 + the file system.
170 153
171 - #define LOCKFILE "/etc/ptmp"
172 - ...
173 - int pfd;
174 - FILE *fpfd;
175 - ...
176 - if ((fpfd = fdopen (pfd, "w")) == NULL) {
177 - close(pfd);
178 - unlink(LOCKFILE);
179 - exit(1);
180 - }
181 - ...
182 -
183 -
184 154 USAGE
185 - An application that used the stdio function fopen(3C) to open a file
186 - should use the corresponding fclose(3C) function rather than close().
155 + An application that used the stdio(3C) function fopen(3C) to open a file
156 + should use the corresponding fclose(3C) function rather than close().
187 157
188 -ATTRIBUTES
189 - See attributes(5) for descriptions of the following attributes:
158 +INTERFACE STABILITY
159 + Committed
190 160
161 +MT-LEVEL
162 + Async-Signal-Safe
191 163
192 -
193 -
194 - +--------------------+-------------------+
195 - | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
196 - +--------------------+-------------------+
197 - |Interface Stability | Standard |
198 - +--------------------+-------------------+
199 - |MT-Level | Async-Signal-Safe |
200 - +--------------------+-------------------+
201 -
202 164 SEE ALSO
203 - Intro(2), creat(2), dup(2), exec(2), fcntl(2), ioctl(2), open(2)
204 - pipe(2), fattach(3C), fclose(3C), fdetach(3C), fopen(3C), signal(3C),
205 - signal.h(3HEAD), attributes(5), standards(5), streamio(7I)
165 + creat(2), dup(2), exec(2), fcntl(2), Intro(2), ioctl(2), open(2),
166 + pipe(2), fattach(3C), fclose(3C), fdetach(3C), fopen(3C), signal(3C),
167 + signal.h(3HEAD), attributes(5), standards(5), streamio(7I)
206 168
207 - October 18, 2005 CLOSE(2)
169 +illumos February 5, 2022 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX