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

FreeBSD Manual Pages

  
 
  

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

NAME
       string, strcasecmp, strncasecmp,	strcat,	strncat, strlcat, strchr, str-
       rchr, strcmp,  strncmp,	strcpy,	 strncpy,  strlcpy,  strcspn,  strspn,
       strdup, strlen, strpbrk,	strstr,	strtok,	strtok_r - string operations

SYNOPSIS
       #include	<strings.h>

       int strcasecmp(const char *s1, const char *s2);

       int strncasecmp(const char *s1, const char *s2, size_t n);

       #include	<string.h>

       char *strcat(char *restrict s1, const char *restrict s2);

       char *strncat(char *restrict s1,	const char *restrict s2, size_t	n);

       size_t strlcat(char *dst, const char *src, size_t dstsize);

       char *strchr(const char *s, int c);

       char *strrchr(const char	*s, int	c);

       int strcmp(const	char *s1, const	char *s2);

       int strncmp(const char *s1, const char *s2, size_t n);

       char *strcpy(char *restrict s1, const char *restrict s2);

       char *strncpy(char *restrict s1,	const char *restrict s2, size_t	n);

       size_t strlcpy(char *dst, const char *src, size_t dstsize);

       size_t strcspn(const char *s1, const char *s2);

       size_t strspn(const char	*s1, const char	*s2);

       char *strdup(const char *s1);

       size_t strlen(const char	*s);

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

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

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

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

   ISO C++
       #include	<string.h>

       const char *strchr(const	char *s, int c);

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

       const char *strrchr(const char *s, int c);

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

       #include	<cstring>

       char *std::strchr(char *s, int c);

       char *std::strpbrk(char *s1, const char *s2);

       char *std::strrchr(char *s, int c);

       char *std::strstr(char *s1, const char *s2);

       The arguments s,	s1, and	s2 point to strings (arrays of characters ter-
       minated by a null character). The strcat(), strncat(), strlcat(),  str-
       cpy(), strncpy(), strlcpy(), strtok(), and strtok_r() functions all al-
       ter their first argument. These functions do not	check for overflow  of
       the array pointed to by the first argument.

   strcasecmp(), strncasecmp()
       The  strcasecmp() and strncasecmp() functions are case-insensitive ver-
       sions of	 strcmp() and strncmp()	respectively, described	 below.	  They
       assume the ASCII	character set and ignore differences in	case when com-
       paring lower and	upper case characters.

   strcat(), strncat(),	strlcat()
       The strcat() function appends a copy of string s2, including the	termi-
       nating  null character, to the end of string s1.	The strncat() function
       appends at most n characters. Each returns a pointer to the null-termi-
       nated result. The initial character of  s2 overrides the	null character
       at the end of s1.

       The strlcat() function appends  at most	(dstsize-strlen(dst)-1)	 char-
       acters  of  src	to  dst	(dstsize being the  size of the	 string	buffer
       dst). If	the string pointed to by dst contains a	null-terminated	string
       that  fits  into	 dstsize  bytes	 when  strlcat() is called, the	string
       pointed to by dst will be a null-terminated string that fits in dstsize
       bytes (including	the terminating	null character)	when it	completes, and
       the initial character of	src will override the null character  at   the
       end  of	dst.  If  the  string pointed to by dst	is longer than dstsize
       bytes when strlcat() is called, the string pointed to by	dst  will  not
       be  changed. The	function returns min{dstsize,strlen(dst)}+strlen(src).
       Buffer overflow can be checked as  follows:

       if (strlcat(dst,	src, dstsize) >= dstsize)
	       return -1;

   strchr(), strrchr()
       The strchr() function returns a pointer to the first  occurrence	 of  c
       (converted to a	char) in string	s, or a	null pointer if	c does not oc-
       cur in the string. The strrchr()	function returns a pointer to the last
       occurrence  of c. The null character terminating	a string is considered
       to be part of the string.

   strcmp(), strncmp()
       The strcmp() function compares two strings byte-by-byte,	 according  to
       the  ordering of	your machine's character set.  The function returns an
       integer greater than, equal to, or less than 0, if  the string  pointed
       to  by s1 is greater than, equal	to, or less than the string pointed to
       by s2 respectively. The sign of a non-zero return value	is  determined
       by  the	sign of	the difference between the values of the first pair of
       bytes that differ in the	strings	being compared.	The strncmp() function
       makes the same comparison but looks at a	maximum	of n bytes. Bytes fol-
       lowing a	null byte are not compared.

   strcpy(), strncpy(),	strlcpy()
       The strcpy() function copies string s2 to s1, including the terminating
       null  character,	stopping after the null	character has been copied. The
       strncpy() function copies exactly n bytes, truncating s2	or adding null
       characters  to  s1 if necessary.	The result will	not be null-terminated
       if the length of	s2 is n	or more. Each function returns s1.

       The strlcpy() function copies  at most  dstsize-1  characters  (dstsize
       being the  size of the  string buffer dst) from src to dst,  truncating
       src if necessary.  The  result is always	null-terminated. The  function
       returns strlen(src). Buffer overflow can	be checked as  follows:

       if (strlcpy(dst,	src, dstsize) >= dstsize)
	       return -1;

   strcspn(), strspn()
       The  strcspn()  function	 returns  the length of	the initial segment of
       string s1 that consists entirely	of characters not from string s2.  The
       strspn()	 function  returns the length of the initial segment of	string
       s1 that consists	entirely of characters from string s2.

   strdup()
       The strdup() function returns a pointer to a new	string that is	a  du-
       plicate	of  the	 string	pointed	to by  s1. The returned	pointer	can be
       passed to free(). The space for the new string is obtained  using  mal-
       loc(3C).	 If  the  new  string cannot be	created, a null	pointer	is re-
       turned and errno	may be set to ENOMEM  to  indicate  that  the  storage
       space available is insufficient.

   strlen()
       The  strlen()  function returns the number of bytes in s, not including
       the terminating null character.

   strpbrk()
       The strpbrk() function 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.

   strstr()
       The strstr() function locates the first occurrence  of  the  string  s2
       (excluding  the	terminating null character) in string s1 and returns a
       pointer to the located string, or a null	pointer	if the string  is  not
       found.  If  s2 points to	a string with zero length (that	is, the	string
       ""), the	function returns  s1.

   strtok()
       A sequence of calls to strtok() breaks the string pointed to by s1 into
       a  sequence  of	tokens,	 each of which is delimited by a byte from the
       string pointed to by s2.	The first call in the sequence has s1  as  its
       first  argument,	 and is	followed by calls with a null pointer as their
       first argument. The separator string pointed to by s2 can be  different
       from call to call.

       The first call in the sequence searches the string pointed to by	s1 for
       the first byte that is not contained in the  current  separator	string
       pointed to by s2. If no such byte is found, then	there are no tokens in
       the string pointed to by	s1 and strtok()	returns	 a  null  pointer.  If
       such a byte is found, it	is the start of	the first token.

       The  strtok() function then searches from there for a byte that is con-
       tained in the current separator string. If no such byte is  found,  the
       current	token  extends	to the end of the string pointed to by s1, and
       subsequent searches for a token return a	null pointer. If such  a  byte
       is  found, it is	overwritten by a null byte that	terminates the current
       token. The strtok() function saves a pointer to the following  byte  in
       thread-specific data, from which	the next search	for a token starts.

       Each subsequent call, with a null pointer as the	value of the first ar-
       gument, starts searching	from the saved	pointer	 and  behaves  as  de-
       scribed above.

       See Example 1, 2, and 3 in the  section for examples of strtok()	usage.

   strtok_r()
       The  strtok_r()	function  considers the	null-terminated	string s1 as a
       sequence	of zero	or more	text tokens separated by spans of one or  more
       characters from the separator string s2.	The argument lasts points to a
       user-provided pointer which points to stored information	necessary  for
       strtok_r() to continue scanning the same	string.

       In the first call to strtok_r(),	s1 points to a null-terminated string,
       s2 to a null-terminated string of separator characters, and  the	 value
       pointed	to  by	lasts  is  ignored.  The strtok_r() function returns a
       pointer to the first character of the first token, writes a null	 char-
       acter into s1 immediately following the returned	token, and updates the
       pointer to which	lasts points.

       In subsequent calls, s1 is a null pointer and lasts is  unchanged  from
       the  previous call so that subsequent calls move	through	the string s1,
       returning successive tokens  until  no  tokens  remain.	The  separator
       string  s2 can be different from	call to	call. When no token remains in
       s, a null pointer is returned.

       See Example 3 in	the  section for an example of strtok_r() usage.

       Example 1: Search for word separators.

       The following example searches for tokens separated  by	space  charac-
       ters.

       #include	<string.h>
       ...
       char *token;
       char *line = "LINE TO BE	SEPARATED";
       char *search = "	";

       /* Token	will point to "LINE". */
       token = strtok(line, search);

       /* Token	will point to "TO". */
       token = strtok(NULL, search);

       Example 2: Break	a Line.

       The  following  example	uses strtok to break a line into two character
       strings separated by any	combination of SPACEs, TABs, or	NEWLINEs.

       #include	<string.h>
       ...
       struct element {
	      char *key;
	      char *data;
       };
       ...
       char line[LINE_MAX];
       char *key, *data;
       ...
       key = strtok(line, " \n");
       data = strtok(NULL, " \n");

       Example 3: Search for tokens.

       The following example uses both strtok()	and strtok_r() to  search  for
       tokens  separated  by one or more characters from the string pointed to
       by the second argument, "/".

       #define __EXTENSIONS__
       #include	<stdio.h>
       #include	<string.h>

       int
       main() {
	       char *buf="5/90/45";
	       char *token;
	       char *lasts;

	       printf("tokenizing \"%s\" with strtok():\n", buf);
	       if ((token = strtok(buf,	"/")) != NULL) {
		       printf("token = "%s\"\n", token);
		       while ((token = strtok(NULL, "/")) != NULL) {
			       printf("token = \"%s\"\n", token);
		       }
	       }

	       buf = "//5//90//45//";
	       printf("\ntokenizing \"%s\" with	strtok_r():\n",	buf);
	       if ((token = strtok_r(buf, "/", &lasts))	!= NULL) {
		       printf("token = \"%s\"\n", token);
		       while ((token = strtok_r(NULL, "/", &lasts)) != NULL) {
			       printf("token = \"%s\"\n", token);
		       }
	       }
       }

       When compiled and run, this example produces the	following output:

       tokenizing "5/90/45" with strtok():
       token = "5"
       token = "90"
       token = "45"

       tokenizing "//5//90//45//" with strtok_r():
       token = "5"
       token = "90"
       token = "45"

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |See below.		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See below.		   |
       +-----------------------------+-----------------------------+

       The strlcat() and strlcpy() functions are Stable.  The remaining	 func-
       tions are Standard.

       The  strtok()  and  strdup() functions are MT-Safe. The remaining func-
       tions are Async-Signal-Safe.

       malloc(3C), setlocale(3C), strxfrm(3C), attributes(5), standards(5)

       When compiling multithreaded applications, the _REENTRANT flag must  be
       defined	on  the	 compile line. This flag should	only be	used in	multi-
       threaded	applications.

       A single-threaded application can gain access  to  strtok_r()  only  by
       defining	 __EXTENSIONS__	 or  by	 defining  _POSIX_C_SOURCE  to a value
       greater than or equal to	199506L.

       All of these functions assume the default locale	``C.''	For  some  lo-
       cales,  strxfrm(3C)  should  be	applied	to the strings before they are
       passed to the functions.

       The strtok() function is	safe to	use in multithreaded applications  be-
       cause it	saves its internal state in a thread-specific data area.  How-
       ever, its use is	discouraged, even  for	single-threaded	 applications.
       The strtok_r() function should be used instead.

				  17 Feb 2004			    string(3C)

NAME | SYNOPSIS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=string&sektion=3c&manpath=SunOS+5.10>

home | help