getfields 1.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899
  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. getfields("#alice#bob##charles###", arg, 3, 0, "#");
  44. .EE
  45. yields three substrings:
  46. null-string ,
  47. .BR "alice" ,
  48. and
  49. .BR "bob##charles###" .
  50. If the
  51. .I multiflag
  52. argument is not zero,
  53. a field is a non-empty string of non-delimiters.
  54. For example
  55. .EX
  56. getfields("#alice#bob##charles###", arg, 3, 1, "#");
  57. .EE
  58. yields the three substrings:
  59. .BR "alice" ,
  60. .BR "bob" ,
  61. and
  62. .BR "charles###" .
  63. .PP
  64. Getfields returns the number of fields pointed to.
  65. .PP
  66. .I Gettokens
  67. is the same as
  68. .I getfields
  69. with
  70. .I multiflag
  71. non-zero,
  72. except that fields may be quoted using single quotes, in the manner
  73. of
  74. .IR rc (1).
  75. Any such quotes remain in the resulting
  76. .IR args .
  77. See
  78. .IR quote (2)
  79. for related quote-handling software.
  80. .PP
  81. .I Tokenize
  82. is similar to
  83. .I gettokens
  84. with
  85. .I delims
  86. set to \f5"\et\er\en\ "\fP,
  87. except that quotes are interpreted but do not appear in the resulting
  88. .IR args .
  89. .SH SOURCE
  90. .B /sys/src/libc/port/tokenize.c
  91. .SH SEE ALSO
  92. .I strtok
  93. in
  94. .IR strcat (2),
  95. .IR quote (2).