Manual Pages for UNIX Operating System command usage for man wcstring

Standard C Library Functions                         wcstring(3C)



NAME
     wcstring, wcscasecmp, wcsncasecmp, wcscat,  wscat,  wcsncat,
     wsncat,  wcscmp,  wscmp,  wcsncmp,  wsncmp,  wcscpy,  wscpy,
     wcsncpy, wsncpy, wcpcpy,  wcpncpy,  wcsdup,  wcslen,  wslen,
     wcsnlen,  wcschr,  wschr,  wcsrchr, wsrchr, windex, wrindex,
     wcspbrk, wspbrk, wcswcs,  wcsspn,  wsspn,  wcscspn,  wscspn,
     wcstok, wstok - wide-character string operations

SYNOPSIS
     #include 

     int wcscasecmp(const wchar_t *ws1, const wchar_t *ws2);


     int wcsncasecmp(const wchar_t ws1*, const wchar_t ws2*, size_t n);


     wchar_t *wcscat(wchar_t *ws1, const wchar_t *ws2);


     wchar_t *wcsncat(wchar_t *restrict ws1, const wchar_t *restrict ws2,
          size_t n);


     int wcscmp(const wchar_t *ws1, const wchar_t *ws2);


     int wcsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);


     wchar_t *wcscpy(wchar_t *ws1, const wchar_t *ws2);


     wchar_t *wcscpy(wchar_t *restrict ws1, const wchar_t *restrict ws2);


     wchar_t *wcsncpy(wchar_t *restrict ws1, const wchar_t *restrict ws2,
          size_t n);


     wchar_t *wcpncpy(wchar_t restrict *ws1, const wchar_t *restrict ws2,
          size_t n);


     wchar_t *wcsdup(const wchar_t *s);


     size_t wcslen(const wchar_t *ws);


     size_t wcsnlen(const wchar_t *ws, size_t maxlen);




SunOS 5.11          Last change: 11 Oct 2010                    1






Standard C Library Functions                         wcstring(3C)



     wchar_t *wcschr(const wchar_t *ws, wchar_t wc);


     wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc);


     wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);


     wchar_t *wcswcs(const wchar_t *ws1, const wchar_t *ws2);


     size_t wcsspn(const wchar_t *ws1, const wchar_t *ws2);


     size_t wcscspn(const wchar_t *ws1, const wchar_t *ws2);


  XPG4, SUS, SUSv2, SUSv3
     wchar_t *wcstok(wchar_t *restrict ws1, const wchar_t *restrict ws2);


  Default and other standards
     wchar_t *wcstok(wchar_t *ws1, const wchar_t *ws2, wchar_t **ptr);


     #include 

     wchar_t *wscat(wchar_t *ws1, const wchar_t *ws2);


     wchar_t *wsncat(wchar_t *ws1, const wchar_t *ws2, size_t n);


     int wscmp(const wchar_t *ws1, const wchar_t *ws2);


     int wsncmp(const wchar_t *ws1, const wchar_t *ws2, size_t n);


     wchar_t *wscpy(wchar_t *ws1, const wchar_t *ws2);


     wchar_t *wsncpy(wchar_t *ws1, const wchar_t *ws2, size_t n);


     size_t wslen(const wchar_t *ws);


     wchar_t *wschr(const wchar_t *ws, wchat_t wc);





SunOS 5.11          Last change: 11 Oct 2010                    2






Standard C Library Functions                         wcstring(3C)



     wchar_t *wsrchr(const wchar_t *ws, wchat_t wc);


     wchar_t *wspbrk(const wchar_t *ws1, const wchar_t *ws2);


     size_t wsspn(const wchar_t *ws1, const wchar_t *ws2);


     size_t wscspn(const wchar_t *ws1, const wchar_t *ws2);


     wchar_t *wstok(wchar_t *ws1, const wchar_t *ws2);


     wchar_t *windex(const wchar_t *ws, wchar_t wc);


     wchar_t *wrindex(const wchar_t *ws, wchar_t wc);


  ISO C++
     #include 

     const wchar_t *wcschr(const wchar_t *ws, wchar_t wc);


     const wchar_t *wcspbrk(const wchar_t *ws1, const wchar_t *ws2);


     const wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc);


     #include 

     wchar_t *std::wcschr(wchar_t *ws, wchar_t wc);


     wchar_t *std::wcspbrk(wchar_t *ws1, const wchar_t *ws2);


     wchar_t *std::wcsrchr(wchar_t *ws, wchar_t wc);


DESCRIPTION
     These functions operate on wide-character strings terminated
     by  wchar_t  NULL  characters.  During appending or copying,
     these routines do not check for an overflow condition of the
     receiving  string.  In the following, ws, ws1, and ws2 point
     to wide-character strings terminated by a wchar_t NULL.





SunOS 5.11          Last change: 11 Oct 2010                    3






Standard C Library Functions                         wcstring(3C)



  wcscasecmp(), wcsncasecmp()
     The wcscasecmp() function is the  wide-character  equivalent
     of  the  strcasecmp(3C)  function.  It  compares  the  wide-
     character string pointed to by  ws1  to  the  wide-character
     string  pointed  to  by  ws2,  ignoring case differences. It
     returns 0 if the wide-character strings at ws1 is  equal  to
     ws2  except  for  case  differences.  It  returns a positive
     integer if ws1 is greater than ws2 and a negative integer if
     ws1 is smaller than ws2, ignoring case.


     The wcsncasecmp() function is the wide-character  equivalent
     of  the  strncasecmp(3C)  function.  It  compares  at most n
     wide-characters from the wide-character string pointed to by
     ws1  to  the  wide-character string pointed to by ws2, while
     ignoring differences in case. It  returns  0  if  the  wide-
     character  strings  at  ws1  and  ws2,  truncated to at most
     length n, are equal except for case distinctions. It returns
     a  positive integer if truncated ws1 is greater than ws2 and
     a negative integer if truncated ws1  is  smaller  than  ws2,
     ignoring case.

  wcscat(), wscat()
     The wcscat() and wscat() functions  append  a  copy  of  the
     wide-character  string pointed to by ws2 (including the ter-
     minating null wide-character code) to the end of  the  wide-
     character  string  pointed  to  by  ws1.  The  initial wide-
     character code of ws2  overwrites  the  null  wide-character
     code  at  the  end  of  ws1.  If copying takes place between
     objects that overlap, the behavior is undefined. Both  func-
     tions  return s1; no return value is reserved to indicate an
     error.

  wcsncat(), wsncat()
     The wcsncat() and wsncat() functions append not more than  n
     wide-character  codes  (a null wide-character code and wide-
     character codes that follow it are not  appended)  from  the
     array  pointed  to  by  ws2 to the end of the wide-character
     string pointed to by ws1. The initial wide-character code of
     ws2  overwrites  the  null wide-character code at the end of
     ws1.  A  terminating  null  wide-character  code  is  always
     appended to the result. Both functions return ws1; no return
     value is reserved to indicate an error.

  wcscmp(), wscmp()
     The  wcscmp()  and  wscmp()  functions  compare  the   wide-
     character  string  pointed  to  by ws1 to the wide-character
     string pointed to by ws2. The  sign  of  a  non-zero  return
     value  is  determined  by the sign of the difference between
     the values of the first pair of  wide-character  codes  that
     differ  in the objects being compared. Upon completion, both
     functions return an integer greater than, equal to, or  less



SunOS 5.11          Last change: 11 Oct 2010                    4






Standard C Library Functions                         wcstring(3C)



     than zero, if the wide-character string pointed to by ws1 is
     greater than, equal to,  or  less  than  the  wide-character
     string pointed to by ws2.

  wcsncmp(), wsncmp()
     The wcsncmp() and wsncmp() functions compare not more than n
     wide-character  codes  (wide-character  codes  that follow a
     null wide character code are not compared)  from  the  array
     pointed  to  by ws1 to the array pointed to by ws2. The sign
     of a non-zero return value is determined by the sign of  the
     difference  between  the  values  of the first pair of wide-
     character codes that differ in the objects  being  compared.
     Upon successful completion, both functions return an integer
     greater than, equal to, or less than zero, if  the  possibly
     null-terminated  array  pointed  to  by ws1 is greater than,
     equal to, or less than the  possibly  null-terminated  array
     pointed to by ws2.

  wcscpy(), wscpy(), wcpcpy()
     The wcscpy(),  wscpy(),  and  wcpcpy()  functions  copy  the
     wide-character  string pointed to by ws2 (including the ter-
     minating null wide-character code) into the array pointed to
     by ws1. If copying takes place between objects that overlap,
     the behavior is undefined.


     The wcscpy() and wscpy() functions return ws1. The  wcpcpy()
     function  returns  a  pointer  to the terminating null wide-
     character code copied into ws1.

  wcsncpy(), wsncpy(), wcpncpy()
     The wcsncpy(), wsncpy(), and wcpncpy()  functions  copy  not
     more  than n wide-character codes (wide-character codes that
     follow a null wide character code are not copied)  from  the
     array  pointed  to by ws2 to the array pointed to by ws1. If
     copying  takes  place  between  objects  that  overlap,  the
     behavior is undefined.


     If the array pointed to by ws2 is  a  wide-character  string
     that  is  shorter  than  n  wide-character codes, null wide-
     character codes are  appended  to  the  copy  in  the  array
     pointed  to by ws1, until a total n wide-character codes are
     written. The wcsncpy() and wsncpy()  functions  return  ws1.
     The  wcpncpy()  function  returns a pointer to the last wide
     character written.

  wcsdup()
     The wcsdup() function is the  wide-character  equivalent  of
     the  strdup(3C)  function.  It  returns  a  pointer to a new
     wide-character string whose initial contents is a  duplicate
     of the wide-character string pointed to by s. Memory for the



SunOS 5.11          Last change: 11 Oct 2010                    5






Standard C Library Functions                         wcstring(3C)



     new wide-character string is allocated with  malloc(3C)  and
     can  be  freed  with  a  call to free(3C). A null pointer is
     returned and errno set to ENOMEM if  there  is  insufficient
     memory available for the duplicate string.

  wcslen(), wslen(), wcsnlen()
     The wcslen() and wslen() functions  compute  the  number  of
     wide-character  codes  in the wide-character string to which
     ws points, not including the terminating null wide-character
     code.  Both functions return ws; no return value is reserved
     to indicate an error.


     The  wcsnlen()  is  the  wide-character  equivalent  of  the
     strnlen(3C)   function.  It  returns  the  number  of  wide-
     characters in the string pointed to by ws, not including the
     terminating  null  wide-character  code  but at most maxlen,
     while never looking beyond the first maxlen  characters.  It
     returns  maxlen  if  there  is  no  terminating  null  wide-
     character  code  among  the  first  maxlen  wide  characters
     pointed to by ws.

  wcschr(), wschr()
     The  wcschr()  and  wschr()  functions  locate   the   first
     occurrence  of wc in the wide-character string pointed to by
     ws. The value of wc must be a character representable  as  a
     type wchar_t and must be a wide-character code corresponding
     to a valid character in the current locale. The  terminating
     null  wide-character  code  is  considered to be part of the
     wide-character  string.  Upon  completion,  both   functions
     return  a  pointer  to  the  wide-character  code, or a null
     pointer if the wide-character code is not found.

  wcsrchr(), wsrchr()
     The  wcsrchr()  and  wsrchr()  functions  locate  the   last
     occurrence  of wc in the wide-character string pointed to by
     ws. The value of wc must be a character representable  as  a
     type wchar_t and must be a wide-character code corresponding
     to a valid character in the current locale. The  terminating
     null  wide-character  code  is  considered to be part of the
     wide-character  string.  Upon  successful  completion,  both
     functions  return a pointer to the wide-character code, or a
     null pointer if wc does  not  occur  in  the  wide-character
     string.

  windex(), wrindex()
     The windex() and wrindex()  functions  behave  the  same  as
     wschr() and wsrchr(), respectively.

  wcspbrk(), wspbrk()
     The  wcspbrk()  and  wspbrk()  functions  locate  the  first
     occurrence in the wide character string pointed to by ws1 of



SunOS 5.11          Last change: 11 Oct 2010                    6






Standard C Library Functions                         wcstring(3C)



     any  wide-character  code  from  the  wide-character  string
     pointed  to by ws2. Upon successful completion, the function
     returns a pointer to the  wide-character  code,  or  a  null
     pointer if no wide-character code from ws2 occurs in ws1.

  wcswcs()
     The wcswcs() function locates the first  occurrence  in  the
     wide-character  string  pointed to by ws1 of the sequence of
     wide-character codes (excluding the terminating  null  wide-
     character  code)  in the wide-character string pointed to by
     ws2. Upon successful  completion,  the  function  returns  a
     pointer  to  the  located  wide-character  string, or a null
     pointer if the wide-character string is not  found.  If  ws2
     points  to  a  wide-character  string  with zero length, the
     function returns ws1.

  wcsspn(), wsspn()
     The wcsspn() and wsspn() functions compute the length of the
     maximum initial segment of the wide-character string pointed
     to by ws1 which consists entirely  of  wide-character  codes
     from the wide-character string pointed to by ws2. Both func-
     tions return the length ws1; no return value is reserved  to
     indicate an error.

  wcscspn(), wscspn()
     The wcscspn() and wscspn() functions compute the  length  of
     the  maximum  initial  segment  of the wide-character string
     pointed to by ws1 which consists entirely of  wide-character
     codes  not from the wide-character string pointed to by ws2.
     Both functions return the length of the initial substring of
     ws1; no return value is reserved to indicate an error.

  wcstok(), wstok()
     A sequence of calls to the wcstok()  and  wstok()  functions
     break  the  wide-character  string  pointed to by ws1 into a
     sequence of tokens, each of which is delimited  by  a  wide-
     character  code from the wide-character string pointed to by
     ws2.

  Default and other standards
     The third  argument  points  to  a  caller-provided  wchar_t
     pointer  into which the wcstok() function stores information
     necessary  for  it  to  continue  scanning  the  same  wide-
     character  string.  This  argument is not available with the
     XPG4 and SUS versions of wcstok(), nor is it available  with
     the wstok() function.  See standards(5).


     The first call in the sequence has ws1 as  its  first  argu-
     ment,  and is followed by calls with a null pointer as their
     first argument. The separator string pointed to by  ws2  may
     be different from call to call.



SunOS 5.11          Last change: 11 Oct 2010                    7






Standard C Library Functions                         wcstring(3C)



     The first call in the sequence searches  the  wide-character
     string  pointed  to by ws1 for the first wide-character code
     that is  not  contained  in  the  current  separator  string
     pointed  to by ws2. If no such wide-character code is found,
     then there  are  no  tokens  in  the  wide-character  string
     pointed  to  by  ws1, and wcstok() and wstok() return a null
     pointer. If such a wide-character code is found, it  is  the
     start of the first token.


     The wcstok() and wstok() functions  then  search  from  that
     point  for  a  wide-character  code that is contained in the
     current separator string. If no such wide-character code  is
     found,  the  current  token  extends to the end of the wide-
     character string pointed to by ws1, and subsequent  searches
     for  a  token  will  return  a null pointer. If such a wide-
     character code is found, it is overwritten by  a  null  wide
     character,  which terminates the current token. The wcstok()
     and wstok() functions save a pointer to the following  wide-
     character  code, from which the next search for a token will
     start.


     Each subsequent call, with a null pointer as  the  value  of
     the  first argument, starts searching from the saved pointer
     and behaves as described above.


     Upon successful completion, both functions return a  pointer
     to  the  first wide-character code of a token. Otherwise, if
     there is no token, a null pointer is returned.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:




















SunOS 5.11          Last change: 11 Oct 2010                    8






Standard C Library Functions                         wcstring(3C)



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe                     |
    |_____________________________|_____________________________|
    | Standard                    | See below.                  |
    |_____________________________|_____________________________|



     For  wcscat(),  wcsncat(),  wcscmp(),  wcsncmp(),  wcscpy(),
     wcsncpy(),   wcslen(),   wcschr(),   wcsrchr(),   wcspbrk(),
     wcswcs(),  wcsspn(),  wcscspn(),  and  wcstok(),  see  stan-
     dards(5).

SEE ALSO
     malloc(3C), string(3C),  wcswidth(3C),  wcwidth(3C),  attri-
     butes(5), standards(5)

































SunOS 5.11          Last change: 11 Oct 2010                    9