1 CLOSE(2) System Calls CLOSE(2)
2
3 NAME
4 close - close a file descriptor
5
6 SYNOPSIS
7 #include <unistd.h>
8
9 int close(int fildes);
10
11
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).
19
20
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
27
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.
30
31
32 When all file descriptors associated with an open file description have
33 been closed the open file description will be freed.
34
35
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.
39
40
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.
54
55
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 RETURN VALUES
98 Upon successful completion, 0 is returned. Otherwise, -1 is returned
99 and errno is set to indicate the error.
100
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 EXAMPLES
131 Example 1 Reassign a file descriptor.
132
133
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.
139
140
141 #include <unistd.h>
142 ...
143 int pfd;
144 ...
145 close(1);
146 dup(pfd);
147 close(pfd);
148 ...
149
150
151
152 Incidentally, this is exactly what could be achieved using:
153
154
155 dup2(pfd, 1);
156 close(pfd);
157
158
159 Example 2 Close a file descriptor.
160
161
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.
165
166
167 #include <stdio.h>
168 #include <unistd.h>
169 #include <stdlib.h>
170
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 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().
187
188 ATTRIBUTES
189 See attributes(5) for descriptions of the following attributes:
190
191
192
193
194 +--------------------+-------------------+
195 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
196 +--------------------+-------------------+
197 |Interface Stability | Standard |
198 +--------------------+-------------------+
199 |MT-Level | Async-Signal-Safe |
200 +--------------------+-------------------+
201
202 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)
206
207 October 18, 2005 CLOSE(2)
|
1 CLOSE(2) System Calls CLOSE(2)
2
3 NAME
4 close - close a file descriptor
5
6 SYNOPSIS
7 #include <unistd.h>
8
9 int
10 close(int fildes);
11
12 DESCRIPTION
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
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.
25
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.
28
29 When all file descriptors associated with an open file description have
30 been closed the open file description will be freed.
31
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.
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.
49
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.
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.
62
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.
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.
71
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.
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.
85
86 RETURN VALUES
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.
90
91 EXAMPLES
92 Example 1 Reassign a file descriptor.
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.
99
100 #include <unistd.h>
101 ...
102 int pfd;
103 ...
104 close(1);
105 dup(pfd);
106 close(pfd);
107 ...
108
109 Incidentally, this is exactly what could be achieved using:
110
111 dup2(pfd, 1);
112 close(pfd);
113
114 Example 2 Close a file descriptor.
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.
119
120 #include <stdio.h>
121 #include <unistd.h>
122 #include <stdlib.h>
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 ...
135
136 ERRORS
137 The close() function will fail if:
138
139 EBADF The fildes argument is not a valid file descriptor.
140
141 EINTR The close() function was interrupted by a signal.
142
143 ENOLINK The fildes argument is on a remote machine and the
144 link to that machine is no longer active.
145
146 ENOSPC There was no free space remaining on the device
147 containing the file.
148
149 The close() function may fail if:
150
151 EIO An I/O error occurred while reading from or writing to
152 the file system.
153
154 USAGE
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().
157
158 INTERFACE STABILITY
159 Committed
160
161 MT-LEVEL
162 Async-Signal-Safe
163
164 SEE ALSO
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)
168
169 illumos February 5, 2022 illumos
|