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.