string(9F)						   Kernel Functions for Drivers 						string(9F)

NAME

       string,	strcasecmp,  strncasecmp,  strncat,  strlcat, strchr, strrchr, strcmp, strncmp, strcpy, strncpy, strlcpy, strfree, strspn, strdup,
       ddi_strdup, strlen, strnlen - string operations

SYNOPSIS

       #include <sys/ddi.h>

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

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

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

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

       char *strchr(const char *str, int chr);

       char *strrchr(const char *str, int chr);

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

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

       char *strcpy(char * dst, const char * src);

       char *strncpy(char * dst, const char * src, size_t n);

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

       void strfree(char *s);

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

       char *strdup(const char *s1);

       char *ddi_strdup(const char *s1, int flag);

       size_t strlen(const char *s);

       size_t strnlen(const char *s, size_t n);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI).

DESCRIPTION

       The arguments s, s1, and s2 point to strings (arrays of characters terminated by a null character).  The  strcat(),  strncat(),	strlcat(),
       strcpy(),  strncpy(), strlcpy(), and strfree() functions all alter their first argument. Additionally, the strcpy() function does not check
       for overflow of the array.

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

   strncat(), strlcat()
       The  strncat()  function  appends  at most n characters of string s2, including the terminating null character, to the end of string s1. It
       returns a pointer to the null-terminated result. The initial character of  s2 overrides the null character at the end  of  s1.  If  copying
       takes place between objects that overlap, the behavior of strncat()and strlcat() is undefined.

       The  strlcat()  function  appends  at most  (dstsize-strlen(dst)-1) characters 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  dst-
       size   bytes   when   strlcat()	 is  called,  the  string  pointed  to	by  dst  will  not  be	changed.  The  function  returns  min{dst-
       size,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
       occur  in the string. The strrchr() function returns a pointer to the last occurrence of c. The null character terminating a string is con-
       sidered 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 following 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-ter-
       minated if the length of s2 is n or more. Each function returns s1.  If copying takes place between objects that overlap, the  behavior	of
       strcpy(), strncpy(), and strlcpy() is undefined.

       The  strlcpy() function copies  at most dstsize-1 characters (dstsize being the	size of the  string buffer dst) from src to dst,  truncat-
       ing 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;

   strfree()
       The strfree() function frees the memory associated with the string pointed to by  s.   This  memory  pointed  to  by  s	must  be  of  size
       strlen(s)+1, and must have been allocated (either directly or indirectly) by kmem_alloc(9F) or kmem_zalloc(9F).

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

   strdup(), ddi_strdup()
       The ddi_strdup() function returns a pointer to a new string that is a duplicate of the string pointed to by s1. The returned pointer can be
       passed to strfree() or kmem_free(9F). The space for the new string  is  obtained  using	kmem_alloc().  flag  can  be  either  KM_SLEEP	or
       KM_NOSLEEP,  and  determines  whether  the  caller  can	sleep  for  memory.  KM_SLEEP allocations may sleep but are guaranteed to succeed.
       KM_NOSLEEP allocations are guaranteed not to sleep but may fail (return NULL) if no memory is currently available.

       The strdup() function behaves the same as the ddi_strdup() when called with the KM_SLEEP flag. This means that  strdup()  can  sleep  until
       memory is available and will always succeed.

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

       The  strnlen()  function  returns the smaller of n or the number of bytes in s, not including the terminating null character. The strnlen()
       function never examines more than n bytes of the string pointed to by s.

CONTEXT

       The strdup() and ddi_strdup() functions can be called from user or kernel context.

       The ddi_strdup() function can be called from interrupt context only if the KM_NOSLEEP flag is set.

       All the other string manipulation functions can be called from user, interrupt, or kernel context.

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+

SEE ALSO

       string(3C), attributes(5), bcopy(9F), ddi_copyin(9F), kmem_alloc(9F)

       Writing Device Drivers

NOTES

       If copying takes place between objects that overlap, the behavior of strlcat(), strncat(), strcpy(), strlcpy(), and strncpy() is undefined.

SunOS 5.11							    27 Feb 2009 							string(9F)