diff options
Diffstat (limited to 'static/netbsd/man9/strlist.9')
| -rw-r--r-- | static/netbsd/man9/strlist.9 | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/static/netbsd/man9/strlist.9 b/static/netbsd/man9/strlist.9 new file mode 100644 index 00000000..c2bd861d --- /dev/null +++ b/static/netbsd/man9/strlist.9 @@ -0,0 +1,218 @@ +.\" $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 . |