Manual Page Result
0
Command: strlist_next | Section: 9 | Source: NetBSD | File: strlist_next.9
OFSL(9) FreeBSD Kernel Developer's Manual OFSL(9)
NAME
strlist, strlist_next, strlist_count, strlist_string, strlist_match,
strlist_index, strlist_append - functions to interact with OpenFirmware-
style string lists
SYNOPSIS
#include <sys/systm.h>
const char *
strlist_next(const char *sl, size_t slsize, size_t *cursorp);
void
strlist_count(const char *sl, size_t slsize);
const char *
strlist_string(const char *sl, size_t slsize, unsigned int index);
int
strlist_match(const char *sl, size_t slsize, const char *str);
int
strlist_pmatch(const char *sl, size_t slsize, const char *pattern);
int
strlist_index(const char *sl, size_t slsize, const char *str);
bool
strlist_append(char **slp, size_t *slsizep, const char *str);
DESCRIPTION
The strlist functions provide a simple way to interact with OpenFirmware
(IEEE 1275) string lists.
An OpenFirmware string list is simply a buffer containing one or more
NUL-terminated strings concatenated together. For example, a string list
containing the strings "foo", "bar", and "baz" would be represented in
memory as:
foo\0bar\0baz\0
The following functions are available:
strlist_next(const char *sl, size_t slsize, size_t *cursorp)
This function provides a way to enumerate the strings in a string
list. To enumerate a string list, initialize cursor to 0 and pass
it by reference to strlist_next(). Each call to strlist_next()
returns the current string and advances the cursor to the next
string in the list. If all strings in the list have been
enumerated, strlist_next() will return NULL.
strlist_count(const char *sl, size_t slsize)
Returns the number of strings in the string list.
strlist_string(const char *sl, size_t slsize, unsigned int index)
Returns a pointer to the string in the string list at the
specified index or NULL if the index is out of range.
strlist_match(const char *sl, size_t slsize, const char *str)
Returns a weighted match value if the specified string appears in
the string list. The value returned is the number of strings in
the string list minus the index of the matched string. For
example, if a string list contains the strings "foo", "bar", and
"baz", a match against "foo" returns 3 and a match against "baz"
returns 1. If the string does not appear in the string list, 0 is
returned.
strlist_pmatch(const char *sl, size_t slsize, const char *pattern)
Like strlist_match(), but uses pmatch() to compare strings,
allowing for wildcard characters to be specified in pattern.
strlist_index(const char *sl, size_t slsize, const char *str)
Returns the index of the specified string if it appears in the
string list, or -1 if the string does not appear in the string
list.
strlist_append(char **slp, size_t *slsizep, const char *str)
Appends a copy of the specified string to the stringlist. Begin
by initializing sl to NULL and slsize to 0. Pass these by
reference to strlist_append(). New memory for the string list
will be allocated as needed. The resulting string list can be
freed with kmem_free(). Returns true if the string was
successfully appended to the string list or false if memory
allocation fails.
EXAMPLES
The following shows an example of string list enumeration using
strlist_next():
void
print_stringlist(const char *sl, size_t slsize)
{
const char *cp;
size_t cursor;
printf("There are %u strings in the string list:\n",
strlist_count(sl, slsize));
for (cursor = 0;
(cp = strlist_next(sl, slsize, &cursor) != NULL; ) {
printf("\t%s\n", cp);
}
}
The following example shows a simple way to use strlist_match():
bool
is_compatible(int phandle, const char *compat_str)
{
char buf[128];
int proplen;
proplen = OF_getprop(phandle, "compatible", buf, sizeof(buf));
return strlist_match(buf, proplen, compat_str) != 0;
}
The following example shows a use of strlist_pmatch():
bool
is_pc_printer_port(const char *pnp_id_list, size_t list_size)
{
return strlist_pmatch(pnp_id_list, list_size, "PNP04??") != 0;
}
The following example converts an array of strings to a string list using
strlist_append():
char *
string_array_to_string_list(const char **array, int count,
size_t *slsizep)
{
char *sl;
size_t slsize;
int i;
for (i = 0, sl = NULL, slsize = 0; i < count; i++) {
if (!strlist_append(&sl, &slsize, array[i])) {
kmem_free(sl, slsize);
return NULL;
}
}
*slsizep = slsize;
return sl;
}
SEE ALSO
kmem(9), pmatch(9)
HISTORY
The strlist functions first appeared in NetBSD 10.0.
FreeBSD 14.1-RELEASE-p8 January 20, 2021 FreeBSD 14.1-RELEASE-p8