Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
string(3C)							    string(3C)

       string:	strcasecmp(),  strcat(),  strchr(),  strcmp(), strcoll(), str-
       cpy(),  strcspn(),  strdup(),   strlen(),   strncasecmp(),   strncat(),
       strncmp(),   strncpy(),	 strpbrk(),  strrchr(),	 strrstr(),  strspn(),
       strstr(), strtok(), strtok_r(), strxfrm(), index(), rindex() -  charac-
       ter string operations

       All  functions  except and are declared in both headers,	so only	one of
       the two headers needs to	be included.

       The functions and are declared only in They  are	 provided  solely  for
       portability of BSD applications,	and are	not recommended	for new	appli-
       cations where portability is important.	For portable applications, use
       and instead.

       Arguments  s1,  s2, and s point to strings (arrays of characters	termi-
       nated by	a null byte).

       Definitions for all these functions, the	type and the constant are pro-
       vided in	the header.

       Appends a copy of string
		      s2  to  the  end	of  string s1.	appends	a maximum of n
		      characters.  It copies fewer if s2  is  shorter  than  n
		      characters.   Each  returns a pointer to the null-termi-
		      nated result (the	value of s1).

       Compares	its arguments and returns an integer less than,
		      equal to,	or greater than	zero, depending	on whether  s1
		      is  lexicographically  less  than,  equal	to, or greater
		      than s2.	The comparison of corresponding	characters  is
		      done  as if the type of the characters were Null pointer
		      values for s1 and	s2 are treated the same	as pointers to
		      empty strings.  makes the	same comparison	but examines a
		      maximum of n characters (n less than or  equal  to  zero
		      yields  equality).  and are identical in function	to and
		      respectively,  but  characters  are   folded   by	  (see
		      conv(3C))	 prior	to  comparison.	  The returned lexico-
		      graphic difference reflects the folding to lowercase.

       Copies string  s2 to s1,	stopping after the null	byte has been  copied.
		      copies  exactly  n  characters,  truncating s2 or	adding
		      null bytes to s1 if necessary, until a total of  n  have
		      been  written.  The result is not	null-terminated	if the
		      length of	s2 is n	or more.  Each	function  returns  s1.
		      Note that	should not be used to copy n bytes of an arbi-
		      trary structure.	If that	structure contains a null byte
		      anywhere,	 copies	 fewer than n bytes from the source to
		      the destination and fills	the remainder with null	bytes.
		      Use  the function	(see memory(3C)) to copy arbitrary bi-
		      nary data.

       Returns a pointer to a new string which is a
		      duplicate	of the string to which s1 points.   The	 space
		      for  the	new string is obtained using the function (see

       Returns the number of characters	in
		      s, not including the terminating null byte.

       Returns a pointer to the	first (last) occurrence	of character
		      c	in string s, or	a null pointer if c does not occur  in
		      the  string.  The	null byte terminating a	string is con-
		      sidered to be part of the	string.	 is identical  to  and
		      is provided solely for portability of BSD	applications.

       Returns a pointer to the	first occurrence in string
		      s1 of any	character from string s2, or a null pointer if
		      no character from	s2 exists in s1.

       Returns the length of the maximum initial segment of string
		      s1, which	consists  entirely  of	characters  from  (not
		      from) string s2.

       Returns a pointer to the	first (last) occurrence	of string
		      s2  in string s1,	or a NULL pointer if s2	does not occur
		      in the string.  If s2 points to a	string of zero length,
		      returns s1.

       Considers the string
		      s1  to consist of	a sequence of zero or more text	tokens
		      separated	by spans of one	or more	 characters  from  the
		      separator	 string	 s2.   The  first call (with a nonnull
		      pointer s1 specified) returns a  pointer	to  the	 first
		      character	 of  the  first	 token,	and writes a null byte
		      into s1 immediately following the	returned  token.   The
		      function	keeps  track  of its position in the string s1
		      between separate calls, so that  subsequent  calls  made
		      with  the	first argument a null pointer work through the
		      string immediately following that	token.	 In  this  way
		      subsequent calls work through the	string s1 until	no to-
		      kens remain.  The	separator string s2 can	 be  different
		      from  call to call.  When	no token remains in s1,	a null
		      pointer is returned.

       is identical to
		      except that it expects to	be passed  the	address	 of  a
		      character	string pointer as the third argument.  It will
		      use this argument	to keep	track of the current  position
		      in  the  string being searched.  It returns a pointer to
		      the current token	in the string or a NULL	value if there
		      are no more tokens.

       Returns an integer greater than,	equal to, or less than zero,
		      according	 to  whether  the  string  pointed to by s1 is
		      greater than, equal to, or less than the string  pointed
		      to  by  s2.   The	 comparison is based on	strings	inter-
		      preted as	appropriate to the program's locale  (see  Lo-
		      cale below).  In the ``C'' locale	works like

       Transforms the string pointed to	by
		      s2  and  places  the  resulting  string  into  the array
		      pointed to by s1.	 The transformation is	such  that  if
		      the  function  is	applied	to two transformed strings, it
		      returns a	value greater than, equal  to,	or  less  than
		      zero,  corresponding  to	the result of the function ap-
		      plied to the same	two original strings.  No more than  n
		      bytes  are  placed  into the resulting string, including
		      the terminating  null  character.	  If  the  transformed
		      string  fits  in no more than n bytes, the length	of the
		      resulting	string is returned (not	including  the	termi-
		      nating  null  character).	 Otherwise the return value is
		      the number of bytes that the s1 string would occupy (not
		      including	 the terminating null character), and the con-
		      tents of the array are indeterminate.

       has better performance with respect to in cases where a given string is
       compared	 to other strings only a few times, or where the strings to be
       compared	are long but a difference in the strings that determines their
       relative	ordering usually comes among the first few characters.	offers
       better performance in, for example, a sorting routine where a number of
       strings are each	transformed just once and the transformed versions are
       compared	against	each other many	times.

       The category determines the interpretation  of  the  bytes  within  the
       string  arguments to the	and functions as single	and/or multibyte char-
       acters.	It also	determines the case conversions	to be done for the and

       The  category  determines  the collation	ordering used by the and func-

   International Code Set Support
       Single- and multibyte character code sets are  supported	 for  the  and
       functions.  All other functions support only single-byte	character code

       The following sample piece of  code  finds  the	tokens,	 separated  by
       blanks,	that  are in the string	s (assuming that there are at most to-

	      int i = 0;
	      char *s, *last, *tok[MAXTOK];
	      tok[0] = strtok_r(s, " ",	&last);
	      while (tok[++i] =	strtok_r(NULL, " ", &last));

       The functions and alter the contents of the array to which  s1  points.
       They do not check for overflow of the array.

       Null pointers for destination strings cause undefined behavior.

       Character  movement  is	performed differently in different implementa-
       tions, so moves involving overlapping source  and  destination  strings
       may yield surprises.

       The  transformed	 string	produced by for	a language using an 8-bit code
       set is usually at least twice as	large as the original string  and  may
       be  as  much  four times	as large (ordinary characters occupy two bytes
       each in the transformed string, 1-to-2 characters  four	bytes,	2-to-1
       characters  two	bytes  per original pair, and don't-care characters no
       bytes).	Each character of a multibyte code set (Asian languages) occu-
       pies three bytes	in the transformed string.

       For  functions  and results are undefined if the	languages specified by
       the and categories use different	code sets.

       Users of	should also note that the  prototype  of  this	function  will
       change  in  the next release for	conformance with the new POSIX Threads

       was developed by	the University of California, Berkeley,	AT&T, OSF, and

       conv(3C), malloc(3C), memory(3C), setlocale(3C),	thread_safety(5).



Want to link to this manual page? Use this URL:

home | help