Add some wrappers for usual loops around strsep(3)

[alejandro-colomar]

Suggested-by: @hallyn

---

Revisions:

v2

• Workaround two GCC bugs [@uecker , @pinskia]
  https://gcc.gnu.org/bugzilla/show_bug.cgi?id=118044
  https://gcc.gnu.org/bugzilla/show_bug.cgi?id=118043

$ git range-diff master gh/astrsep2ls astrsep2ls 
 1:  ad66293e !  1:  ccee0abc lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
    @@ lib/string/strtok/strsep2arr.h (new)
     +)
     +
     +
    -+ATTR_ACCESS(read_write, 1) ATTR_ACCESS(write_only, 4)
    ++ATTR_ACCESS(read_write, 1) ATTR_ACCESS(write_only, 4, 3)
     +ATTR_STRING(1) ATTR_STRING(2)
     +inline ssize_t strsep2arr(char *s, const char *restrict delim,
     +    size_t n, char *a[restrict n]);
 2:  5f98de6e !  2:  95f4a921 lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
    @@ lib/string/strtok/strsep2ls.h (new)
     +#define STRSEP2LS(s, delim, ls)  strsep2ls(s, delim, NITEMS(ls), ls)
     +
     +
    -+ATTR_ACCESS(read_write, 1) ATTR_ACCESS(write_only, 4)
    ++ATTR_ACCESS(read_write, 1) ATTR_ACCESS(write_only, 4, 3)
     +ATTR_STRING(1) ATTR_STRING(2)
     +inline ssize_t strsep2ls(char *s, const char *restrict delim,
     +    size_t n, char *ls[restrict n]);
 3:  a5390a9c =  3:  ab168394 lib/: Use STRSEP2LS() instead of its pattern
 4:  4f29f5e7 =  4:  411dd0be lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 5:  519fc865 =  5:  dc232372 lib/: Use strsep2arr() instead of its pattern
 6:  57f481b4 =  6:  a2dd29c8 lib/: Use STRSEP2ARR() instead of its pattern
 7:  70f747cc =  7:  884f9611 lib/string/strtok/: astrsep2ls(): Add function
 8:  3b908118 =  8:  abcaf9ed lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
 9:  28366e31 =  9:  60a02867 lib/string/strtok/: xastrsep2ls(): Add function
10:  8b6cac14 = 10:  040a7acf lib/: Use xastrsep2ls() instead of its pattern

v2b

• Rebase

$ git range-diff alx/master..gh/astrsep2ls master..astrsep2ls 
 1:  ccee0abc =  1:  060db63c lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  95f4a921 =  2:  2858fb22 lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  ab168394 =  3:  e2f2c2ed lib/: Use STRSEP2LS() instead of its pattern
 4:  411dd0be =  4:  a707b113 lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 5:  dc232372 =  5:  d7fdde21 lib/: Use strsep2arr() instead of its pattern
 6:  a2dd29c8 =  6:  b708da45 lib/: Use STRSEP2ARR() instead of its pattern
 7:  884f9611 =  7:  051e32e2 lib/string/strtok/: astrsep2ls(): Add function
 8:  abcaf9ed =  8:  9f3f560f lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
 9:  60a02867 =  9:  5f22734d lib/string/strtok/: xastrsep2ls(): Add function
10:  040a7acf = 10:  729949bd lib/: Use xastrsep2ls() instead of its pattern

v2c

• Rebase

$ git range-diff alx/master..gh/astrsep2ls master..astrsep2ls 
 1:  060db63c =  1:  8f864f1c lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  2858fb22 =  2:  2ed11b13 lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  e2f2c2ed =  3:  d246f9fe lib/: Use STRSEP2LS() instead of its pattern
 4:  a707b113 =  4:  06bff0e2 lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 5:  d7fdde21 =  5:  96e71394 lib/: Use strsep2arr() instead of its pattern
 6:  b708da45 !  6:  7fe618f2 lib/: Use STRSEP2ARR() instead of its pattern
    @@ src/newusers.c: int main (int argc, char **argv)
     -  char *cp;
        const struct passwd *pw;
        struct passwd newpw;
    -   int line = 0;
    +   intmax_t line = 0;
     @@ src/newusers.c: int main (int argc, char **argv)
                        fail_exit (EXIT_FAILURE);
                }
    @@ src/newusers.c: int main (int argc, char **argv)
     -          }
     -          if (nfields != 6) {
     +          if (STRSEP2ARR(buf, ":", fields) == -1) {
    -                   fprintf (stderr, _("%s: line %d: invalid line\n"),
    +                   fprintf (stderr, _("%s: line %jd: invalid line\n"),
                                 Prog, line);
                        fail_exit (EXIT_FAILURE);
 7:  051e32e2 =  7:  6b9865ad lib/string/strtok/: astrsep2ls(): Add function
 8:  9f3f560f =  8:  fa61d4da lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
 9:  5f22734d =  9:  faa72acd lib/string/strtok/: xastrsep2ls(): Add function
10:  729949bd = 10:  b4ce84cc lib/: Use xastrsep2ls() instead of its pattern

v2d

• Rebase

$ git range-diff master..gh/astrsep2ls shadow/master..astrsep2ls 
 1:  8f864f1c =  1:  c553fb99 lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  2ed11b13 =  2:  2aa3acd1 lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  d246f9fe =  3:  6af902d9 lib/: Use STRSEP2LS() instead of its pattern
 4:  06bff0e2 =  4:  7e4fe7d1 lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 5:  96e71394 =  5:  2203576f lib/: Use strsep2arr() instead of its pattern
 6:  7fe618f2 !  6:  806e7a74 lib/: Use STRSEP2ARR() instead of its pattern
    @@ lib/gshadow.c: sgetsgent(const char *string)
     +  if (STRSEP2ARR(sgrbuf, ":", fields) == -1)
                return NULL;
      
    -   sgroup.sg_name = fields[0];
    +   sgroup.sg_namp = fields[0];
     
      ## lib/sgetgrent.c ##
     @@
 7:  6b9865ad =  7:  9cc51b54 lib/string/strtok/: astrsep2ls(): Add function
 8:  fa61d4da =  8:  fe87cd70 lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
 9:  faa72acd =  9:  e3dd7f24 lib/string/strtok/: xastrsep2ls(): Add function
10:  b4ce84cc = 10:  0413de0a lib/: Use xastrsep2ls() instead of its pattern

v2e

• Rebase

$ git range-diff master..gh/astrsep2ls shadow/master..astrsep2ls 
 1:  c553fb99 =  1:  268cb83d lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  2aa3acd1 =  2:  b5ea7e1b lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  6af902d9 =  3:  c210ec07 lib/: Use STRSEP2LS() instead of its pattern
 4:  7e4fe7d1 =  4:  fa169f67 lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 5:  2203576f =  5:  34a8c828 lib/: Use strsep2arr() instead of its pattern
 6:  806e7a74 =  6:  203a400f lib/: Use STRSEP2ARR() instead of its pattern
 7:  9cc51b54 =  7:  ed1dc8c3 lib/string/strtok/: astrsep2ls(): Add function
 8:  fe87cd70 =  8:  c3f46d42 lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
 9:  e3dd7f24 =  9:  fcc1d8e9 lib/string/strtok/: xastrsep2ls(): Add function
10:  0413de0a = 10:  b93cc4d4 lib/: Use xastrsep2ls() instead of its pattern

v3

• Use strsep2ls() instead of STRSEP2LS() with non-array input.

$ git range-diff shadow/master gh/astrsep2ls astrsep2ls 
 1:  268cb83d =  1:  268cb83d lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  b5ea7e1b =  2:  b5ea7e1b lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 -:  -------- >  3:  7b0faaf6 lib/list.c: Use strsep2ls() instead of its pattern
 3:  c210ec07 !  4:  fdd8c924 lib/: Use STRSEP2LS() instead of its pattern
    @@ Metadata
     Author: Alejandro Colomar <[email protected]>
     
      ## Commit message ##
    -    lib/: Use STRSEP2LS() instead of its pattern
    +    lib/port.c: Use STRSEP2LS() instead of its pattern
     
         Signed-off-by: Alejandro Colomar <[email protected]>
     
    - ## lib/list.c ##
    -@@
    - #include "string/strchr/strchrcnt.h"
    - #include "string/strcmp/streq.h"
    - #include "string/strdup/xstrdup.h"
    -+#include "string/strtok/strsep2ls.h"
    - 
    - 
    - /*
    -@@ lib/list.c: comma_to_list(const char *comma)
    - {
    -   char *members;
    -   char **array;
    --  int i;
    --  char *cp;
    --  char *cp2;
    - 
    -   assert (NULL != comma);
    - 
    -@@ lib/list.c: comma_to_list(const char *comma)
    -           return array;
    -   }
    - 
    --  /*
    --   * Now go walk that list all over again, this time building the
    --   * array of pointers.
    --   */
    --
    --  for (cp = members, i = 0; cp != NULL; i++)
    --          array[i] = strsep(&cp, ",");
    --  array[i] = NULL;
    --
    --  /*
    --   * Return the new array of pointers
    --   */
    -+  STRSEP2LS(members, ",", array);
    - 
    -   return array;
    - }
    -
      ## lib/port.c ##
     @@
      #include "prototypes.h"
 4:  fa169f67 =  5:  5904aff5 lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 5:  34a8c828 =  6:  034175ba lib/: Use strsep2arr() instead of its pattern
 6:  203a400f =  7:  efbdb4a6 lib/: Use STRSEP2ARR() instead of its pattern
 7:  ed1dc8c3 =  8:  ca4c4959 lib/string/strtok/: astrsep2ls(): Add function
 8:  c3f46d42 =  9:  fafb2f36 lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
 9:  fcc1d8e9 = 10:  bf24bd3e lib/string/strtok/: xastrsep2ls(): Add function
10:  b93cc4d4 = 11:  2e6ef4b0 lib/: Use xastrsep2ls() instead of its pattern

v4

• Fix a few typos.

$ git range-diff shadow/master gh/astrsep2ls astrsep2ls 
 1:  268cb83d =  1:  268cb83d lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  b5ea7e1b =  2:  b5ea7e1b lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  7b0faaf6 =  3:  7b0faaf6 lib/list.c: Use strsep2ls() instead of its pattern
 4:  fdd8c924 =  4:  fdd8c924 lib/port.c: Use STRSEP2LS() instead of its pattern
 5:  5904aff5 !  5:  d0e9086e lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
    @@ lib/port.c: getportent(void)
        int   saveerr;
     -  char  *cp, *field;
     +  char  *cp;
    -+  char  fields[3];
    ++  char  *fields[3];
      
        static char            buf[BUFSIZ];
        static char            *ttys[PORT_TTY + 1];
 6:  034175ba =  6:  8493aeb5 lib/: Use strsep2arr() instead of its pattern
 7:  efbdb4a6 !  7:  a9dafec7 lib/: Use STRSEP2ARR() instead of its pattern
    @@ lib/subordinateio.c: subordinate_parse(const char *line)
     -   * the entry is invalid.  Also, fields must be non-blank.
     -   */
     -  if (i != SUBID_NFIELDS)
    -+  if (STRSEP2ARR(rangebuff, ":", fields) == -1)
    ++  if (STRSEP2ARR(rangebuf, ":", fields) == -1)
                return NULL;
     +
        if (streq(fields[0], ""))
 8:  ca4c4959 =  8:  d43aac97 lib/string/strtok/: astrsep2ls(): Add function
 9:  fafb2f36 =  9:  3cbeb393 lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
10:  bf24bd3e = 10:  df12d7eb lib/string/strtok/: xastrsep2ls(): Add function
11:  2e6ef4b0 = 11:  de41126e lib/: Use xastrsep2ls() instead of its pattern

v4b

• Rebase

$ git range-diff master..gh/astrsep2ls shadow/master..astrsep2ls 
 1:  268cb83d =  1:  aecd18a4 lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  b5ea7e1b =  2:  b84de158 lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  7b0faaf6 =  3:  ea06f0db lib/list.c: Use strsep2ls() instead of its pattern
 4:  fdd8c924 =  4:  5ac90f5d lib/port.c: Use STRSEP2LS() instead of its pattern
 5:  d0e9086e =  5:  6387fa80 lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 6:  8493aeb5 =  6:  4357ac55 lib/: Use strsep2arr() instead of its pattern
 7:  a9dafec7 =  7:  d82cccfa lib/: Use STRSEP2ARR() instead of its pattern
 8:  d43aac97 =  8:  d934164b lib/string/strtok/: astrsep2ls(): Add function
 9:  3cbeb393 =  9:  f6ed9958 lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
10:  df12d7eb = 10:  9cd4d325 lib/string/strtok/: xastrsep2ls(): Add function
11:  de41126e = 11:  0430e0bd lib/: Use xastrsep2ls() instead of its pattern

v5

• In function definitions, put the return type on a line of its own.
• Add comments spelling out the meaning of the letter-soup API names. [@hallyn]

$ git range-diff shadow/master gh/astrsep2ls astrsep2ls 
 1:  aecd18a4 !  1:  6b8d8482 lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
    @@ lib/string/strtok/strsep2arr.h (new)
     +    size_t n, char *a[restrict n]);
     +
     +
    ++// string separate to array-of-strings
     +// strsep(3) a string into an array of strings.
     +// Return the number of fields in the string, or -1 on error.
    -+inline ssize_t strsep2arr(char *s, const char *restrict delim,
    -+    size_t n, char *a[restrict n])
    ++inline ssize_t
    ++strsep2arr(char *s, const char *restrict delim, size_t n, char *a[restrict n])
     +{
     +  size_t  i;
     +
 2:  b84de158 !  2:  b8c2f8f1 lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
    @@ lib/string/strtok/strsep2ls.h (new)
     +    size_t n, char *ls[restrict n]);
     +
     +
    ++// string separate to list-of-strings
     +// Like strsep2arr(), but add a NULL terminator.
    -+inline ssize_t strsep2ls(char *s, const char *restrict delim,
    -+    size_t n, char *ls[restrict n])
    ++inline ssize_t
    ++strsep2ls(char *s, const char *restrict delim, size_t n, char *ls[restrict n])
     +{
     +  size_t  i;
     +
 3:  ea06f0db =  3:  5123cd78 lib/list.c: Use strsep2ls() instead of its pattern
 4:  5ac90f5d =  4:  03cf076e lib/port.c: Use STRSEP2LS() instead of its pattern
 5:  6387fa80 =  5:  33f6b3bc lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 6:  4357ac55 =  6:  b5d71210 lib/: Use strsep2arr() instead of its pattern
 7:  d82cccfa =  7:  5f03ea0e lib/: Use STRSEP2ARR() instead of its pattern
 8:  d934164b !  8:  0009294f lib/string/strtok/: astrsep2ls(): Add function
    @@ lib/string/strtok/astrsep2ls.h (new)
     +    size_t *restrict np);
     +
     +
    ++// allocate string separate to list-of-strings
     +// Like strsep2ls(), but allocate the list array.
    -+inline char **astrsep2ls(char *s, const char *restrict delim,
    -+    size_t *restrict np)
    ++inline char **
    ++astrsep2ls(char *s, const char *restrict delim, size_t *restrict np)
     +{
     +  char     **ls;
     +  ssize_t  n;
 9:  f6ed9958 =  9:  bbe3d126 lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
10:  9cd4d325 ! 10:  6c38440b lib/string/strtok/: xastrsep2ls(): Add function
    @@ lib/string/strtok/xastrsep2ls.h (new)
     +    size_t *restrict np);
     +
     +
    -+inline char **xastrsep2ls(char *s, const char *restrict delim,
    -+    size_t *restrict np)
    ++// exit-on-error allocate string separate to list-of-strings
    ++inline char **
    ++xastrsep2ls(char *s, const char *restrict delim, size_t *restrict np)
     +{
     +  char     **ls;
     +
11:  0430e0bd = 11:  62d4348d lib/: Use xastrsep2ls() instead of its pattern

v5b

• Rebase

$ git range-diff master..gh/astrsep2ls shadow/master..astrsep2ls 
 1:  6b8d8482 !  1:  5ae71be9 lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
    @@ Commit message
     
      ## lib/Makefile.am ##
     @@ lib/Makefile.am: libshadow_la_SOURCES = \
    -   string/strftime.h \
    +   string/strspn/strrspn.h \
        string/strtok/stpsep.c \
        string/strtok/stpsep.h \
     +  string/strtok/strsep2arr.c \
 2:  b8c2f8f1 =  2:  d3c5cccb lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  5123cd78 =  3:  6f92964e lib/list.c: Use strsep2ls() instead of its pattern
 4:  03cf076e =  4:  f919b470 lib/port.c: Use STRSEP2LS() instead of its pattern
 5:  33f6b3bc =  5:  51e52f8e lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 6:  b5d71210 =  6:  84274eeb lib/: Use strsep2arr() instead of its pattern
 7:  5f03ea0e =  7:  094f8c13 lib/: Use STRSEP2ARR() instead of its pattern
 8:  0009294f !  8:  dbfd45b0 lib/string/strtok/: astrsep2ls(): Add function
    @@ Commit message
     
      ## lib/Makefile.am ##
     @@ lib/Makefile.am: libshadow_la_SOURCES = \
    -   string/strftime.h \
    +   string/strspn/strrspn.h \
        string/strtok/stpsep.c \
        string/strtok/stpsep.h \
     +  string/strtok/astrsep2ls.c \
 9:  bbe3d126 =  9:  7d95317f lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
10:  6c38440b = 10:  acdd17da lib/string/strtok/: xastrsep2ls(): Add function
11:  62d4348d = 11:  7f723f5f lib/: Use xastrsep2ls() instead of its pattern

v5c

• Rebase

$ git range-diff master..gh/astrsep2ls shadow/master..astrsep2ls 
 1:  5ae71be9 =  1:  7296bb71 lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  d3c5cccb =  2:  1013737d lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  6f92964e =  3:  19d4b8a0 lib/list.c: Use strsep2ls() instead of its pattern
 4:  f919b470 =  4:  725f450b lib/port.c: Use STRSEP2LS() instead of its pattern
 5:  51e52f8e =  5:  68168f2e lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 6:  84274eeb =  6:  4376c10b lib/: Use strsep2arr() instead of its pattern
 7:  094f8c13 !  7:  fe6697fa lib/: Use STRSEP2ARR() instead of its pattern
    @@ lib/sgetpwent.c: sgetpwent(const char *buf)
     
      ## lib/subordinateio.c ##
     @@
    - #include "atoi/str2i/str2u.h"
    + #include "string/ctype/strisascii/strisdigit.h"
      #include "string/sprintf/snprintf.h"
      #include "string/strcmp/streq.h"
     +#include "string/strtok/strsep2arr.h"
 8:  dbfd45b0 =  8:  ec9c9dd8 lib/string/strtok/: astrsep2ls(): Add function
 9:  7d95317f =  9:  161ba558 lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
10:  acdd17da = 10:  a6a4f8a0 lib/string/strtok/: xastrsep2ls(): Add function
11:  7f723f5f = 11:  b53790c5 lib/: Use xastrsep2ls() instead of its pattern

v5d

• Rebase

$ git range-diff master..gh/astrsep2ls shadow/master..astrsep2ls 
 1:  7296bb71 =  1:  46316135 lib/string/strtok/: strsep2arr(), STRSEP2ARR(): Add APIs
 2:  1013737d =  2:  95473371 lib/string/strtok/: strsep2ls(), STRSEP2LS(): Add APIs
 3:  19d4b8a0 =  3:  49d0d7f4 lib/list.c: Use strsep2ls() instead of its pattern
 4:  725f450b =  4:  472f8937 lib/port.c: Use STRSEP2LS() instead of its pattern
 5:  68168f2e =  5:  02eb448a lib/port.c: getportent(): Use STRSEP2ARR() instead of its pattern
 6:  4376c10b =  6:  0cb74f80 lib/: Use strsep2arr() instead of its pattern
 7:  fe6697fa =  7:  f544508d lib/: Use STRSEP2ARR() instead of its pattern
 8:  ec9c9dd8 =  8:  57968091 lib/string/strtok/: astrsep2ls(): Add function
 9:  161ba558 =  9:  ff5d3838 lib/sgetgrent.c: list(): Explicitly free(3) at the start of the function
10:  a6a4f8a0 = 10:  6abcc1fa lib/string/strtok/: xastrsep2ls(): Add function
11:  b53790c5 = 11:  be9ecea5 lib/: Use xastrsep2ls() instead of its pattern