Source-Changes-HG archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

[src/trunk]: src/share/man/man9 Add a manual page for strlist(9).



details:   https://anonhg.NetBSD.org/src/rev/e392d1f464b9
branches:  trunk
changeset: 980048:e392d1f464b9
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Thu Jan 21 15:53:15 2021 +0000

description:
Add a manual page for strlist(9).

diffstat:

 distrib/sets/lists/comp/mi |   26 +++++-
 share/man/man9/Makefile    |   10 +-
 share/man/man9/strlist.9   |  218 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 252 insertions(+), 2 deletions(-)

diffs (truncated from 307 to 300 lines):

diff -r 96f55e4154c3 -r e392d1f464b9 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Thu Jan 21 15:44:14 2021 +0000
+++ b/distrib/sets/lists/comp/mi        Thu Jan 21 15:53:15 2021 +0000
@@ -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
diff -r 96f55e4154c3 -r e392d1f464b9 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Thu Jan 21 15:44:14 2021 +0000
+++ b/share/man/man9/Makefile   Thu Jan 21 15:53:15 2021 +0000
@@ -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 @@
        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 @@
        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 \
diff -r 96f55e4154c3 -r e392d1f464b9 share/man/man9/strlist.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/strlist.9  Thu Jan 21 15:53:15 2021 +0000
@@ -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



Home | Main Index | Thread Index | Old Index