Module Name: src
Committed By: thorpej
Date: Thu Jan 21 15:53:16 UTC 2021
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: strlist.9
Log Message:
Add a manual page for strlist(9).
To generate a diff of this commit:
cvs rdiff -u -r1.2371 -r1.2372 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.453 -r1.454 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/strlist.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.2371 src/distrib/sets/lists/comp/mi:1.2372
--- src/distrib/sets/lists/comp/mi:1.2371 Sun Jan 17 19:32:52 2021
+++ src/distrib/sets/lists/comp/mi Thu Jan 21 15:53:15 2021
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.2371 2021/01/17 19:32:52 rillig Exp $
+# $NetBSD: mi,v 1.2372 2021/01/21 15:53:15 thorpej Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -12227,6 +12227,14 @@
./usr/share/man/cat9/sprintf.0 comp-obsolete obsolete
./usr/share/man/cat9/stathz.0 comp-sys-catman .cat
./usr/share/man/cat9/store.0 comp-obsolete obsolete
+./usr/share/man/cat9/strlist.0 comp-sys-catman .cat
+./usr/share/man/cat9/strlist_append.0 comp-sys-catman .cat
+./usr/share/man/cat9/strlist_count.0 comp-sys-catman .cat
+./usr/share/man/cat9/strlist_index.0 comp-sys-catman .cat
+./usr/share/man/cat9/strlist_match.0 comp-sys-catman .cat
+./usr/share/man/cat9/strlist_next.0 comp-sys-catman .cat
+./usr/share/man/cat9/strlist_pmatch.0 comp-sys-catman .cat
+./usr/share/man/cat9/strlist_string.0 comp-sys-catman .cat
./usr/share/man/cat9/subyte.0 comp-obsolete obsolete
./usr/share/man/cat9/suibyte.0 comp-obsolete obsolete
./usr/share/man/cat9/suiword.0 comp-obsolete obsolete
@@ -20361,6 +20369,14 @@
./usr/share/man/html9/sprintf.html comp-obsolete obsolete
./usr/share/man/html9/stathz.html comp-sys-htmlman html
./usr/share/man/html9/store.html comp-obsolete obsolete
+./usr/share/man/html9/strlist.html comp-sys-htmlman html
+./usr/share/man/html9/strlist_append.html comp-sys-htmlman html
+./usr/share/man/html9/strlist_count.html comp-sys-htmlman html
+./usr/share/man/html9/strlist_index.html comp-sys-htmlman html
+./usr/share/man/html9/strlist_match.html comp-sys-htmlman html
+./usr/share/man/html9/strlist_next.html comp-sys-htmlman html
+./usr/share/man/html9/strlist_pmatch.html comp-sys-htmlman html
+./usr/share/man/html9/strlist_string.html comp-sys-htmlman html
./usr/share/man/html9/subyte.html comp-obsolete obsolete
./usr/share/man/html9/suibyte.html comp-obsolete obsolete
./usr/share/man/html9/suiword.html comp-obsolete obsolete
@@ -28693,6 +28709,14 @@
./usr/share/man/man9/sprintf.9 comp-obsolete obsolete
./usr/share/man/man9/stathz.9 comp-sys-man .man
./usr/share/man/man9/store.9 comp-obsolete obsolete
+./usr/share/man/man9/strlist.9 comp-sys-man .man
+./usr/share/man/man9/strlist_append.9 comp-sys-man .man
+./usr/share/man/man9/strlist_count.9 comp-sys-man .man
+./usr/share/man/man9/strlist_index.9 comp-sys-man .man
+./usr/share/man/man9/strlist_match.9 comp-sys-man .man
+./usr/share/man/man9/strlist_next.9 comp-sys-man .man
+./usr/share/man/man9/strlist_pmatch.9 comp-sys-man .man
+./usr/share/man/man9/strlist_string.9 comp-sys-man .man
./usr/share/man/man9/subyte.9 comp-obsolete obsolete
./usr/share/man/man9/suibyte.9 comp-obsolete obsolete
./usr/share/man/man9/suiword.9 comp-obsolete obsolete
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.453 src/share/man/man9/Makefile:1.454
--- src/share/man/man9/Makefile:1.453 Sat Oct 31 22:43:01 2020
+++ src/share/man/man9/Makefile Thu Jan 21 15:53:16 2021
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.453 2020/10/31 22:43:01 uwe Exp $
+# $NetBSD: Makefile,v 1.454 2021/01/21 15:53:16 thorpej Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -54,6 +54,7 @@ MAN= accept_filter.9 accf_data.9 accf_ht
SET.9 setbit.9 setjmp.9 shutdownhook_establish.9 \
signal.9 skpc.9 sockopt.9 softintr.9 spl.9 specificdata.9 \
spi.9 splraiseipl.9 \
+ strlist.9 \
suspendsched.9 \
sysctl.9 sysmon_envsys.9 sysmon_pswitch.9 sysmon_taskq.9 tc.9 \
tcp_congctl.9 thmap.9 threadpool.9 timecounter.9 time_second.9 todr.9 \
@@ -885,6 +886,13 @@ MLINKS+=spl.9 spl0.9 spl.9 splbio.9 spl.
spl.9 splsoftclock.9 spl.9 splsoftnet.9 spl.9 splsoftserial.9 \
spl.9 splstatclock.9 spl.9 spltty.9 spl.9 splvm.9 spl.9 splx.9 \
spl.9 splsoftbio.9
+MLINKS+=strlist.9 strlist_append.9 \
+ strlist.9 strlist_count.9 \
+ strlist.9 strlist_index.9 \
+ strlist.9 strlist_match.9 \
+ strlist.9 strlist_next.9 \
+ strlist.9 strlist_pmatch.9 \
+ strlist.9 strlist_string.9
MLINKS+=sysctl.9 old_sysctl.9 \
sysctl.9 sysctl_create.9 \
sysctl.9 sysctl_createv.9 \
Added files:
Index: src/share/man/man9/strlist.9
diff -u /dev/null src/share/man/man9/strlist.9:1.1
--- /dev/null Thu Jan 21 15:53:16 2021
+++ src/share/man/man9/strlist.9 Thu Jan 21 15:53:16 2021
@@ -0,0 +1,218 @@
+.\" $NetBSD: strlist.9,v 1.1 2021/01/21 15:53:16 thorpej 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 folowing 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
+.Xr strlist 9
+functions first appeared in
+.Nx 10.0 .
