Updated: 2021/Feb/13


OFSL(9)                    Kernel Developer's Manual                   OFSL(9)

NAME
     strlist, strlist_next, strlist_count, strlist_string, strlist_match,
     strlist_index, strlist_append - functions to interact with OpenFirmware-
     style string lists

SYNOPSIS
     #include <sys/systm.h>

     const char *
     strlist_next(const char *sl, size_t slsize, size_t *cursorp);

     void
     strlist_count(const char *sl, size_t slsize);

     const char *
     strlist_string(const char *sl, size_t slsize, unsigned int index);

     int
     strlist_match(const char *sl, size_t slsize, const char *str);

     int
     strlist_pmatch(const char *sl, size_t slsize, const char *pattern);

     int
     strlist_index(const char *sl, size_t slsize, const char *str);

     bool
     strlist_append(char **slp, size_t *slsizep, const char *str);

DESCRIPTION
     The strlist functions provide a simple way to interact with OpenFirmware
     (IEEE 1275) string lists.

     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 "foo", "bar", and "baz" would be represented in
     memory as:

           foo\0bar\0baz\0

     The following functions are available:

     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 cursor to 0 and pass
            it by reference to strlist_next().  Each call to 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, strlist_next() will return NULL.

     strlist_count(const char *sl, size_t slsize)
            Returns the number of strings in the string list.

     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 NULL if the index is out of range.

     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 "foo", "bar", and
            "baz", a match against "foo" returns 3 and a match against "baz"
            returns 1.  If the string does not appear in the string list, 0 is
            returned.

     strlist_pmatch(const char *sl, size_t slsize, const char *pattern)
            Like strlist_match(), but uses pmatch() to compare strings,
            allowing for wildcard characters to be specified in pattern.

     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.

     strlist_append(char **slp, size_t *slsizep, const char *str)
            Appends a copy of the specified string to the stringlist.  Begin
            by initializing sl to NULL and slsize to 0.  Pass these by
            reference to strlist_append().  New memory for the string list
            will be allocated as needed.  The resulting string list can be
            freed with kmem_free().  Returns true if the string was
            successfully appended to the string list or false if memory
            allocation fails.

EXAMPLES
     The following shows an example of string list enumeration using
     strlist_next():

     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);
             }
     }

     The following example shows a simple way to use strlist_match():

     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;
     }

     The following example shows a use of strlist_pmatch():

     bool
     is_pc_printer_port(const char *pnp_id_list, size_t list_size)
     {
             return strlist_pmatch(pnp_id_list, list_size, "PNP04??") != 0;
     }

     The following example converts an array of strings to a string list using
     strlist_append():

     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;
     }

SEE ALSO
     kmem(9), pmatch(9)

HISTORY
     The strlist functions first appeared in NetBSD 10.0.

NetBSD 9.99                    January 20, 2021                    NetBSD 9.99