[src/trunk]: src/lib/libc/sys Document O_EXEC, and add some extra explanation...

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/51edc2ef882f
branches:  trunk
changeset: 965420:51edc2ef882f
user:      christos <christos%NetBSD.org@localhost>
date:      Sun Sep 15 20:53:24 2019 +0000

description:
Document O_EXEC, and add some extra explanation for O_CREAT from FreeBSD.

diffstat:

 lib/libc/sys/open.2 |  43 ++++++++++++++++++++++++++++++++++++-------
 1 files changed, 36 insertions(+), 7 deletions(-)

diffs (88 lines):

diff -r 57849e06780b -r 51edc2ef882f lib/libc/sys/open.2
--- a/lib/libc/sys/open.2       Sun Sep 15 20:51:52 2019 +0000
+++ b/lib/libc/sys/open.2       Sun Sep 15 20:53:24 2019 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: open.2,v 1.60 2019/09/01 23:57:14 sevan Exp $
+.\"    $NetBSD: open.2,v 1.61 2019/09/15 20:53:24 christos Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,13 +29,13 @@
 .\"
 .\"     @(#)open.2     8.2 (Berkeley) 11/16/93
 .\"
-.Dd September 2, 2019
+.Dd September 16, 2019
 .Dt OPEN 2
 .Os
 .Sh NAME
 .Nm open ,
 .Nm openat
-.Nd open or create a file for reading or writing
+.Nd open or create a file for reading, writing or executing
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -48,15 +48,34 @@
 The file name specified by
 .Fa path
 is opened
-for reading and/or writing as specified by the
+for either execution or reading and/or writing as specified by the
 argument
 .Fa flags
 and the file descriptor returned to the calling process.
-.Pp
+The
+.Fa flags
+argument may indicate the file is to be
+created if it does not exist (by specifying the
+.Dv O_CREAT
+flag).
+In this case
+.Fn open
+and
 .Fn openat
-works the same way as
+require an additional argument
+.Fa "mode_t mode" ,
+and the file is created with mode
+.Fa mode
+as described in
+.Xr chmod 2
+and modified by the process' umask value (see
+.Xr umask 2 ) .
+.Pp
+The
+.Fn openat
+function is equivalent to the
 .Fn open
-except if
+function except in the case where the
 .Fa path
 is relative.
 In that case, it is looked up from a directory whose file
@@ -91,6 +110,8 @@
 Open for reading only.
 .It Dv O_WRONLY
 Open for writing only.
+.It Dv O_EXEC
+Open for execute only.
 .It Dv O_RDWR
 Open for reading and writing.
 .El
@@ -412,6 +433,14 @@
 .Fn openat
 will fail if:
 .Bl -tag -width Er
+.It Bq Er EINVAL
+An attempt was made to open a descriptor with an illegal combination
+of
+.Dv O_RDONLY ,
+.Dv O_WRONLY ,
+.Dv O_RDWR
+and
+.Dv O_EXEC .
 .It Bq Er EBADF
 .Fa path
 does not specify an absolute path and