Module Name: src
Committed By: riastradh
Date: Sat Dec 21 18:56:28 UTC 2024
Modified Files:
src/lib/libc/sys: close.2
Log Message:
close(2): Document the finality of closing.
Even if close(2) returns -1 on error, the descriptor is closed (or
was already closed).
POSIX doesn't specify this, but that's a bug in POSIX (probably to
accommodate some buggy ancient proprietary Unix). Every free
software OS kernel I checked works the same way and it is important
to be able to reliably close descriptors with finality.
To generate a diff of this commit:
cvs rdiff -u -r1.18 -r1.19 src/lib/libc/sys/close.2
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/sys/close.2
diff -u src/lib/libc/sys/close.2:1.18 src/lib/libc/sys/close.2:1.19
--- src/lib/libc/sys/close.2:1.18 Sun Sep 1 19:20:45 2019
+++ src/lib/libc/sys/close.2 Sat Dec 21 18:56:28 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: close.2,v 1.18 2019/09/01 19:20:45 sevan Exp $
+.\" $NetBSD: close.2,v 1.19 2024/12/21 18:56:28 riastradh Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993, 1994
.\" The Regents of the University of California. All rights reserved.
@@ -106,6 +106,24 @@ Upon successful completion, a value of 0
Otherwise, a value of \-1 is returned and
.Va errno
is set to indicate the error.
+.Pp
+In either case, if
+.Fa d
+was an active descriptor, it is no longer active.
+That is,
+.Fn close
+always closes the file descriptor, and, if it was the last reference to
+the underlying object, frees the associated resources \(em even if some
+underlying I/O fails or it is interrupted by a signal.
+.Pp
+Callers must not retry failed
+.Fn close ,
+even on
+.Er EINTR .
+Retrying may inadvertently close a descriptor that was created by
+another thread concurrently after the first call to
+.Fn close
+failed.
.Sh ERRORS
.Fn close
will fail if:
@@ -130,6 +148,14 @@ The
.Fn close
function conforms to
.St -p1003.1-90 .
+.Pp
+The finality of
+.Fn close ,
+even on error, is not specified by POSIX, but most operating systems,
+including
+.Fx ,
+.Ox ,
+Linux, and Solaris, implement the same semantics.
.Sh HISTORY
The
.Fn close
