Thu Apr 20 10:43:17 2023 UTC ()
optstr(9): markup fixes

While here, wrap long .Fn lines for readability and make the
optstr_get_item list compact.


(uwe)
diff -r1.5 -r1.6 src/share/man/man9/optstr.9
cvs diff -r1.5 -r1.6 src/share/man/man9/optstr.9 (expand / switch to unified diff)

--- src/share/man/man9/optstr.9 2023/04/20 09:06:02 1.5
+++ src/share/man/man9/optstr.9 2023/04/20 10:43:17 1.6
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: optstr.9,v 1.5 2023/04/20 09:06:02 skrll Exp $ 1.\" $NetBSD: optstr.9,v 1.6 2023/04/20 10:43:17 uwe Exp $
2.\" 2.\"
3.\" Copyright (c) 2006 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2006 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Julio M. Merino Vidal. 7.\" by Julio M. Merino Vidal.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -20,104 +20,136 @@ @@ -20,104 +20,136 @@
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd May 20, 2023 30.Dd May 20, 2023
31.Dt OPTSTR 9 31.Dt OPTSTR 9
32.Os 32.Os
 33.
33.Sh NAME 34.Sh NAME
34.Nm optstr_get , 35.Nm optstr_get ,
35.Nm optstr_get_string , 36.Nm optstr_get_string ,
36.Nm optstr_get_number , 37.Nm optstr_get_number ,
37.Nm optstr_get_number_binary , 38.Nm optstr_get_number_binary ,
38.Nm optstr_get_number_hex , 39.Nm optstr_get_number_hex ,
39.Nm optstr_get_macaddr 40.Nm optstr_get_macaddr
40.Nd Options string management 41.Nd Options string management
 42.
41.Sh SYNOPSIS 43.Sh SYNOPSIS
42.In sys/optstr.h 44.In sys/optstr.h
 45.
43.Ft bool 46.Ft bool
44.Fn optstr_get "const char *optstr" "const char *key" "char *buf" "size_t bufsize" 47.Fo optstr_get
45.Ft bool 48.Fa "const char *optstr"
46.Fn optstr_get_string "const char *optstr" "const char *key" "char **result" 49.Fa "const char *key"
47.Ft bool 50.Fa "char *buf"
48.Fn optstr_get_number "const char *optstr" "const char *key" "unsigned long *result" 51.Fa "size_t bufsize"
49.Ft bool 52.Fc
50.Fn optstr_get_number_binary "const char *optstr" "const char *key" "unsigned long *result" 53.
51.Ft bool 54.Ft bool
52.Fn optstr_get_number_hex "const char *optstr" "const char *key" "unsigned long *result" 55.Fo optstr_get_string
53.Ft bool 56.Fa "const char *optstr"
54.Fn optstr_get_macaddr "const char *optstr" "const char *key" "uint8_t result[ETHER_ADDR_LEN]" 57.Fa "const char *key"
 58.Fa "char **result"
 59.Fc
 60.
 61.Ft bool
 62.Fo optstr_get_number
 63.Fa "const char *optstr"
 64.Fa "const char *key"
 65.Fa "unsigned long *result"
 66.Fc
 67.
 68.Ft bool
 69.Fo optstr_get_number_binary
 70.Fa "const char *optstr"
 71.Fa "const char *key"
 72.Fa "unsigned long *result"
 73.Fc
 74.
 75.Ft bool
 76.Fo optstr_get_number_hex
 77.Fa "const char *optstr"
 78.Fa "const char *key"
 79.Fa "unsigned long *result"
 80.Fc
 81.
 82.Ft bool
 83.Fo optstr_get_macaddr
 84.Fa "const char *optstr"
 85.Fa "const char *key"
 86.Fa "uint8_t result[ETHER_ADDR_LEN]"
 87.Fc
 88.
55.Sh DESCRIPTION 89.Sh DESCRIPTION
56An options string is a list of key/value pairs represented in textual form. 90An options string is a list of key/value pairs represented in textual form.
57Each pair is expressed as 91Each pair is expressed as
58.Sq 'key=value' 92.Ar key\^ Ns Li = Ns Ar value
59and is separated from other pairs by one or more spaces. 93and is separated from other pairs by one or more spaces.
60For example: 94For example:
61.Bd -literal 95.Pp
62key1=value1 key2=value2 key3=value3 96.Dl key1=value1 key2=value2 key3=value3
63.Ed 
64.Pp 97.Pp
65Options strings are used to pass information between userland programs and 98Options strings are used to pass information between userland programs and
66the kernel in a binary-agnostic way. 99the kernel in a binary-agnostic way.
67This makes them endianness and ABI independent. 100This makes them endianness and ABI independent.
68.Sh FUNCTIONS 101.Sh FUNCTIONS
69The following functions are provided to manage options strings: 102The following functions are provided to manage options strings:
70.Bl -tag -width compact 103.Bl -tag -width Fn
71.It Fn optstr_get "optstr" "key" "buf" "bufsize" 104.It Fn optstr_get "optstr" "key" "buf" "bufsize"
72Scans the 105Scans the
73.Va optstr 106.Fa optstr
74options string looking for the key 107options string looking for the key
75.Va key 108.Fa key
76and stores its value in the buffer pointed to by 109and stores its value in the buffer pointed to by
77.Va buf 110.Fa buf
78copying a maximum of 111copying a maximum of
79.Va bufsize 112.Fa bufsize
80bytes. 113bytes.
81Returns 114Returns
82.Sq true 115.Ql true
83if the key was found or 116if the key was found or
84.Sq false 117.Ql false
85otherwise, in which case 118otherwise, in which case
86.Va buf 119.Fa buf
87is left unmodified. 120is left unmodified.
88.El 121.El
89.Pp 122.Pp
90The 123The
91.Fn optstr_get_ITEM 124.Li optstr_get_ Ns Ar item
92family of functions provide the ability to scan for the key, and 125family of functions provide the ability to scan for the key, and
93return the value converted to an appropriate type. 126return the value converted to an appropriate type.
94.Pp 127.Pp
95.Bl -tag -width compact 128.Bl -tag -width Fn -compact
96.It Fn optstr_get_string "optstr" "key" "result" 129.It Fn optstr_get_string "optstr" "key" "result"
97.It Fn optstr_get_number "optstr" "key" "result" 130.It Fn optstr_get_number "optstr" "key" "result"
98.It Fn optstr_get_number_binary "optstr" "key" "result" 131.It Fn optstr_get_number_binary "optstr" "key" "result"
99.It Fn optstr_get_number_hex "optstr" "key" "result" 132.It Fn optstr_get_number_hex "optstr" "key" "result"
100.It Fn optstr_get_macaddr "optstr" "key" "result" 133.It Fn optstr_get_macaddr "optstr" "key" "result"
101.Pp 
102These functions scan the 134These functions scan the
103.Va optstr 135.Fa optstr
104options string looking for the key 136options string looking for the key
105.Va key 137.Fa key
106and returns the key value converted as per the function name in 138and returns the key value converted as per the function name in
107.Va result . 139.Fa result .
108All functions return 140All functions return
109.Sq true 141.Ql true
110if the key was found or 142if the key was found or
111.Sq false 143.Ql false
112otherwise, in which case 144otherwise, in which case
113.Va result 145.Fa result
114is left unmodified. 146is left unmodified.
115.El 147.El
116.Sh CODE REFERENCES 148.Sh CODE REFERENCES
117The options string management functions are implemented within the files 149The options string management functions are implemented within the files
118.Pa sys/kern/subr_optstr.c 150.Pa sys/kern/subr_optstr.c
119and 151and
120.Pa sys/sys/optstr.h . 152.Pa sys/sys/optstr.h .
121.Sh HISTORY 153.Sh HISTORY
122Options strings appeared in 154Options strings appeared in
123.Nx 4.0 . 155.Nx 4.0 .