sys/man/2/getfields

   1 .TH GETFIELDS 2
   2 .SH NAME
   3 getfields, gettokens, tokenize \- break a string into fields
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .ta \w'\fLchar* \fP'u
  10 .B
  11 int     getfields(char *str, char **args, int maxargs, int multiflag,
  12 .br
  13 .B
  14             char *delims)
  15 .PP
  16 .B
  17 int     gettokens(char *str, char **args, int maxargs, char *delims)
  18 .PP
  19 .B
  20 int     tokenize(char *str, char **args, int maxargs)
  21 .SH DESCRIPTION
  22 .I Getfields
  23 places into the array
  24 .I args
  25 pointers to the first
  26 .I maxargs
  27 fields of the null terminated
  28 .SM UTF
  29 string
  30 .IR str .
  31 Delimiters between these fields are set to null.
  32 .PP
  33 Fields are substrings of
  34 .I str
  35 whose definition depends on the value of
  36 .IR multiflag.
  37 If
  38 .I multiflag
  39 is zero,
  40 adjacent fields are separated by exactly one delimiter.
  41 For example
  42 .EX
  43
  44         getfields("#alice#bob##charles###", arg, 3, 0, "#");
  45
  46 .EE
  47 yields three substrings:
  48 null-string ,
  49 .BR "alice" ,
  50 and
  51 .BR "bob##charles###" .
  52 If the
  53 .I multiflag
  54 argument is not zero,
  55 a field is a non-empty string of non-delimiters.
  56 For example
  57 .EX
  58
  59         getfields("#alice#bob##charles###", arg, 3, 1, "#");
  60
  61 .EE
  62 yields the three substrings:
  63 .BR "alice" ,
  64 .BR "bob" ,
  65 and
  66 .BR "charles###" .
  67 .PP
  68 Getfields returns the number of fields pointed to.
  69 .PP
  70 .I Gettokens
  71 is the same as
  72 .I getfields
  73 with
  74 .I multiflag
  75 non-zero,
  76 except that fields may be quoted using single quotes, in the manner
  77 of
  78 .IR rc (1).
  79 Any such quotes remain in the resulting
  80 .IR args .
  81 See
  82 .IR quote (2)
  83 for related quote-handling software.
  84 .PP
  85 .I Tokenize
  86 is similar to
  87 .I gettokens
  88 with
  89 .I delims
  90 set to \f5"\et\er\en\ "\fP,
  91 except that quotes are interpreted but do not appear in the resulting
  92 .IR args .
  93 .SH SOURCE
  94 .B /sys/src/libc/port/getfields.c
  95 .br
  96 .B /sys/src/libc/port/tokenize.c
  97 .SH SEE ALSO
  98 .I strtok
  99 in
 100 .IR strcat (2),
 101 .IR quote (2).