[unix-history] / usr / src / lib / libc / sys / close.2

.\" Copyright (c) 1980, 1991 Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)close.2	6.4 (Berkeley) %G%
.\"
.Dd 
.Dt CLOSE 2
.Os BSD 4
.Sh NAME
.Nm close
.Nd delete a descriptor
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Ft int
.Fn close "int d"
.Sh DESCRIPTION
The
.Fn close
call deletes a descriptor from the per-process object
reference table.
If this is the last reference to the underlying object, the
object will be deactivated.
For example, on the last close of a file
the current
.Em seek
pointer associated with the file is lost;
on the last close of a
.Xr socket 2
associated naming information and queued data are discarded;
on the last close of a file holding an advisory lock
the lock is released (see further
.Xr flock 2 ) .
.Pp
When a process exits,
all associated file descriptors are freed, but since there is
a limit on active descriptors per processes, the
.Fn close
function call
is useful when a large quanitity of file descriptors are being handled.
.Pp
When a process forks (see
.Xr fork 2 ) ,
all descriptors for the new child process reference the same
objects as they did in the parent before the fork.
If a new process is then to be run using
.Xr execve 2 ,
the process would normally inherit these descriptors.  Most
of the descriptors can be rearranged with
.Xr dup2 2
or deleted with
.Fn close
before the
.Xr execve
is attempted, but if some of these descriptors will still
be needed if the execve fails, it is necessary to arrange for them
to be closed if the execve succeeds.
For this reason, the call
.Dq Li fcntl(d, F_SETFD, 1)
is provided,
which arranges that a descriptor will be closed after a successful
execve; the call
.Dq Li fcntl(d, F_SETFD, 0)
restores the default,
which is to not close the descriptor.
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and the global integer variable
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn Close
will fail if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa D
is not an active descriptor.
.It Bq Er EINTR
An interupt was received.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr flock 2 ,
.Xr open 2 ,
.Xr pipe 2 ,
.Xr socket 2 ,
.Xr socketpair 2 ,
.Xr execve 2 ,
.Xr fcntl 2
.Sh STANDARDS
.Fn Close
conforms to IEEE Std 1003.1-1988
.Pq Dq Tn POSIX .
Commit	Line	Data
931b8415 CL	1	.\" Copyright (c) 1980, 1991 Regents of the University of California.
931b8415 CL	2	.\" All rights reserved.
6fd5737e	3	.\"
931b8415	4	.\" %sccs.include.redist.man%
6fd5737e	5	.\"
931b8415 CL	6	.\" @(#)close.2 6.4 (Berkeley) %G%
	7	.\"
	8	.Dd
	9	.Dt CLOSE 2
	10	.Os BSD 4
	11	.Sh NAME
	12	.Nm close
	13	.Nd delete a descriptor
	14	.Sh SYNOPSIS
	15	.Fd #include <unistd.h>
	16	.Ft int
	17	.Fn close "int d"
	18	.Sh DESCRIPTION
447c53e0	19	The
931b8415 CL	20	.Fn close
931b8415 CL	21	call deletes a descriptor from the per-process object
447c53e0	22	reference table.
931b8415 CL	23	If this is the last reference to the underlying object, the
931b8415 CL	24	object will be deactivated.
447c53e0	25	For example, on the last close of a file
931b8415 CL	26	the current
	27	.Em seek
	28	pointer associated with the file is lost;
447c53e0	29	on the last close of a
931b8415	30	.Xr socket 2
447c53e0 KM	31	associated naming information and queued data are discarded;
447c53e0 KM	32	on the last close of a file holding an advisory lock
d4bad45b	33	the lock is released (see further
931b8415 CL	34	.Xr flock 2 ) .
	35	.Pp
	36	When a process exits,
	37	all associated file descriptors are freed, but since there is
	38	a limit on active descriptors per processes, the
	39	.Fn close
	40	function call
	41	is useful when a large quanitity of file descriptors are being handled.
	42	.Pp
447c53e0	43	When a process forks (see
931b8415	44	.Xr fork 2 ) ,
447c53e0 KM	45	all descriptors for the new child process reference the same
	46	objects as they did in the parent before the fork.
	47	If a new process is then to be run using
931b8415	48	.Xr execve 2 ,
447c53e0 KM	49	the process would normally inherit these descriptors. Most
447c53e0 KM	50	of the descriptors can be rearranged with
931b8415	51	.Xr dup2 2
447c53e0	52	or deleted with
931b8415	53	.Fn close
447c53e0	54	before the
931b8415	55	.Xr execve
447c53e0 KM	56	is attempted, but if some of these descriptors will still
	57	be needed if the execve fails, it is necessary to arrange for them
	58	to be closed if the execve succeeds.
931b8415 CL	59	For this reason, the call
	60	.Dq Li fcntl(d, F_SETFD, 1)
	61	is provided,
447c53e0	62	which arranges that a descriptor will be closed after a successful
931b8415 CL	63	execve; the call
	64	.Dq Li fcntl(d, F_SETFD, 0)
	65	restores the default,
447c53e0	66	which is to not close the descriptor.
931b8415	67	.Sh RETURN VALUES
447c53e0	68	Upon successful completion, a value of 0 is returned.
931b8415 CL	69	Otherwise, a value of -1 is returned and the global integer variable
931b8415 CL	70	.Va errno
447c53e0	71	is set to indicate the error.
931b8415 CL	72	.Sh ERRORS
931b8415 CL	73	.Fn Close
447c53e0	74	will fail if:
931b8415 CL	75	.Bl -tag -width Er
	76	.It Bq Er EBADF
	77	.Fa D
	78	is not an active descriptor.
	79	.It Bq Er EINTR
	80	An interupt was received.
	81	.El
	82	.Sh SEE ALSO
	83	.Xr accept 2 ,
	84	.Xr flock 2 ,
	85	.Xr open 2 ,
	86	.Xr pipe 2 ,
	87	.Xr socket 2 ,
	88	.Xr socketpair 2 ,
	89	.Xr execve 2 ,
	90	.Xr fcntl 2
	91	.Sh STANDARDS
	92	.Fn Close
	93	conforms to IEEE Std 1003.1-1988
	94	.Pq Dq Tn POSIX .