[src/trunk]: src Document opendisk1() - it has been around long enough.

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

details:   https://anonhg.NetBSD.org/src/rev/051f3df037c0
branches:  trunk
changeset: 321755:051f3df037c0
user:      kre <kre%NetBSD.org@localhost>
date:      Wed Apr 04 04:43:46 2018 +0000

description:
Document opendisk1() - it has been around long enough.
(pity about the name...)

XXX pullup-8

diffstat:

 distrib/sets/lists/comp/mi |   5 +++-
 lib/libutil/Makefile       |   3 +-
 lib/libutil/opendisk.3     |  51 ++++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 53 insertions(+), 6 deletions(-)

diffs (154 lines):

diff -r acbf828f701f -r 051f3df037c0 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Tue Apr 03 21:57:14 2018 +0000
+++ b/distrib/sets/lists/comp/mi        Wed Apr 04 04:43:46 2018 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.2185 2018/02/25 12:28:18 kamil Exp $
+#      $NetBSD: mi,v 1.2186 2018/04/04 04:43:46 kre Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 ./etc/mtree/set.comp                           comp-sys-root
@@ -8387,6 +8387,7 @@
 ./usr/share/man/cat3/open_wmemstream.0         comp-c-catman           .cat
 ./usr/share/man/cat3/opendir.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/opendisk.0                        comp-c-catman           .cat
+./usr/share/man/cat3/opendisk1.0               comp-c-catman           .cat
 ./usr/share/man/cat3/openlog.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/openlog_r.0               comp-c-catman           .cat
 ./usr/share/man/cat3/openpam.0                 comp-c-catman           .cat,pam
@@ -16127,6 +16128,7 @@
 ./usr/share/man/html3/open_wmemstream.html     comp-c-htmlman          html
 ./usr/share/man/html3/opendir.html             comp-c-htmlman          html
 ./usr/share/man/html3/opendisk.html            comp-c-htmlman          html
+./usr/share/man/html3/opendisk1.html           comp-c-htmlman          html
 ./usr/share/man/html3/openlog.html             comp-c-htmlman          html
 ./usr/share/man/html3/openlog_r.html           comp-c-htmlman          html
 ./usr/share/man/html3/openpam.html             comp-c-htmlman          html,pam
@@ -23879,6 +23881,7 @@
 ./usr/share/man/man3/open_wmemstream.3         comp-c-man              .man
 ./usr/share/man/man3/opendir.3                 comp-c-man              .man
 ./usr/share/man/man3/opendisk.3                        comp-c-man              .man
+./usr/share/man/man3/opendisk1.3               comp-c-man              .man
 ./usr/share/man/man3/openlog.3                 comp-c-man              .man
 ./usr/share/man/man3/openlog_r.3               comp-c-man              .man
 ./usr/share/man/man3/openpam.3                 comp-c-man              .man,pam
diff -r acbf828f701f -r 051f3df037c0 lib/libutil/Makefile
--- a/lib/libutil/Makefile      Tue Apr 03 21:57:14 2018 +0000
+++ b/lib/libutil/Makefile      Wed Apr 04 04:43:46 2018 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.81 2017/04/01 14:31:05 abhinav Exp $
+#      $NetBSD: Makefile,v 1.82 2018/04/04 04:43:46 kre Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/4/93
 
 USE_SHLIBDIR=  yes
@@ -60,6 +60,7 @@
 MLINKS+=login_cap.3 setclasscontext.3
 MLINKS+=login_cap.3 setusercontext.3
 MLINKS+=loginx.3 logoutx.3 loginx.3 logwtmpx.3
+MLINKS+=opendisk.3 opendisk1.3
 MLINKS+=openpty.3 login_tty.3
 MLINKS+=openpty.3 forkpty.3
 MLINKS+=pidfile.3 pidfile_clean.3
diff -r acbf828f701f -r 051f3df037c0 lib/libutil/opendisk.3
--- a/lib/libutil/opendisk.3    Tue Apr 03 21:57:14 2018 +0000
+++ b/lib/libutil/opendisk.3    Wed Apr 04 04:43:46 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: opendisk.3,v 1.14 2017/01/29 05:13:55 snj Exp $
+.\"    $NetBSD: opendisk.3,v 1.15 2018/04/04 04:43:46 kre Exp $
 .\"
 .\" Copyright (c) 1997, 2001 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,11 +27,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd June 6, 2016
+.Dd April 4, 2018
 .Dt OPENDISK 3
 .Os
 .Sh NAME
-.Nm opendisk
+.Nm opendisk ,
+.Nm opendisk1
 .Nd open a disk partition
 .Sh LIBRARY
 .Lb libutil
@@ -45,6 +46,15 @@
 .Fa "size_t buflen"
 .Fa "int iscooked"
 .Fc
+.Ft int
+.Fo opendisk1
+.Fa "const char *path"
+.Fa "int flags"
+.Fa "char *buf"
+.Fa "size_t buflen"
+.Fa "int iscooked"
+.Fa "int (*ofn)(const char *, int, ...))"
+.Fc
 .Sh DESCRIPTION
 .Fn opendisk
 opens
@@ -137,15 +147,33 @@
 represents the raw partition of the device, as determined by
 .Xr getrawpartition 3 ,
 usually
-.Dq c .
+.Dq c
+or
+.Dq d .
 .El
 .El
+.Pp
+.Fn opendisk1
+is identical to
+.Fn opendisk
+except uses the supplied
+.Fa ofn
+function instead of
+.Xr open 2 .
+This function must be compatible
+with
+.Xr open 2
+in the parameters it takes,
+the value it returns,
+and way that errors are indicated.
 .Sh RETURN VALUES
 An open file descriptor, or -1 if the
 .Xr open 2
 failed.
 .Sh ERRORS
 .Fn opendisk
+and
+.Fn opendisk1
 may set
 .Va errno
 to one of the following values:
@@ -172,6 +200,14 @@
 to any value specified by the
 .Xr open 2
 function.
+.PP
+The
+.Fn opendisk1
+function may also set
+.Va errno
+to any value set by the
+.Fa ofn
+function.
 .Sh SEE ALSO
 .Xr open 2 ,
 .Xr getrawpartition 3
@@ -180,6 +216,13 @@
 .Fn opendisk
 function first appeared in
 .Nx 1.3 .
+.br
+The
+.Fn opendisk1
+function first appeared in
+.Nx 6.0 ,
+and was documented in
+.Nx 8.0 .
 .Pp
 The lookup order of
 .Fn opendisk