| 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 | .\" |
| 5 | .\" @(#)close.2 5.1 (Berkeley) %G% |
| 6 | .\" |
| 7 | .TH CLOSE 2 "27 July 1983" |
| 8 | .UC 4 |
| 9 | .SH NAME |
| 10 | close \- delete a descriptor |
| 11 | .SH SYNOPSIS |
| 12 | .B close(d) |
| 13 | .br |
| 14 | .B "int d;" |
| 15 | .SH DESCRIPTION |
| 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 , |
| 32 | but since |
| 33 | there is a limit on the number of active descriptors per process, |
| 34 | .I close |
| 35 | is necessary for programs which deal with many descriptors. |
| 36 | .PP |
| 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. |
| 68 | .SH "SEE ALSO" |
| 69 | accept(2), flock(2), open(2), pipe(2), socket(2), socketpair(2), |
| 70 | execve(2), fcntl(2) |