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

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)close.2	5.1 (Berkeley) %G%
.\"
.TH CLOSE 2 "27 July 1983"
.UC 4
.SH NAME
close \- delete a descriptor
.SH SYNOPSIS
.B close(d)
.br
.B "int d;"
.SH DESCRIPTION
The
\fIclose\fP call deletes a descriptor from the per-process object
reference table.
If this is the last reference to the underlying object, then
it will be deactivated.
For example, on the last close of a file
the current \fIseek\fP pointer associated with the file is lost;
on the last close of a
.IR 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
.IR flock (2).
.PP
A close of all of a process's descriptors is automatic on
.IR exit ,
but since
there is a limit on the number of active descriptors per process,
.I close
is necessary for programs which deal with many descriptors.
.PP
When a process forks (see
.IR 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
.IR execve (2),
the process would normally inherit these descriptors.  Most
of the descriptors can be rearranged with
.IR dup2 (2)
or deleted with
.I close
before the
.I 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 ``fcntl(d, F_SETFD, 1)'' is provided
which arranges that a descriptor will be closed after a successful
execve; the call ``fcntl(d, F_SETFD, 0)'' restores the default,
which is to not close the descriptor.
.SH "RETURN VALUE
Upon successful completion, a value of 0 is returned.
Otherwise, a value of \-1 is returned and the global integer variable
.I errno
is set to indicate the error.
.SH ERRORS
.I Close
will fail if:
.TP 15
[EBADF]
\fID\fP is not an active descriptor.
.SH "SEE ALSO"
accept(2), flock(2), open(2), pipe(2), socket(2), socketpair(2),
execve(2), fcntl(2)
Commit	Line	Data
6fd5737e KM	1	.\" Copyright (c) 1980 Regents of the University of California.
	2	.\" All rights reserved. The Berkeley software License Agreement
	3	.\" specifies the terms and conditions for redistribution.
	4	.\"
447c53e0	5	.\" @(#)close.2 5.1 (Berkeley) %G%
6fd5737e	6	.\"
447c53e0	7	.TH CLOSE 2 "27 July 1983"
6fd5737e KM	8	.UC 4
6fd5737e KM	9	.SH NAME
447c53e0	10	close \- delete a descriptor
6fd5737e	11	.SH SYNOPSIS
447c53e0 KM	12	.B close(d)
	13	.br
	14	.B "int d;"
6fd5737e	15	.SH DESCRIPTION
447c53e0 KM	16	The
	17	\fIclose\fP call deletes a descriptor from the per-process object
	18	reference table.
	19	If this is the last reference to the underlying object, then
	20	it will be deactivated.
	21	For example, on the last close of a file
	22	the current \fIseek\fP pointer associated with the file is lost;
	23	on the last close of a
	24	.IR socket (2)
	25	associated naming information and queued data are discarded;
	26	on the last close of a file holding an advisory lock
	27	the lock is released; see further
	28	.IR flock (2).
	29	.PP
	30	A close of all of a process's descriptors is automatic on
	31	.IR exit ,
6fd5737e	32	but since
447c53e0	33	there is a limit on the number of active descriptors per process,
6fd5737e	34	.I close
447c53e0	35	is necessary for programs which deal with many descriptors.
6fd5737e	36	.PP
447c53e0 KM	37	When a process forks (see
	38	.IR fork (2)),
	39	all descriptors for the new child process reference the same
	40	objects as they did in the parent before the fork.
	41	If a new process is then to be run using
	42	.IR execve (2),
	43	the process would normally inherit these descriptors. Most
	44	of the descriptors can be rearranged with
	45	.IR dup2 (2)
	46	or deleted with
	47	.I close
	48	before the
	49	.I execve
	50	is attempted, but if some of these descriptors will still
	51	be needed if the execve fails, it is necessary to arrange for them
	52	to be closed if the execve succeeds.
	53	For this reason, the call ``fcntl(d, F_SETFD, 1)'' is provided
	54	which arranges that a descriptor will be closed after a successful
	55	execve; the call ``fcntl(d, F_SETFD, 0)'' restores the default,
	56	which is to not close the descriptor.
	57	.SH "RETURN VALUE
	58	Upon successful completion, a value of 0 is returned.
	59	Otherwise, a value of \-1 is returned and the global integer variable
	60	.I errno
	61	is set to indicate the error.
	62	.SH ERRORS
	63	.I Close
	64	will fail if:
	65	.TP 15
	66	[EBADF]
	67	\fID\fP is not an active descriptor.
6fd5737e	68	.SH "SEE ALSO"
447c53e0 KM	69	accept(2), flock(2), open(2), pipe(2), socket(2), socketpair(2),
447c53e0 KM	70	execve(2), fcntl(2)