Add a flags argument to falloc() that lets it optionally set the

close-on-exec flag on the newly allocated fd.  Make falloc()'s
return arguments non-optional: assert that they're not NULL.

ok mpi@ millert@

1 files changed, 27 insertions, 12 deletions

diff --git a/share/man/man9/file.9 b/share/man/man9/file.9
index ad530bba0c6..b3dfe90ea95 100644
--- a/share/man/man9/file.9
+++ b/share/man/man9/file.9
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: file.9,v 1.16 2015/11/23 17:53:57 jmc Exp $
+.\"     $OpenBSD: file.9,v 1.17 2017/02/11 19:51:06 guenther Exp $
 .\"
 .\" Copyright (c) 2002 Artur Grabowski <art@openbsd.org>
 .\" All rights reserved.
@@ -22,7 +22,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 23 2015 $
+.Dd $Mdocdate: February 11 2017 $
 .Dt FALLOC 9
 .Os
 .Sh NAME
@@ -38,7 +38,7 @@
 .In sys/file.h
 .In sys/filedesc.h
 .Ft int
-.Fn falloc "struct proc *p" "struct file **resultfp" "int *resultfd"
+.Fn falloc "struct proc *p" "int flags" "struct file **resultfp" "int *resultfd"
 .Ft int
 .Fn fdrelease "struct proc *p" "int fd"
 .Ft void
@@ -66,17 +66,32 @@ kqueues (see
 .Xr kqueue 2 ) ,
 and various special purpose communication endpoints.
 .Pp
-A new file descriptor is allocated with the function
+A new file and a file descriptor for it are allocated with the function
+.Fn falloc .
+The
+.Fa flags
+argument can be used to set the
+.Dv UF_EXCLOSE
+flag on the new descriptor.
+The larval file and fd are returned via
+.Fa resultfp
+and
+.Fa resultfd ,
+which must not be
+.Dv NULL .
 .Fn falloc
-and freed with
+initializes the new file to have a reference count of two:
+one for the reference from the file descriptor table and one
+for the caller to release with
+.Fn FRELE
+when it done initializing it.
+.Pp
+A file descriptor is freed with
 .Fn fdrelease .
-.Fn falloc
-and
-.Fn fdrelease
-deal with allocating and freeing slots in the file descriptor table,
-expanding the table when necessary and initializing the descriptor.
-It's possible to do those things in smaller steps, but it's not
-recommended to make complicated kernel APIs that require it.
+This releases the reference that it holds to the underlying file;
+if that's the last reference then the file will be freed.
+.\" with
+.\" .Xr closef 9 .
 .Pp
 The files are extracted from the file descriptor table using the
 functions