manual page distributed with 4.2BSD

SCCS-vsn: lib/libc/sys/close.2 5.1

diff --git a/usr/src/lib/libc/sys/close.2 b/usr/src/lib/libc/sys/close.2
index 7263d88..d9e7f15 100644 (file)
--- a/usr/src/lib/libc/sys/close.2
+++ b/usr/src/lib/libc/sys/close.2
@@ -2,51 +2,69 @@
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"

-.\"    @(#)close.2     4.1 (Berkeley) %G%
+.\"    @(#)close.2     5.1 (Berkeley) %G%

 .\"
 .\"

-.TH CLOSE 2 
+.TH CLOSE 2 "27 July 1983"

 .UC 4
 .SH NAME
 .UC 4
 .SH NAME

-close \- close a file
+close \- delete a descriptor

 .SH SYNOPSIS
 .SH SYNOPSIS

-.B close(fildes)
+.B close(d)
+.br
+.B "int d;"

 .SH DESCRIPTION
 .SH DESCRIPTION

-Given
-a file descriptor such as returned from an
-.I open,
-.I creat,
-.I dup
-or
-.IR pipe (2)
-call,
-.I close
-closes the associated file.
-A close of all files is automatic on
-.I exit,
+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
 but since

-there is a limit on the number of open files per process,
+there is a limit on the number of active descriptors per process,

 .I close
 .I close

-is necessary for programs which deal with many files.
+is necessary for programs which deal with many descriptors.

 .PP
 .PP

-Files are closed upon termination of a process, and
-certain high-numbered file descriptors are closed by
-.IR exec (2),
-and it is possible to arrange for others to be closed
-(see FIOCLEX in
-.IR ioctl (2)).
+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"
 .SH "SEE ALSO"

-creat(2), open(2), pipe(2), exec(2), ioctl(2)
-.SH DIAGNOSTICS
-Zero is returned if a file is closed;
-\-1 is returned for an unknown file descriptor.
-.SH "ASSEMBLER (PDP-11)"
-(close = 6.)
-.br
-(file descriptor in r0)
-.br
-.B sys close
-.PP
-.SH BUGS
-A file cannot be closed while there are pages which have been
-.I vread
-but not referenced.
+accept(2), flock(2), open(2), pipe(2), socket(2), socketpair(2),
+execve(2), fcntl(2)