219 lines
6.3 KiB
Groff
219 lines
6.3 KiB
Groff
.\" $NetBSD: strlist.9,v 1.3 2021/01/21 17:05:50 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2021 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Jason R. Thorpe.
|
|
.\"
|
|
.\" 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 January 20, 2021
|
|
.Dt OFSL 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm strlist ,
|
|
.Nm strlist_next ,
|
|
.Nm strlist_count ,
|
|
.Nm strlist_string ,
|
|
.Nm strlist_match ,
|
|
.Nm strlist_index ,
|
|
.Nm strlist_append
|
|
.Nd functions to interact with OpenFirmware-style string lists
|
|
.Sh SYNOPSIS
|
|
.In sys/systm.h
|
|
.Ft const char *
|
|
.Fn strlist_next "const char *sl" "size_t slsize" "size_t *cursorp"
|
|
.Ft void
|
|
.Fn strlist_count "const char *sl" "size_t slsize"
|
|
.Ft const char *
|
|
.Fn strlist_string "const char *sl" "size_t slsize" "unsigned int index"
|
|
.Ft int
|
|
.Fn strlist_match "const char *sl" "size_t slsize" "const char *str"
|
|
.Ft int
|
|
.Fn strlist_pmatch "const char *sl" "size_t slsize" "const char *pattern"
|
|
.Ft int
|
|
.Fn strlist_index "const char *sl" "size_t slsize" "const char *str"
|
|
.Ft bool
|
|
.Fn strlist_append "char **slp" "size_t *slsizep" "const char *str"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
functions provide a simple way to interact with OpenFirmware
|
|
.Pq IEEE 1275
|
|
string lists.
|
|
.Pp
|
|
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
|
|
.Dq foo ,
|
|
.Dq bar ,
|
|
and
|
|
.Dq baz
|
|
would be represented in memory as:
|
|
.Bd -literal -offset indent
|
|
foo\\0bar\\0baz\\0
|
|
.Ed
|
|
.Pp
|
|
The following functions are available:
|
|
.Bl -tag -width "xxxxx"
|
|
.It Fn 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
|
|
.Fa cursor
|
|
to 0 and pass it by reference to
|
|
.Fn strlist_next .
|
|
Each call to
|
|
.Fn 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,
|
|
.Fn strlist_next
|
|
will return
|
|
.Dv NULL .
|
|
.It Fn strlist_count "const char *sl" "size_t slsize"
|
|
Returns the number of strings in the string list.
|
|
.It Fn 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
|
|
.Dv NULL
|
|
if the index is out of range.
|
|
.It Fn 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
|
|
.Dq foo ,
|
|
.Dq bar ,
|
|
and
|
|
.Dq baz ,
|
|
a match against
|
|
.Dq foo
|
|
returns 3 and a match against
|
|
.Dq baz
|
|
returns 1.
|
|
If the string does not appear in the string list, 0 is returned.
|
|
.It Fn strlist_pmatch "const char *sl" "size_t slsize" "const char *pattern"
|
|
Like
|
|
.Fn strlist_match ,
|
|
but uses
|
|
.Fn pmatch
|
|
to compare strings, allowing for wildcard characters to be specified in
|
|
.Fa pattern .
|
|
.It Fn 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.
|
|
.It Fn strlist_append "char **slp" "size_t *slsizep" "const char *str"
|
|
Appends a copy of the specified string to the stringlist.
|
|
Begin by initializing
|
|
.Fa sl
|
|
to
|
|
.Dv NULL
|
|
and
|
|
.Fa slsize
|
|
to 0.
|
|
Pass these by reference to
|
|
.Fn strlist_append .
|
|
New memory for the string list will be allocated as needed.
|
|
The resulting string list can be freed with
|
|
.Fn kmem_free .
|
|
Returns
|
|
.Dv true
|
|
if the string was successfully appended to the string list or
|
|
.Dv false
|
|
if memory allocation fails.
|
|
.El
|
|
.Sh EXAMPLES
|
|
The following shows an example of string list enumeration using
|
|
.Fn strlist_next :
|
|
.Bd -literal
|
|
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);
|
|
}
|
|
}
|
|
.Ed
|
|
.Pp
|
|
The following example shows a simple way to use
|
|
.Fn strlist_match :
|
|
.Bd -literal
|
|
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;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
The following example shows a use of
|
|
.Fn strlist_pmatch :
|
|
.Bd -literal
|
|
bool
|
|
is_pc_printer_port(const char *pnp_id_list, size_t list_size)
|
|
{
|
|
return strlist_pmatch(pnp_id_list, list_size, "PNP04??") != 0;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
The following example converts an array of strings to a string list using
|
|
.Fn strlist_append :
|
|
.Bd -literal
|
|
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;
|
|
}
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr kmem 9 ,
|
|
.Xr pmatch 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
functions first appeared in
|
|
.Nx 10.0 .
|