wcstok(3)						     Library Functions Manual							 wcstok(3)

NAME

       wcstok, wcstok_r - Split wide-character strings into tokens

LIBRARY

       Standard C Library (libc)

SYNOPSIS

       wchar_t *wcstok(
	       wchar_t *ws1,
	       const wchar_t *ws2),
	       wchar_t **savept);

       This prototype conforms to both ISO C and XSH Issue 5 and is strongly recommended for new applications.	The wcstok() function supported in
       compilation environments for XSH versions earlier than XSH Issue 5 does not include the savept parameter, which is required for	threadsafe
       operation.   The following proprietary prototype is the threadsafe interface that was supported on Tru64 UNIX versions prior to Version 4.0
       and is supported only to provide backward compatibility for applications written before the ISO C and XSH5 threadsafe prototype was  avail-
       able.

       wchar_t *wcstok_r(
	       wchar_t *ws1,
	       const wchar_t *ws2),
	       wchar_t **savept);

STANDARDS

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

       wcstok(): XSH5.0

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

PARAMETERS

       Contains  a  pointer  to  the  wide-character  string to be searched.  Contains a pointer to the string of wide-character token delimiters.
       Identifies the location of the wide character where the search for tokens should be started in the next call. The savept parameter contains
       a pointer to a variable that contains a pointer to the wide character where scanning begins.

DESCRIPTION

       The  wcstok()  function splits the wide-character string pointed to by the ws1 parameter into a sequence of tokens, each of which is delim-
       ited by a wide character from the wide-character string pointed to by the ws2 parameter.

       Usually, the wcstok() function is called repeatedly to extract the tokens in a wide-character string. On the first  call  to  the  wcstok()
       function,  the  application sets the ws1 parameter to point to the input wide-character string. The function returns a pointer to the first
       token.

       The application program calls the function again with the ws1 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 wcstok() with the ws1 parameter set to the null pointer until all the
       tokens in the string have been returned.

       On the initial call to wcstok(), the function first searches the wide-character string pointed to by the ws1 parameter to locate the  first
       wide  character	that  does  not occur in the wide-character delimiter string pointed to by the ws2 parameter.  If such a wide character is
       found, it is the start of the first token.  The wcstok() function then searches from there for a wide character	that  does  occur  in  the
       delimiter string. If such a wide-character delimiter is found, wcstok() overwrites it with a null wide character, which terminates the cur-
       rent token. The wcstok() function saves a pointer to the wide character following the null wide character and  returns  a  pointer  to  the
       start of the token.

       In  subsequent  calls  to  wcstok(), where ws1 is set to a null pointer, the function starts at the saved pointer and searches for the next
       wide character that does not occur in the wide-character delimiter string pointed to by the ws2 parameter.  If such  a  wide  character	is
       found, it is the start of the new token.  The wcstok() function then searches from there for a wide character that does occur in the delim-
       iter string. If such a wide-character delimiter is found, wcstok() overwrites it with a null  wide  character,  which  terminates  the  new
       token.  The wcstok() function saves a pointer to the wide character following the null wide character and returns a pointer to the start of
       the new token. It stores the saved pointer in the *savept parameter as well as internally.  On calls where  the	s1  parameter  is  a  null
       pointer,  the function uses the saved pointer in *savept to start searching for the next token. Applications that require threadsafe opera-
       tion must use a wcstok() interface that includes the savept parameter.

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

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

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

EXAMPLES

       The following example splits a wide-character string into tokens:

       #include <wchar.h> #include <locale.h> #include <stdio.h> #define WLENGTH 40

       main() {
	  wchar_t WCString1[WLENGTH], delimiters[WLENGTH];
	  wchar_t * pwcs;
	  int	counter;

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

		if ((pwcs = wcstok(WCString1, delimiters ))  != NULL) {
		   /* pwcs points to the first token */
		   printf("Token 1 is %S
", pwcs);
		   counter = 2;
		   while ((pwcs = wcstok((wchar_t * )NULL, delimiters ))  != NULL) {
		      printf("Token %d is %S
", counter, pwcs);
		      counter++;
		   }
		}
	     }
	  } }

RETURN VALUES

       On  successful  completion,  the  wcstok() function returns a pointer to the first wide character of a token. A null pointer is returned if
       there is no token.

       The wcstok() function also sets the pointer *savept to the wide character from which the search for the next token starts,  or  to  a  null
       pointer if there is none.

RELATED INFORMATION

       Functions: strtok(3), wcspbrk(3), wcsspn(3), wcstod(3), wcstol(3), wcstoul(3)

       Standards: standards(5) delim off

																	 wcstok(3)