OPTSTR(9)

OPTSTR(9) | 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.

May 20, 2023 | NetBSD 11.0