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