1CLOSE(3P)                  POSIX Programmer's Manual                 CLOSE(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       close — close a file descriptor
13

SYNOPSIS

15       #include <unistd.h>
16
17       int close(int fildes);
18

DESCRIPTION

20       The close() function shall deallocate the file descriptor indicated  by
21       fildes.   To deallocate means to make the file descriptor available for
22       return by subsequent calls to open() or other functions  that  allocate
23       file  descriptors. All outstanding record locks owned by the process on
24       the file associated with the file descriptor shall be removed (that is,
25       unlocked).
26
27       If  close()  is  interrupted by a signal that is to be caught, it shall
28       return -1 with errno set to [EINTR] and the state of fildes is unspeci‐
29       fied.  If  an  I/O  error occurred while reading from or writing to the
30       file system during close(), it may return -1 with errno set  to  [EIO];
31       if this error is returned, the state of fildes is unspecified.
32
33       When  all  file descriptors associated with a pipe or FIFO special file
34       are closed, any data remaining in the pipe or FIFO shall be discarded.
35
36       When all file descriptors associated with an open file description have
37       been closed, the open file description shall be freed.
38
39       If  the  link count of the file is 0, when all file descriptors associ‐
40       ated with the file are closed, the space occupied by the file shall  be
41       freed and the file shall no longer be accessible.
42
43       If  a STREAMS-based fildes is closed and the calling process was previ‐
44       ously registered to receive a SIGPOLL signal for events associated with
45       that STREAM, the calling process shall be unregistered for events asso‐
46       ciated with the STREAM. The last close() for a STREAM shall  cause  the
47       STREAM  associated  with  fildes to be dismantled. If O_NONBLOCK is not
48       set and there have been no signals posted for the STREAM, and if  there
49       is data on the module's write queue, close() shall wait for an unspeci‐
50       fied time (for each module and driver) for any output to  drain  before
51       dismantling  the  STREAM.  The  time delay can be changed via an I_SET‐
52       CLTIME ioctl() request. If the O_NONBLOCK flag is set, or if there  are
53       any  pending  signals,  close() shall not wait for output to drain, and
54       shall dismantle the STREAM immediately.
55
56       If the implementation supports STREAMS-based pipes, and fildes is asso‐
57       ciated with one end of a pipe, the last close() shall cause a hangup to
58       occur on the other end of the pipe. In addition, if the  other  end  of
59       the pipe has been named by fattach(), then the last close() shall force
60       the named end to be detached by fdetach().  If the  named  end  has  no
61       open  file descriptors associated with it and gets detached, the STREAM
62       associated with that end shall also be dismantled.
63
64       If fildes refers to the master side of a pseudo-terminal, and  this  is
65       the  last  close,  a  SIGHUP  signal  shall  be sent to the controlling
66       process, if any, for which the slave side of the pseudo-terminal is the
67       controlling terminal. It is unspecified whether closing the master side
68       of the pseudo-terminal flushes all queued input and output.
69
70       If fildes refers to the slave side of a STREAMS-based  pseudo-terminal,
71       a zero-length message may be sent to the master.
72
73       When  there  is  an  outstanding  cancelable asynchronous I/O operation
74       against fildes when close() is called, that I/O operation may  be  can‐
75       celed.  An  I/O  operation  that  is  not  canceled completes as if the
76       close() operation had not yet occurred. All  operations  that  are  not
77       canceled  shall complete as if the close() blocked until the operations
78       completed. The close() operation itself need not  block  awaiting  such
79       I/O  completion.  Whether  any I/O operation is canceled, and which I/O
80       operation may be canceled upon close(), is implementation-defined.
81
82       If a memory mapped file or a shared memory object remains referenced at
83       the last close (that is, a process has it mapped), then the entire con‐
84       tents of the memory  object  shall  persist  until  the  memory  object
85       becomes  unreferenced.   If  this  is the last close of a memory mapped
86       file or a shared memory object and the  close  results  in  the  memory
87       object  becoming unreferenced, and the memory object has been unlinked,
88       then the memory object shall be removed.
89
90       If fildes refers to a socket, close() shall  cause  the  socket  to  be
91       destroyed.  If  the  socket  is  in  connection-mode, and the SO_LINGER
92       option is set for the socket with non-zero linger time, and the  socket
93       has  untransmitted data, then close() shall block for up to the current
94       linger interval until all data is transmitted.
95

RETURN VALUE

97       Upon successful completion, 0 shall be returned; otherwise, -1 shall be
98       returned and errno set to indicate the error.
99

ERRORS

101       The close() function shall fail if:
102
103       EBADF  The fildes argument is not a open file descriptor.
104
105       EINTR  The close() function was interrupted by a signal.
106
107       The close() function may fail if:
108
109       EIO    An  I/O error occurred while reading from or writing to the file
110              system.
111
112       The following sections are informative.
113

EXAMPLES

115   Reassigning a File Descriptor
116       The following example closes the file descriptor associated with  stan‐
117       dard  output  for  the current process, re-assigns standard output to a
118       new file descriptor, and closes the original file descriptor  to  clean
119       up.  This  example  assumes  that  the  file descriptor 0 (which is the
120       descriptor for standard input) is not closed.
121
122
123           #include <unistd.h>
124           ...
125           int pfd;
126           ...
127           close(1);
128           dup(pfd);
129           close(pfd);
130           ...
131
132       Incidentally, this is exactly what could be achieved using:
133
134
135           dup2(pfd, 1);
136           close(pfd);
137
138   Closing a File Descriptor
139       In the following example, close() is used to close  a  file  descriptor
140       after an unsuccessful attempt is made to associate that file descriptor
141       with a stream.
142
143
144           #include <stdio.h>
145           #include <unistd.h>
146           #include <stdlib.h>
147
148           #define LOCKFILE "/etc/ptmp"
149           ...
150           int pfd;
151           FILE *fpfd;
152           ...
153           if ((fpfd = fdopen (pfd, "w")) == NULL) {
154               close(pfd);
155               unlink(LOCKFILE);
156               exit(1);
157           }
158           ...
159

APPLICATION USAGE

161       An application that had used the stdio routine fopen() to open  a  file
162       should  use  the  corresponding  fclose()  routine rather than close().
163       Once a file is closed, the file descriptor no longer exists, since  the
164       integer corresponding to it no longer refers to a file.
165
166       Implementations  may  use  file descriptors that must be inherited into
167       child processes for the child process to remain conforming, such as for
168       message  catalog  or  tracing  purposes. Therefore, an application that
169       calls close() on an arbitrary integer  risks  non-conforming  behavior,
170       and  close()  can  only portably be used on file descriptor values that
171       the application has obtained through explicit actions, as well  as  the
172       three  file  descriptors corresponding to the standard file streams. In
173       multi-threaded parent applications, the practice of calling close()  in
174       a  loop  after  fork() and before an exec call in order to avoid a race
175       condition of  leaking  an  unintended  file  descriptor  into  a  child
176       process,  is therefore unsafe, and the race should instead be combatted
177       by opening all file descriptors with the FD_CLOEXEC bit set unless  the
178       file descriptor is intended to be inherited across exec.
179
180       Usage  of  close()  on file descriptors STDIN_FILENO, STDOUT_FILENO, or
181       STDERR_FILENO should immediately be followed by an operation to  reopen
182       these file descriptors. Unexpected behavior will result if any of these
183       file descriptors is left in a closed state  (for  example,  an  [EBADF]
184       error from perror()) or if an unrelated open() or similar call later in
185       the application accidentally allocates a file to  one  of  these  well-
186       known  file  descriptors.  Furthermore,  a close() followed by a reopen
187       operation (e.g., open(), dup(), etc.) is not atomic; dup2()  should  be
188       used to change standard file descriptors.
189

RATIONALE

191       The use of interruptible device close routines should be discouraged to
192       avoid problems with the implicit closes of file descriptors by exec and
193       exit().  This volume of POSIX.1‐2017 only intends to permit such behav‐
194       ior by specifying the [EINTR] error condition.
195
196       Note that the requirement for close() on a socket to block  for  up  to
197       the  current  linger interval is not conditional on the O_NONBLOCK set‐
198       ting.
199
200       The standard developers rejected a proposal to add closefrom()  to  the
201       standard. Because the standard permits implementations to use inherited
202       file descriptors as a means of providing a conforming  environment  for
203       the  child process, it is not possible to standardize an interface that
204       closes arbitrary file descriptors above a  certain  value  while  still
205       guaranteeing a conforming environment.
206

FUTURE DIRECTIONS

208       None.
209

SEE ALSO

211       Section  2.6,  STREAMS,  dup(), exec, exit(), fattach(), fclose(), fde‐
212       tach(), fopen(), fork(), ioctl(), open(), perror(), unlink()
213
214       The Base Definitions volume of POSIX.1‐2017, <unistd.h>
215
217       Portions of this text are reprinted and reproduced in  electronic  form
218       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
219       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
220       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
221       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
222       event of any discrepancy between this version and the original IEEE and
223       The Open Group Standard, the original IEEE and The Open Group  Standard
224       is  the  referee document. The original Standard can be obtained online
225       at http://www.opengroup.org/unix/online.html .
226
227       Any typographical or formatting errors that appear  in  this  page  are
228       most likely to have been introduced during the conversion of the source
229       files to man page format. To report such errors,  see  https://www.ker
230       nel.org/doc/man-pages/reporting_bugs.html .
231
232
233
234IEEE/The Open Group                  2017                            CLOSE(3P)
Impressum