1.\" $NetBSD: strlist.9,v 1.3 2021/01/21 17:05:50 wiz Exp $ 2.\" 3.\" Copyright (c) 2021 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 20, 2021 31.Dt OFSL 9 32.Os 33.Sh NAME 34.Nm strlist , 35.Nm strlist_next , 36.Nm strlist_count , 37.Nm strlist_string , 38.Nm strlist_match , 39.Nm strlist_index , 40.Nm strlist_append 41.Nd functions to interact with OpenFirmware-style string lists 42.Sh SYNOPSIS 43.In sys/systm.h 44.Ft const char * 45.Fn strlist_next "const char *sl" "size_t slsize" "size_t *cursorp" 46.Ft void 47.Fn strlist_count "const char *sl" "size_t slsize" 48.Ft const char * 49.Fn strlist_string "const char *sl" "size_t slsize" "unsigned int index" 50.Ft int 51.Fn strlist_match "const char *sl" "size_t slsize" "const char *str" 52.Ft int 53.Fn strlist_pmatch "const char *sl" "size_t slsize" "const char *pattern" 54.Ft int 55.Fn strlist_index "const char *sl" "size_t slsize" "const char *str" 56.Ft bool 57.Fn strlist_append "char **slp" "size_t *slsizep" "const char *str" 58.Sh DESCRIPTION 59The 60.Nm 61functions provide a simple way to interact with OpenFirmware 62.Pq IEEE 1275 63string lists. 64.Pp 65An OpenFirmware string list is simply a buffer containing one or more 66NUL-terminated strings concatenated together. 67For example, a string list containing the strings 68.Dq foo , 69.Dq bar , 70and 71.Dq baz 72would be represented in memory as: 73.Bd -literal -offset indent 74foo\\0bar\\0baz\\0 75.Ed 76.Pp 77The following functions are available: 78.Bl -tag -width "xxxxx" 79.It Fn strlist_next "const char *sl" "size_t slsize" "size_t *cursorp" 80This function provides a way to enumerate the strings in a string list. 81To enumerate a string list, initialize 82.Fa cursor 83to 0 and pass it by reference to 84.Fn strlist_next . 85Each call to 86.Fn strlist_next 87returns the current string and advances the cursor to the next string in 88the list. 89If all strings in the list have been enumerated, 90.Fn strlist_next 91will return 92.Dv NULL . 93.It Fn strlist_count "const char *sl" "size_t slsize" 94Returns the number of strings in the string list. 95.It Fn strlist_string "const char *sl" "size_t slsize" "unsigned int index" 96Returns a pointer to the string in the string list at the specified 97index or 98.Dv NULL 99if the index is out of range. 100.It Fn strlist_match "const char *sl" "size_t slsize" "const char *str" 101Returns a weighted match value if the specified string appears in 102the string list. 103The value returned is the number of strings in the string list 104minus the index of the matched string. 105For example, if a string list contains the strings 106.Dq foo , 107.Dq bar , 108and 109.Dq baz , 110a match against 111.Dq foo 112returns 3 and a match against 113.Dq baz 114returns 1. 115If the string does not appear in the string list, 0 is returned. 116.It Fn strlist_pmatch "const char *sl" "size_t slsize" "const char *pattern" 117Like 118.Fn strlist_match , 119but uses 120.Fn pmatch 121to compare strings, allowing for wildcard characters to be specified in 122.Fa pattern . 123.It Fn strlist_index "const char *sl" "size_t slsize" "const char *str" 124Returns the index of the specified string if it appears in the 125string list, or \-1 if the string does not appear in the string list. 126.It Fn strlist_append "char **slp" "size_t *slsizep" "const char *str" 127Appends a copy of the specified string to the stringlist. 128Begin by initializing 129.Fa sl 130to 131.Dv NULL 132and 133.Fa slsize 134to 0. 135Pass these by reference to 136.Fn strlist_append . 137New memory for the string list will be allocated as needed. 138The resulting string list can be freed with 139.Fn kmem_free . 140Returns 141.Dv true 142if the string was successfully appended to the string list or 143.Dv false 144if memory allocation fails. 145.El 146.Sh EXAMPLES 147The following shows an example of string list enumeration using 148.Fn strlist_next : 149.Bd -literal 150void 151print_stringlist(const char *sl, size_t slsize) 152{ 153 const char *cp; 154 size_t cursor; 155 156 printf("There are %u strings in the string list:\\n", 157 strlist_count(sl, slsize)); 158 for (cursor = 0; 159 (cp = strlist_next(sl, slsize, &cursor) != NULL; ) { 160 printf("\\t%s\\n", cp); 161 } 162} 163.Ed 164.Pp 165The following example shows a simple way to use 166.Fn strlist_match : 167.Bd -literal 168bool 169is_compatible(int phandle, const char *compat_str) 170{ 171 char buf[128]; 172 int proplen; 173 174 proplen = OF_getprop(phandle, "compatible", buf, sizeof(buf)); 175 return strlist_match(buf, proplen, compat_str) != 0; 176} 177.Ed 178.Pp 179The following example shows a use of 180.Fn strlist_pmatch : 181.Bd -literal 182bool 183is_pc_printer_port(const char *pnp_id_list, size_t list_size) 184{ 185 return strlist_pmatch(pnp_id_list, list_size, "PNP04??") != 0; 186} 187.Ed 188.Pp 189The following example converts an array of strings to a string list using 190.Fn strlist_append : 191.Bd -literal 192char * 193string_array_to_string_list(const char **array, int count, 194 size_t *slsizep) 195{ 196 char *sl; 197 size_t slsize; 198 int i; 199 200 for (i = 0, sl = NULL, slsize = 0; i < count; i++) { 201 if (!strlist_append(&sl, &slsize, array[i])) { 202 kmem_free(sl, slsize); 203 return NULL; 204 } 205 } 206 207 *slsizep = slsize; 208 return sl; 209} 210.Ed 211.Sh SEE ALSO 212.Xr kmem 9 , 213.Xr pmatch 9 214.Sh HISTORY 215The 216.Nm 217functions first appeared in 218.Nx 10.0 . 219