diff options
Diffstat (limited to 'static/netbsd/man9/optstr.9')
| -rw-r--r-- | static/netbsd/man9/optstr.9 | 155 |
1 files changed, 155 insertions, 0 deletions
diff --git a/static/netbsd/man9/optstr.9 b/static/netbsd/man9/optstr.9 new file mode 100644 index 00000000..8ca3b79a --- /dev/null +++ b/static/netbsd/man9/optstr.9 @@ -0,0 +1,155 @@ +.\" $NetBSD: optstr.9,v 1.6 2023/04/20 10:43:17 uwe Exp $ +.\" +.\" Copyright (c) 2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Julio M. Merino Vidal. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (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 May 20, 2023 +.Dt OPTSTR 9 +.Os +. +.Sh NAME +.Nm optstr_get , +.Nm optstr_get_string , +.Nm optstr_get_number , +.Nm optstr_get_number_binary , +.Nm optstr_get_number_hex , +.Nm optstr_get_macaddr +.Nd Options string management +. +.Sh SYNOPSIS +.In sys/optstr.h +. +.Ft bool +.Fo optstr_get +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "char *buf" +.Fa "size_t bufsize" +.Fc +. +.Ft bool +.Fo optstr_get_string +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "char **result" +.Fc +. +.Ft bool +.Fo optstr_get_number +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "unsigned long *result" +.Fc +. +.Ft bool +.Fo optstr_get_number_binary +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "unsigned long *result" +.Fc +. +.Ft bool +.Fo optstr_get_number_hex +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "unsigned long *result" +.Fc +. +.Ft bool +.Fo optstr_get_macaddr +.Fa "const char *optstr" +.Fa "const char *key" +.Fa "uint8_t result[ETHER_ADDR_LEN]" +.Fc +. +.Sh DESCRIPTION +An options string is a list of key/value pairs represented in textual form. +Each pair is expressed as +.Ar key\^ Ns Li = Ns Ar value +and is separated from other pairs by one or more spaces. +For example: +.Pp +.Dl key1=value1 key2=value2 key3=value3 +.Pp +Options strings are used to pass information between userland programs and +the kernel in a binary-agnostic way. +This makes them endianness and ABI independent. +.Sh FUNCTIONS +The following functions are provided to manage options strings: +.Bl -tag -width Fn +.It Fn optstr_get "optstr" "key" "buf" "bufsize" +Scans the +.Fa optstr +options string looking for the key +.Fa key +and stores its value in the buffer pointed to by +.Fa buf +copying a maximum of +.Fa bufsize +bytes. +Returns +.Ql true +if the key was found or +.Ql false +otherwise, in which case +.Fa buf +is left unmodified. +.El +.Pp +The +.Li optstr_get_ Ns Ar item +family of functions provide the ability to scan for the key, and +return the value converted to an appropriate type. +.Pp +.Bl -tag -width Fn -compact +.It Fn optstr_get_string "optstr" "key" "result" +.It Fn optstr_get_number "optstr" "key" "result" +.It Fn optstr_get_number_binary "optstr" "key" "result" +.It Fn optstr_get_number_hex "optstr" "key" "result" +.It Fn optstr_get_macaddr "optstr" "key" "result" +These functions scan the +.Fa optstr +options string looking for the key +.Fa key +and returns the key value converted as per the function name in +.Fa result . +All functions return +.Ql true +if the key was found or +.Ql false +otherwise, in which case +.Fa result +is left unmodified. +.El +.Sh CODE REFERENCES +The options string management functions are implemented within the files +.Pa sys/kern/subr_optstr.c +and +.Pa sys/sys/optstr.h . +.Sh HISTORY +Options strings appeared in +.Nx 4.0 . |