diff options
Diffstat (limited to 'usr/src/man/man2/close.2')
| -rw-r--r-- | usr/src/man/man2/close.2 | 472 |
1 files changed, 251 insertions, 221 deletions
diff --git a/usr/src/man/man2/close.2 b/usr/src/man/man2/close.2 index 86b3c45a43..1305270f45 100644 --- a/usr/src/man/man2/close.2 +++ b/usr/src/man/man2/close.2 @@ -43,173 +43,193 @@ .\" Copyright 1989 AT&T .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 2022 Oxide Computer Company .\" -.TH CLOSE 2 "Oct 18, 2005" -.SH NAME -close \- close a file descriptor -.SH SYNOPSIS -.LP -.nf -#include <unistd.h> - -\fBint\fR \fBclose\fR(\fBint\fR \fIfildes\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBclose()\fR function deallocates the file descriptor indicated by -\fIfildes\fR. To deallocate means to make the file descriptor available for -return by subsequent calls to \fBopen\fR(2) or other functions that allocate -file descriptors. All outstanding record locks owned by the process on the file -associated with the file descriptor will be removed (that is, unlocked). -.sp -.LP -If \fBclose()\fR is interrupted by a signal that is to be caught, it will -return \fB\(mi1\fR with \fBerrno\fR set to \fBEINTR\fR and the state of -\fIfildes\fR is unspecified. If an I/O error occurred while reading from or -writing to the file system during \fBclose()\fR, it returns -1, sets -\fBerrno\fR to \fBEIO\fR, and the state of \fIfildes\fR is unspecified. -.sp -.LP -When all file descriptors associated with a pipe or \fBFIFO\fR special file are -closed, any data remaining in the pipe or \fBFIFO\fR will be discarded. -.sp -.LP +.Dd February 5, 2022 +.Dt CLOSE 2 +.Os +.Sh NAME +.Nm close +.Nd close a file descriptor +.Sh SYNOPSIS +.In unistd.h +.Ft int +.Fo close +.Fa "int fildes" +.Fc +.Sh DESCRIPTION +The +.Fn close +function deallocates the file descriptor indicated by +.Fa fildes . +To deallocate means to make the file descriptor available for return by +subsequent calls to +.Xr open 2 +or other functions that allocate file descriptors. +All outstanding record locks owned by the process on the file associated with +the file descriptor will be removed +.Pq "that is, unlocked" . +.Pp +If +.Fn close +is interrupted by a signal that is to be caught, it will return +.Sy -1 +with +.Va errno +set to +.Er EINTR +and the state of +.Fa fildes +is unspecified. +If an I/O error occurred while reading from or writing to the file system during +.Fn close , +it returns +.Sy -1 , +sets +.Va errno +to +.Er EIO , +and the state of +.Fa fildes +is unspecified. +.Pp +When all file descriptors associated with a pipe or FIFO special file are +closed, any data remaining in the pipe or FIFO will be discarded. +.Pp When all file descriptors associated with an open file description have been closed the open file description will be freed. -.sp -.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 will be freed and the file -will no longer be accessible. -.sp -.LP -If a streams-based (see \fBIntro\fR(2)) \fIfildes\fR is closed and the calling -process was previously registered to receive a \fBSIGPOLL\fR signal (see -\fBsignal\fR(3C)) for events associated with that stream (see \fBI_SETSIG\fR in -\fBstreamio\fR(4I)), the calling process will be unregistered for events -associated with the stream. The last \fBclose()\fR for a stream causes the -stream associated with \fIfildes\fR to be dismantled. If \fBO_NONBLOCK\fR and -\fBO_NDELAY\fR are not set and there have been no signals posted for the -stream, and if there is data on the module's write queue, \fBclose()\fR waits -up to 15 seconds (for each module and driver) for any output to drain before -dismantling the stream. The time delay can be changed via an \fBI_SETCLTIME\fR -\fBioctl\fR(2) request (see \fBstreamio\fR(4I)). If the \fBO_NONBLOCK\fR or -\fBO_NDELAY\fR flag is set, or if there are any pending signals, \fBclose()\fR +.Pp +If the link count of the file is +.Sy 0 , +when all file descriptors associated with the file are closed, the space +occupied by the file will be freed and the file will no longer be accessible. +.Pp +If a streams-based +.Po +see +.Xr Intro 2 +.Pc +.Fa fildes +is closed and the calling process was previously registered to receive a +.Dv SIGPOLL +signal +.Po +see +.Xr signal 3C +.Pc +for events associated with that stream +.Po +see +.Dv I_SETSIG +in +.Xr streamio 4I +.Pc , +the calling process will be unregistered for events associated with the stream. +The last +.Fn close +for a stream causes the stream associated with +.Fa fildes +to be dismantled. +If +.Dv O_NONBLOCK +and +.Dv O_NDELAY +are not set and there have been no signals posted for the stream, and if there +is data on the module's write queue, +.Fn close +waits up to 15 seconds +.Pq for each module and driver +for any output to drain +before dismantling the stream. +The time delay can be changed via an +.Dv I_SETCLTIME +.Xr ioctl 2 +request +.Po +see +.Xr streamio 4I +.Pc . +If the +.Dv O_NONBLOCK +or +.Dv O_NDELAY +flag is set, or if there are any pending signals, +.Fn close does not wait for output to drain, and dismantles the stream immediately. -.sp -.LP -If \fIfildes\fR is associated with one end of a pipe, the last \fBclose()\fR -causes a hangup to occur on the other end of the pipe. In addition, if the -other end of the pipe has been named by \fBfattach\fR(3C), then the last -\fBclose()\fR forces the named end to be detached by \fBfdetach\fR(3C). If the -named end has no open file descriptors associated with it and gets detached, -the stream associated with that end is also dismantled. -.sp -.LP -If \fIfildes\fR refers to the master side of a pseudo-terminal, a \fBSIGHUP\fR -signal is sent to the session leader, 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. -.sp -.LP -If \fIfildes\fR refers to the slave side of a streams-based pseudo-terminal, a -zero-length message may be sent to the master. -.sp -.LP +.Pp +If +.Fa fildes +is associated with one end of a pipe, the last +.Fn close +causes a hangup to occur on the other end of the pipe. +In addition, if the other end of the pipe has been named by +.Xr fattach 3C , +then the last +.Fn close +forces the named end to be detached by +.Xr fdetach 3C . +If the named end has no open file descriptors associated with it and gets +detached, the stream associated with that end is also dismantled. +.Pp +If +.Fa fildes +refers to the manager side of a pseudo-terminal, a +.Dv SIGHUP +signal is sent to the session leader, if any, for which the subsidiary side of +the pseudo-terminal is the controlling terminal. +It is unspecified whether closing the manager side of the pseudo-terminal +flushes all queued input and output. +.Pp +If +.Fa fildes +refers to the subsidiary side of a streams-based pseudo-terminal, a zero-length +message may be sent to the manager. +.Pp When there is an outstanding cancelable asynchronous I/O operation against -\fIfildes\fR when \fBclose()\fR is called, that I/O operation is canceled. An -I/O operation that is not canceled completes as if the \fBclose()\fR operation -had not yet occurred. All operations that are not canceled will complete as if -the \fBclose()\fR blocked until the operations completed. -.sp -.LP +.Fa fildes +when +.Fn close +is called, that I/O operation is canceled. +An I/O operation that is not canceled completes as if the +.Fn close +operation had not yet occurred. +All operations that are not canceled will complete as if the +.Fn close +blocked until the operations completed. +.Pp 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 will persist until the memory object becomes unreferenced. If -this is the last close of a shared memory object or a memory mapped file and +last close +.Pq "that is, a process has it mapped" , +then the entire contents of the memory object will 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 will be removed. -.sp -.LP -If \fIfildes\fR refers to a socket, \fBclose()\fR causes the socket to be -destroyed. If the socket is connection-mode, and the \fBSO_LINGER\fR option is -set for the socket with non-zero linger time, and the socket has untransmitted -data, then \fBclose()\fR will block for up to the current linger interval until -all data is transmitted. -.SH RETURN VALUES -.sp -.LP -Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is -returned and \fBerrno\fR is set to indicate the error. -.SH ERRORS -.sp -.LP -The \fBclose()\fR function will fail if: -.sp -.ne 2 -.na -\fB\fBEBADF\fR\fR -.ad -.RS 11n -The \fIfildes\fR argument is not a valid file descriptor. -.RE - -.sp -.ne 2 -.na -\fB\fBEINTR\fR\fR -.ad -.RS 11n -The \fBclose()\fR function was interrupted by a signal. -.RE - -.sp -.ne 2 -.na -\fB\fBENOLINK\fR\fR -.ad -.RS 11n -The \fIfildes\fR argument is on a remote machine and the link to that machine -is no longer active. -.RE - -.sp -.ne 2 -.na -\fB\fBENOSPC\fR\fR -.ad -.RS 11n -There was no free space remaining on the device containing the file. -.RE - -.sp -.LP -The \fBclose()\fR function may fail if: -.sp -.ne 2 -.na -\fB\fBEIO\fR\fR -.ad -.RS 7n -An I/O error occurred while reading from or writing to the file system. -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fRReassign a file descriptor. -.sp -.LP +.Pp +If +.Fa fildes +refers to a socket, +.Fn close +causes the socket to be destroyed. +If the socket is connection-mode, and the +.Dv SO_LINGER +option is set for the socket with non-zero linger time, and the socket has +untransmitted data, then +.Fn close +will block for up to the current linger interval until all data is transmitted. +.Sh RETURN VALUES +.Rv -std close +.Sh EXAMPLES +.Sy Example 1 +Reassign a file descriptor. +.Pp 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 -.in +2 -.nf +descriptor, and closes the original file descriptor to clean up. +This example assumes that the file descriptor +.Sy 0 , +which is the descriptor for standard input, is not closed. +.Bd -literal -offset Ds #include <unistd.h> \&... int pfd; @@ -218,32 +238,22 @@ close(1); dup(pfd); close(pfd); \&... -.fi -.in -2 - -.sp -.LP +.Ed +.Pp Incidentally, this is exactly what could be achieved using: - -.sp -.in +2 -.nf +.Bd -literal -offset Ds dup2(pfd, 1); close(pfd); -.fi -.in -2 - -.LP -\fBExample 2 \fRClose a file descriptor. -.sp -.LP -In the following example, \fBclose()\fR is used to close a file descriptor -after an unsuccessful attempt is made to associate that file descriptor with a -stream. - -.sp -.in +2 -.nf +.Ed +.Pp +.Sy Example 2 +Close a file descriptor. +.Pp +In the following example, +.Fn close +is used to close a file descriptor after an unsuccessful attempt is made to +associate that file descriptor with a stream. +.Bd -literal -offset Ds #include <stdio.h> #include <unistd.h> #include <stdlib.h> @@ -259,44 +269,64 @@ if ((fpfd = fdopen (pfd, "w")) == NULL) { exit(1); } \&... -.fi -.in -2 - -.SH USAGE -.sp -.LP -An application that used the \fBstdio\fR function \fBfopen\fR(3C) to open a -file should use the corresponding \fBfclose\fR(3C) function rather than -\fBclose()\fR. -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Interface Stability Standard -_ -MT-Level Async-Signal-Safe -.TE - -.SH SEE ALSO -.sp -.LP -\fBIntro\fR(2), \fBcreat\fR(2), \fBdup\fR(2), \fBexec\fR(2), \fBfcntl\fR(2), -\fBioctl\fR(2), \fBopen\fR(2) \fBpipe\fR(2), -.BR fattach (3C), -.BR fclose (3C), -.BR fdetach (3C), -.BR fopen (3C), -.BR signal (3C), -.BR signal.h (3HEAD), -.BR streamio (4I), -.BR attributes (7), -.BR standards (7) +.Ed +.Sh ERRORS +The +.Fn close +function will fail if: +.Bl -tag -width Er +.It Er EBADF +The +.Fa fildes +argument is not a valid file descriptor. +.It Er EINTR +The +.Fn close +function was interrupted by a signal. +.It Er ENOLINK +The +.Fa fildes +argument is on a remote machine and the link to that machine is no longer +active. +.It Er ENOSPC +There was no free space remaining on the device containing the file. +.El +.Pp +The +.Fn close +function may fail if: +.Bl -tag -width Er +.It Er EIO +An I/O error occurred while reading from or writing to the file system. +.El +.Sh USAGE +An application that used the +.Xr stdio 3C +function +.Xr fopen 3C +to open a file should use the corresponding +.Xr fclose 3C +function rather than +.Fn close . +.Sh INTERFACE STABILITY +.Sy Committed +.Sh MT-LEVEL +.Sy Async-Signal-Safe +.Sh SEE ALSO +.Xr creat 2 , +.Xr dup 2 , +.Xr exec 2 , +.Xr fcntl 2 , +.Xr Intro 2 , +.Xr ioctl 2 , +.Xr open 2 , +.Xr pipe 2 , +.Xr fattach 3C , +.Xr fclose 3C , +.Xr fdetach 3C , +.Xr fopen 3C , +.Xr signal 3C , +.Xr signal.h 3HEAD , +.Xr streamio 4I , +.Xr attributes 7 , +.Xr standards 7 |