1.\" $NetBSD: close.2,v 1.5 1995/02/27 12:32:14 cgd Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993, 1994 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)close.2 8.2 (Berkeley) 4/19/94 35.\" 36.Dd April 19, 1994 37.Dt CLOSE 2 38.Os BSD 4 39.Sh NAME 40.Nm close 41.Nd delete a descriptor 42.Sh SYNOPSIS 43.Fd #include <unistd.h> 44.Ft int 45.Fn close "int d" 46.Sh DESCRIPTION 47The 48.Fn close 49call deletes a descriptor from the per-process object 50reference table. 51If this is the last reference to the underlying object, the 52object will be deactivated. 53For example, on the last close of a file 54the current 55.Em seek 56pointer associated with the file is lost; 57on the last close of a 58.Xr socket 2 59associated naming information and queued data are discarded; 60on the last close of a file holding an advisory lock 61the lock is released (see further 62.Xr flock 2 ) . 63.Pp 64When a process exits, 65all associated file descriptors are freed, but since there is 66a limit on active descriptors per processes, the 67.Fn close 68function call 69is useful when a large quantity of file descriptors are being handled. 70.Pp 71When a process forks (see 72.Xr fork 2 ) , 73all descriptors for the new child process reference the same 74objects as they did in the parent before the fork. 75If a new process is then to be run using 76.Xr execve 2 , 77the process would normally inherit these descriptors. Most 78of the descriptors can be rearranged with 79.Xr dup2 2 80or deleted with 81.Fn close 82before the 83.Xr execve 84is attempted, but if some of these descriptors will still 85be needed if the execve fails, it is necessary to arrange for them 86to be closed if the execve succeeds. 87For this reason, the call 88.Dq Li fcntl(d, F_SETFD, 1) 89is provided, 90which arranges that a descriptor will be closed after a successful 91execve; the call 92.Dq Li fcntl(d, F_SETFD, 0) 93restores the default, 94which is to not close the descriptor. 95.Sh RETURN VALUES 96Upon successful completion, a value of 0 is returned. 97Otherwise, a value of -1 is returned and the global integer variable 98.Va errno 99is set to indicate the error. 100.Sh ERRORS 101.Fn Close 102will fail if: 103.Bl -tag -width Er 104.It Bq Er EBADF 105.Fa D 106is not an active descriptor. 107.It Bq Er EINTR 108An interrupt was received. 109.El 110.Sh SEE ALSO 111.Xr accept 2 , 112.Xr flock 2 , 113.Xr open 2 , 114.Xr pipe 2 , 115.Xr socket 2 , 116.Xr socketpair 2 , 117.Xr execve 2 , 118.Xr fcntl 2 119.Sh STANDARDS 120.Fn Close 121conforms to 122.St -p1003.1-88 . 123