xref: /freebsd/lib/libsys/close.2 (revision 053a988497342a6fd0a717cc097d09c23f83e103)
18269e767SBrooks Davis.\" Copyright (c) 1980, 1991, 1993, 1994
28269e767SBrooks Davis.\"	The Regents of the University of California.  All rights reserved.
38269e767SBrooks Davis.\"
48269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without
58269e767SBrooks Davis.\" modification, are permitted provided that the following conditions
68269e767SBrooks Davis.\" are met:
78269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright
88269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer.
98269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright
108269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer in the
118269e767SBrooks Davis.\"    documentation and/or other materials provided with the distribution.
128269e767SBrooks Davis.\" 3. Neither the name of the University nor the names of its contributors
138269e767SBrooks Davis.\"    may be used to endorse or promote products derived from this software
148269e767SBrooks Davis.\"    without specific prior written permission.
158269e767SBrooks Davis.\"
168269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
178269e767SBrooks Davis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
188269e767SBrooks Davis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
198269e767SBrooks Davis.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
208269e767SBrooks Davis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
218269e767SBrooks Davis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
228269e767SBrooks Davis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
238269e767SBrooks Davis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
248269e767SBrooks Davis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
258269e767SBrooks Davis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
268269e767SBrooks Davis.\" SUCH DAMAGE.
278269e767SBrooks Davis.\"
28*053a9884SGleb Smirnoff.Dd December 18, 2024
298269e767SBrooks Davis.Dt CLOSE 2
308269e767SBrooks Davis.Os
318269e767SBrooks Davis.Sh NAME
328269e767SBrooks Davis.Nm close
338269e767SBrooks Davis.Nd delete a descriptor
348269e767SBrooks Davis.Sh LIBRARY
358269e767SBrooks Davis.Lb libc
368269e767SBrooks Davis.Sh SYNOPSIS
378269e767SBrooks Davis.In unistd.h
388269e767SBrooks Davis.Ft int
398269e767SBrooks Davis.Fn close "int fd"
408269e767SBrooks Davis.Sh DESCRIPTION
418269e767SBrooks DavisThe
428269e767SBrooks Davis.Fn close
438269e767SBrooks Davissystem call deletes a descriptor from the per-process object
448269e767SBrooks Davisreference table.
458269e767SBrooks DavisIf this is the last reference to the underlying object, the
468269e767SBrooks Davisobject will be deactivated.
478269e767SBrooks DavisFor example, on the last close of a file
488269e767SBrooks Davisthe current
498269e767SBrooks Davis.Em seek
508269e767SBrooks Davispointer associated with the file is lost;
518269e767SBrooks Davison the last close of a
528269e767SBrooks Davis.Xr socket 2
538269e767SBrooks Davisassociated naming information and queued data are discarded;
548269e767SBrooks Davison the last close of a file holding an advisory lock
558269e767SBrooks Davisthe lock is released (see further
568269e767SBrooks Davis.Xr flock 2 ) .
578269e767SBrooks DavisHowever, the semantics of System V and
588269e767SBrooks Davis.St -p1003.1-88
598269e767SBrooks Davisdictate that all
608269e767SBrooks Davis.Xr fcntl 2
618269e767SBrooks Davisadvisory record locks associated with a file for a given process
628269e767SBrooks Davisare removed when
638269e767SBrooks Davis.Em any
648269e767SBrooks Davisfile descriptor for that file is closed by that process.
658269e767SBrooks Davis.Pp
668269e767SBrooks DavisWhen a process exits,
678269e767SBrooks Davisall associated file descriptors are freed, but since there is
688269e767SBrooks Davisa limit on active descriptors per processes, the
698269e767SBrooks Davis.Fn close
708269e767SBrooks Davissystem call
718269e767SBrooks Davisis useful when a large quantity of file descriptors are being handled.
728269e767SBrooks Davis.Pp
738269e767SBrooks DavisWhen a process forks (see
748269e767SBrooks Davis.Xr fork 2 ) ,
758269e767SBrooks Davisall descriptors for the new child process reference the same
768269e767SBrooks Davisobjects as they did in the parent before the fork.
778269e767SBrooks DavisIf a new process is then to be run using
788269e767SBrooks Davis.Xr execve 2 ,
798269e767SBrooks Davisthe process would normally inherit these descriptors.
808269e767SBrooks DavisMost
818269e767SBrooks Davisof the descriptors can be rearranged with
828269e767SBrooks Davis.Xr dup2 2
838269e767SBrooks Davisor deleted with
848269e767SBrooks Davis.Fn close
858269e767SBrooks Davisbefore the
868269e767SBrooks Davis.Xr execve 2
878269e767SBrooks Davisis attempted, but if some of these descriptors will still
888269e767SBrooks Davisbe needed if the execve fails, it is necessary to arrange for them
898269e767SBrooks Davisto be closed if the execve succeeds.
908269e767SBrooks DavisFor this reason, the call
918269e767SBrooks Davis.Dq Li fcntl(d, F_SETFD, FD_CLOEXEC)
928269e767SBrooks Davisis provided,
938269e767SBrooks Daviswhich arranges that a descriptor will be closed after a successful
948269e767SBrooks Davisexecve; the call
958269e767SBrooks Davis.Dq Li fcntl(d, F_SETFD, 0)
968269e767SBrooks Davisrestores the default,
978269e767SBrooks Daviswhich is to not close the descriptor.
988269e767SBrooks Davis.Sh RETURN VALUES
998269e767SBrooks Davis.Rv -std close
1008269e767SBrooks Davis.Sh ERRORS
1018269e767SBrooks DavisThe
1028269e767SBrooks Davis.Fn close
1038269e767SBrooks Davissystem call will fail if:
1048269e767SBrooks Davis.Bl -tag -width Er
1058269e767SBrooks Davis.It Bq Er EBADF
1068269e767SBrooks DavisThe
1078269e767SBrooks Davis.Fa fd
1088269e767SBrooks Davisargument
1098269e767SBrooks Davisis not an active descriptor.
1108269e767SBrooks Davis.It Bq Er EINTR
1118269e767SBrooks DavisAn interrupt was received.
1128269e767SBrooks Davis.It Bq Er ENOSPC
1138269e767SBrooks DavisThe underlying object did not fit, cached data was lost.
1148269e767SBrooks Davis.El
1158269e767SBrooks Davis.Pp
1168269e767SBrooks DavisIn case of any error except
1178269e767SBrooks Davis.Er EBADF ,
1188269e767SBrooks Davisthe supplied file descriptor is deallocated and therefore is no longer valid.
1198269e767SBrooks Davis.Sh SEE ALSO
1208269e767SBrooks Davis.Xr accept 2 ,
1218269e767SBrooks Davis.Xr closefrom 2 ,
1228269e767SBrooks Davis.Xr execve 2 ,
1238269e767SBrooks Davis.Xr fcntl 2 ,
1248269e767SBrooks Davis.Xr flock 2 ,
1258269e767SBrooks Davis.Xr open 2 ,
1268269e767SBrooks Davis.Xr pipe 2 ,
1278269e767SBrooks Davis.Xr socket 2 ,
1288269e767SBrooks Davis.Xr socketpair 2
1298269e767SBrooks Davis.Sh STANDARDS
1308269e767SBrooks DavisThe
1318269e767SBrooks Davis.Fn close
1328269e767SBrooks Davissystem call is expected to conform to
1338269e767SBrooks Davis.St -p1003.1-90 .
1348269e767SBrooks Davis.Sh HISTORY
1358269e767SBrooks DavisThe
1368269e767SBrooks Davis.Fn close
1378269e767SBrooks Davisfunction appeared in
1388269e767SBrooks Davis.At v1 .
139