diff options
Diffstat (limited to 'man3p/close.3p')
| -rw-r--r-- | man3p/close.3p | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/man3p/close.3p b/man3p/close.3p new file mode 100644 index 000000000..3f06fee6f --- /dev/null +++ b/man3p/close.3p @@ -0,0 +1,220 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CLOSE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" close +.SH NAME +close \- close a file descriptor +.SH SYNOPSIS +.LP +\fB#include <unistd.h> +.br +.sp +int close(int\fP \fIfildes\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIclose\fP() function shall deallocate the file descriptor indicated +by \fIfildes\fP. To deallocate means to make the +file descriptor available for return by subsequent calls to \fIopen\fP() +or other functions +that allocate file descriptors. All outstanding record locks owned +by the process on the file associated with the file descriptor +shall be removed (that is, unlocked). +.LP +If \fIclose\fP() is interrupted by a signal that is to be caught, +it shall return -1 with \fIerrno\fP set to [EINTR] and the +state of \fIfildes\fP is unspecified. If an I/O error occurred while +reading from or writing to the file system during +\fIclose\fP(), it may return -1 with \fIerrno\fP set to [EIO]; if +this error is returned, the state of \fIfildes\fP is +unspecified. +.LP +When all file descriptors associated with a pipe or FIFO special file +are closed, any data remaining in the pipe or FIFO shall +be discarded. +.LP +When all file descriptors associated with an open file description +have been closed, the open file description shall be +freed. +.LP +If the link count of the file is 0, when all file descriptors associated +with the file are closed, the space occupied by the +file shall be freed and the file shall no longer be accessible. +.LP +If a STREAMS-based \fIfildes\fP is closed and the calling process +was previously registered to receive a SIGPOLL signal for events +associated with that STREAM, the calling process shall be unregistered +for events associated with the STREAM. The last +\fIclose\fP() for a STREAM shall cause the STREAM associated with +\fIfildes\fP to be dismantled. If O_NONBLOCK is not set and +there have been no signals posted for the STREAM, and if there is +data on the module's write queue, \fIclose\fP() shall wait for +an unspecified time (for each module and driver) for any output to +drain before dismantling the STREAM. The time delay can be +changed via an I_SETCLTIME \fIioctl\fP() request. If the O_NONBLOCK +flag is set, or if there +are any pending signals, \fIclose\fP() shall not wait for output to +drain, and shall dismantle the STREAM immediately. +.LP +If the implementation supports STREAMS-based pipes, and \fIfildes\fP +is associated with one end of a pipe, the last +\fIclose\fP() shall cause a hangup to occur on the other end of the +pipe. In addition, if the other end of the pipe has been named +by \fIfattach\fP(), then the last \fIclose\fP() shall force the named +end to be detached +by \fIfdetach\fP(). If the named end has no open file descriptors +associated with it and +gets detached, the STREAM associated with that end shall also be dismantled. +.LP +If \fIfildes\fP refers to the master side of a pseudo-terminal, and +this is the last close, a SIGHUP signal shall be sent to the +controlling process, if any, for which the slave side of the pseudo-terminal +is the controlling terminal. It is unspecified whether +closing the master side of the pseudo-terminal flushes all queued +input and output. +.LP +If \fIfildes\fP refers to the slave side of a STREAMS-based pseudo-terminal, +a zero-length message may be sent to the master. +.LP +When there is an outstanding cancelable asynchronous I/O operation +against \fIfildes\fP when \fIclose\fP() is called, that I/O +operation may be canceled. An I/O operation that is not canceled completes +as if the \fIclose\fP() operation had not yet occurred. +All operations that are not canceled shall complete as if the \fIclose\fP() +blocked until the operations completed. The +\fIclose\fP() operation itself need not block awaiting such I/O completion. +Whether any I/O operation is canceled, and which I/O +operation may be canceled upon \fIclose\fP(), is implementation-defined. +.LP +If a shared memory object or a memory mapped file remains referenced +at the last close (that is, a process has it mapped), then the +entire contents of the memory object shall persist until the memory +object becomes unreferenced. If this is the last close of a +shared memory object or a memory mapped file and the close results +in the memory object becoming unreferenced, and the memory +object has been unlinked, then the memory object shall be removed. +.LP +If \fIfildes\fP refers to a socket, \fIclose\fP() shall cause the +socket to be destroyed. If the socket is in connection-mode, +and the SO_LINGER option is set for the socket with non-zero linger +time, and the socket has untransmitted data, then +\fIclose\fP() shall block for up to the current linger interval until +all data is transmitted. +.SH RETURN VALUE +.LP +Upon successful completion, 0 shall be returned; otherwise, -1 shall +be returned and \fIerrno\fP set to indicate the error. +.SH ERRORS +.LP +The \fIclose\fP() function shall fail if: +.TP 7 +.B EBADF +The \fIfildes\fP argument is not a valid file descriptor. +.TP 7 +.B EINTR +The \fIclose\fP() function was interrupted by a signal. +.sp +.LP +The \fIclose\fP() function may fail if: +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to the file system. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Reassigning a File Descriptor +.LP +The following example closes the file descriptor associated with standard +output for the current process, re-assigns standard +output to a new file descriptor, and closes the original file descriptor +to clean up. This example assumes that the file descriptor +0 (which is the descriptor for standard input) is not closed. +.sp +.RS +.nf + +\fB#include <unistd.h> +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +\fP +.fi +.RE +.LP +Incidentally, this is exactly what could be achieved using: +.sp +.RS +.nf + +\fBdup2(pfd, 1); +close(pfd); +\fP +.fi +.RE +.SS Closing a File Descriptor +.LP +In the following example, \fIclose\fP() is used to close a file descriptor +after an unsuccessful attempt is made to associate +that file descriptor with a stream. +.sp +.RS +.nf + +\fB#include <stdio.h> +#include <unistd.h> +#include <stdlib.h> +.sp + +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; +FILE *fpfd; +\&... +if ((fpfd = fdopen (pfd, "w")) == NULL) { + close(pfd); + unlink(LOCKFILE); + exit(1); +} +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +An application that had used the \fIstdio\fP routine \fIfopen\fP() +to open a file should +use the corresponding \fIfclose\fP() routine rather than \fIclose\fP(). +Once a file is +closed, the file descriptor no longer exists, since the integer corresponding +to it no longer refers to a file. +.SH RATIONALE +.LP +The use of interruptible device close routines should be discouraged +to avoid problems with the implicit closes of file +descriptors by \fIexec\fP and \fIexit\fP(). This volume +of IEEE\ Std\ 1003.1-2001 only intends to permit such behavior by +specifying the [EINTR] error condition. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fISTREAMS\fP , \fIfattach\fP() , \fIfclose\fP() , \fIfdetach\fP() +, \fIfopen\fP() , \fIioctl\fP() , \fIopen\fP() , the Base Definitions +volume of +IEEE\ Std\ 1003.1-2001, \fI<unistd.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |