getfields(2) [plan9 man page]

GETFIELDS(2)							System Calls Manual						      GETFIELDS(2)

NAME

       getfields, getmfields, setfields, tokenize - break a string into fields

SYNOPSIS

       #include <u.h>
       #include <libc.h>

       int   getfields(char *str, char **ptrs, int nptrs)

       int   getmfields(char *str, char **ptrs, int nptrs)

       char* setfields(char *fielddelim)

       int   tokenize(char *str, char **args, int max)

DESCRIPTION

       Getfields  breaks the null-terminated string str into at most nptrs null-terminated fields and places pointers to the start of these fields
       in the array ptrs.  It returns the number of fields and terminates the list of pointers with a zero pointer.  It  overwrites  some  of  the
       bytes  in  str.	If there are nptr or more fields, the list will not end with zero and the last `field' will extend to the end of the input
       string and may contain delimiters.

       A field is defined as a maximal sequence of characters not in a set of field delimiters.  Adjacent fields  are  separated  by  exactly  one
       delimiter.   No	field follows a delimiter at the end of string.  Thus a string of just two delimiter characters contains two empty fields,
       and a nonempty string with no delimiters contains one field.

       Getmfields is the same as getfields except that fields are separated by maximal strings of field delimiters rather than just one.

       Setfields makes the field delimiters (space and tab by default) be the characters of the string fielddelim  and	returns  a  pointer  to  a
       string of the previous delimiters.

       Tokenize  breaks  null-terminated string str into tokens by replacing every blank or newline with a null byte.  Pointers to successive non-
       empty tokens are placed in args.  Processing stops after max tokens are processed.  Tokenize returns the number of tokens processed.   Tok-
       enize does not terminate args with a null pointer.

   Alef
       Of these routines, only tokenize is in Alef.

SOURCE

       /sys/src/libc/port/getfields.c
       /sys/src/libc/port/tokenize.c

SEE ALSO

       strtok in strcat(2)

																      GETFIELDS(2)

strtok(3)						     Library Functions Manual							 strtok(3)

NAME

       strtok, strtok_r - Split string into tokens

LIBRARY

       Standard C Library (libc.so, libc.a)

SYNOPSIS

       #include <string.h>

       char *strtok(
	       char *s1,
	       const char *s2);

       char *strtok_r(
	       char *s1,
	       const char *s2,
	       char **savept);

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       strtok_r():  POSIX.1c

       strtok():  XPG4, XPG4-UNIX

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Contains a pointer to the string to be searched.  Contains a pointer to the string of byte token delimiters.  [POSIX]  Identifies the loca-
       tion of the byte where the search for tokens should be started in the next call to strtok_r(). The savept parameter contains a pointer to a
       variable that contains a pointer to the byte in the string.

DESCRIPTION

       The  strtok()  function	splits	the  string pointed to by the s1 parameter into a sequence of tokens, each of which is delimited by a byte
       equal to one of the bytes in the s2 parameter.

       Usually, the strtok() function is called repeatedly to extract the tokens in a string.  The first time the application  program	calls  the
       strtok()  function,  it	sets  the s1 parameter to point to the input string.  The function returns a pointer to the first token.  Then the
       application program calls the function again with the s1 parameter set to the null pointer.  This call returns a pointer to the next  token
       in  the	string. The application program repeats the call to strtok() with the s1 parameter set to the null pointer until all the tokens in
       the string have been returned.

									  Note

       If the input string contains no instances of bytes from the delimiter string, the first call to strtok() results in the return of a pointer
       to the original string.	On subsequent calls, strtok() returns NULL.

       In  the	initial call to strtok(), the function first searches the string pointed to by the s1 parameter to locate the first byte that does
       not occur in the delimiter string pointed to by the s2 parameter.  If such a byte is found, it is the start of the first token.	 The  str-
       tok()  function	then searches from there for a byte that does occur in the delimiter string.  If such a delimiter is found, strtok() over-
       writes it with a null byte, which terminates the current token.	The strtok() function saves a pointer to the byte following the null  byte
       and returns a pointer to the start of the token.

       In  the	subsequent  calls  to strtok(), in which the s1 parameter is set to the null pointer, the function starts at its saved pointer and
       searches for the next byte that does not occur in the delimiter string pointed to by the s2 parameter.  If such a byte is found, it is  the
       start  of  the  new  token.   The strtok() function then searches from there for a byte that does occur in the delimiter string.  If such a
       delimiter is found, strtok() overwrites it with a null byte, which terminates the new token.  The strtok() function saves a pointer to  the
       byte following the null byte and returns a pointer to the start of the new token.

       If  a call to the strtok() function cannot find a byte that does not occur in the delimiter string, it returns the null pointer.  If a call
       to the strtok() function cannot find the terminating byte that does occur in the delimiter string, the current token extends to the end	of
       the string and subsequent calls to strtok() will return the null pointer.

       If  the	delimiters  used in the string change from one set of characters to another within the string, the application program can set the
       second parameter, s2, to different strings from call to call.

       The implementation behaves as though no function calls the strtok() function.

       The strtok_r() function is the reentrant version of strtok().  Upon successful completion, the strtok_r() function stores the saved pointer
       in  *savept.   If  the s1 parameter is a null pointer, the strtok_r() function uses the saved pointer in *savept to start searching for the
       next token.  In the initial call to strtok_r(), the *savept must be the null pointer.

NOTES

       [POSIX]	The strtok() function is not supported for multithreaded applications.	Instead, its reentrant equivalent, strtok_r(),	should	be
       used with multiple threads.

EXAMPLES

       The following example demonstrates how to split a string into tokens.

       #include <string.h> #include <locale.h> #include <stdio.h> #define LENGTH 40

       main() {
	  char	 string1[LENGTH], delimiters[LENGTH];
	  char	 *pstr ;
	  int	counter;

	  (void)setlocale(LC_ALL, "");
	  printf("Enter the string to be searched: ");
	  if (fgets(string1, LENGTH, stdin) != NULL) {
	     printf("Enter the delimiter(s): ");
	     if (fgets(delimiters, LENGTH, stdin) != NULL) {

		if ((pstr = strtok(string1, delimiters ))
		    != NULL) {
		   /* pstr points to the first token */
		   printf("Token 1 is %s
", pstr);
		   counter = 2;
		   while ((pstr = strtok((char *)NULL, delimiters ))
			  != NULL) {
		      printf("Token %d is %s
", counter, pstr);
		      counter++;
		   }
		}
	     }
	  } }

RETURN VALUES

       Upon  successful  completion,  the  strtok() and strtok_r() functions return a pointer to the first byte of the parsed token in the string.
       When there is no token in the string, a null pointer is returned.

RELATED INFORMATION

       Functions: string(3), wcstok(3), wcstok_r(3)

       Standards: standards(5) delim off

																	 strtok(3)