optstr(9) - NetBSD Manual Pages

OPTSTR(9)              NetBSD Kernel Developer's Manual              OPTSTR(9)


NAME

     optstr_get, optstr_get_string, optstr_get_number,
     optstr_get_number_binary, optstr_get_number_hex, optstr_get_macaddr --
     Options string management


SYNOPSIS

     #include <sys/optstr.h>

     bool
     optstr_get(const char *optstr, const char *key, char *buf,
         size_t bufsize);

     bool
     optstr_get_string(const char *optstr, const char *key, char **result);

     bool
     optstr_get_number(const char *optstr, const char *key,
         unsigned long *result);

     bool
     optstr_get_number_binary(const char *optstr, const char *key,
         unsigned long *result);

     bool
     optstr_get_number_hex(const char *optstr, const char *key,
         unsigned long *result);

     bool
     optstr_get_macaddr(const char *optstr, const char *key,
         uint8_t result[ETHER_ADDR_LEN]);


DESCRIPTION

     An options string is a list of key/value pairs represented in textual
     form.  Each pair is expressed as key=value and is separated from other
     pairs by one or more spaces.  For example:

           key1=value1 key2=value2 key3=value3

     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.


FUNCTIONS

     The following functions are provided to manage options strings:

     optstr_get(optstr, key, buf, bufsize)
                       Scans the optstr options string looking for the key key
                       and stores its value in the buffer pointed to by buf
                       copying a maximum of bufsize bytes.  Returns `true' if
                       the key was found or `false' otherwise, in which case
                       buf is left unmodified.

     The optstr_get_item family of functions provide the ability to scan for
     the key, and return the value converted to an appropriate type.

     optstr_get_string(optstr, key, result)
     optstr_get_number(optstr, key, result)
     optstr_get_number_binary(optstr, key, result)
     optstr_get_number_hex(optstr, key, result)
     optstr_get_macaddr(optstr, key, result)
                       These functions scan the optstr options string looking
                       for the key key and returns the key value converted as
                       per the function name in result.  All functions return
                       `true' if the key was found or `false' otherwise, in
                       which case result is left unmodified.


CODE REFERENCES

     The options string management functions are implemented within the files
     sys/kern/subr_optstr.c and sys/sys/optstr.h.


HISTORY

     Options strings appeared in NetBSD 4.0.

NetBSD 10.99                     May 20, 2023                     NetBSD 10.99