bsd/man/man2/close.2

   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 .Fo close
  46 .Fa "int fildes"
  47 .Fc
  48 .Sh DESCRIPTION
  49 The
  50 .Fn close
  51 call deletes a descriptor from the per-process object
  52 reference table.
  53 If this is the last reference to the underlying object, the
  54 object will be deactivated.
  55 For example, on the last close of a file
  56 the current
  57 .Em seek
  58 pointer associated with the file is lost;
  59 on the last close of a
  60 .Xr socket 2
  61 associated naming information and queued data are discarded;
  62 on the last close of a file holding an advisory lock
  63 the lock is released (see further
  64 .Xr flock 2 ) .
  65 .Pp
  66 When a process exits,
  67 all associated file descriptors are freed, but since there is
  68 a limit on active descriptors per processes, the
  69 .Fn close
  70 function call
  71 is useful when a large quantity of file descriptors are being handled.
  72 .Pp
  73 When a process forks (see
  74 .Xr fork 2 ) ,
  75 all descriptors for the new child process reference the same
  76 objects as they did in the parent before the fork.
  77 If a new process is then to be run using
  78 .Xr execve 2 ,
  79 the process would normally inherit these descriptors.  Most
  80 of the descriptors can be rearranged with
  81 .Xr dup2 2
  82 or deleted with
  83 .Fn close
  84 before the
  85 .Xr execve
  86 is attempted, but if some of these descriptors will still
  87 be needed if the execve fails, it is necessary to arrange for them
  88 to be closed if the execve succeeds.
  89 For this reason, the call
  90 .Dq Li fcntl(d, F_SETFD, 1)
  91 is provided,
  92 which arranges that a descriptor will be closed after a successful
  93 execve; the call
  94 .Dq Li fcntl(d, F_SETFD, 0)
  95 restores the default,
  96 which is to not close the descriptor.
  97 .Sh RETURN VALUES
  98 Upon successful completion, a value of 0 is returned.
  99 Otherwise, a value of -1 is returned and the global integer variable
 100 .Va errno
 101 is set to indicate the error.
 102 .Sh ERRORS
 103 The
 104 .Fn close
 105 system call will fail if:
 106 .Bl -tag -width Er
 107 .\" ==========
 108 .It Bq Er EBADF
 109 .Fa fildes
 110 is not a valid, active file descriptor.
 111 .\" ==========
 112 .It Bq Er EINTR
 113 Its execution was interrupted by a signal.
 114 .\" ==========
 115 .It Bq Er EIO
 116 A previously-uncommitted
 117 .Xr write 2
 118 encountered an input/output error.
 119 .El
 120 .Sh SEE ALSO
 121 .Xr accept 2 ,
 122 .Xr execve 2 ,
 123 .Xr fcntl 2 ,
 124 .Xr flock 2 ,
 125 .Xr open 2 ,
 126 .Xr pipe 2 ,
 127 .Xr socket 2 ,
 128 .Xr socketpair 2
 129 .Sh STANDARDS
 130 .Fn close
 131 conforms to
 132 .St -p1003.1-88 .