1string(9F)               Kernel Functions for Drivers               string(9F)
2
3
4

NAME

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

SYNOPSIS

11       #include <sys/ddi.h>
12
13       int strcasecmp(const char *s1, const char *s2);
14
15
16       int strncasecmp(const char *s1, const char *s2, size_t n);
17
18
19       char *strncat(char * s1, const char * s2, size_t n);
20
21
22       size_t strlcat(char *dst, const char *src, size_t dstsize);
23
24
25       char *strchr(const char *str, int chr);
26
27
28       char *strrchr(const char *str, int chr);
29
30
31       int strcmp(const char *s1, const char *s2);
32
33
34       int strncmp(const char *s1, const char *s2, size_t n);
35
36
37       char *strcpy(char * dst, const char * src);
38
39
40       char *strncpy(char * dst, const char * src, size_t n);
41
42
43       size_t strlcpy(char *dst, const char *src, size_t dstsize);
44
45
46       void strfree(char *s);
47
48
49       size_t strspn(const char *s1, const char *s2);
50
51
52       char *strdup(const char *s1);
53
54
55       char *ddi_strdup(const char *s1, int flag);
56
57
58       size_t strlen(const char *s);
59
60
61       size_t strnlen(const char *s, size_t n);
62
63

INTERFACE LEVEL

65       Solaris DDI specific (Solaris DDI).
66

DESCRIPTION

68       The arguments s, s1, and s2 point to strings (arrays of characters ter‐
69       minated by a null character). The strcat(), strncat(), strlcat(),  str‐
70       cpy(),  strncpy(),  strlcpy(),  and strfree() functions all alter their
71       first argument. Additionally, the strcpy() function does not check  for
72       overflow of the array.
73
74   strcasecmp(), strncasecmp()
75       The  strcasecmp() and strncasecmp() functions are case-insensitive ver‐
76       sions of  strcmp() and strncmp() respectively, described  below.   They
77       assume the ASCII character set and ignore differences in case when com‐
78       paring lower and upper case characters.
79
80   strncat(), strlcat()
81       The strncat() function appends at  most  n  characters  of  string  s2,
82       including  the  terminating null character, to the end of string s1. It
83       returns a pointer to the null-terminated result. The initial  character
84       of   s2 overrides the null character at the end of s1. If copying takes
85       place between objects that overlap, the behavior of strncat()and  strl‐
86       cat() is undefined.
87
88
89       The  strlcat() function appends  at most  (dstsize-strlen(dst)-1) char‐
90       acters of src to dst (dstsize being the  size  of  the   string  buffer
91       dst). If the string pointed to by dst contains a null-terminated string
92       that fits into dstsize bytes  when  strlcat()  is  called,  the  string
93       pointed to by dst will be a null-terminated string that fits in dstsize
94       bytes (including the terminating null character) when it completes, and
95       the  initial  character of src will override the null character at  the
96       end of dst. If the string pointed to by  dst  is  longer  than  dstsize
97       bytes  when  strlcat() is called, the string pointed to by dst will not
98       be changed. The function returns  min{dstsize,strlen(dst)}+strlen(src).
99       Buffer overflow can be checked as  follows:
100
101         if (strlcat(dst, src, dstsize) >= dstsize)
102                 return −1;
103
104
105   strchr(), strrchr()
106       The  strchr()  function  returns a pointer to the first occurrence of c
107       (converted to a  char) in string s, or a null pointer  if  c  does  not
108       occur  in  the  string. The strrchr() function returns a pointer to the
109       last occurrence of c. The null character terminating a string  is  con‐
110       sidered to be part of the string.
111
112   strcmp(), strncmp()
113       The  strcmp()  function compares two strings byte-by-byte, according to
114       the ordering of your machine's character set.  The function returns  an
115       integer  greater than, equal to, or less than 0, if  the string pointed
116       to by s1 is greater than, equal to, or less than the string pointed  to
117       by  s2  respectively. The sign of a non-zero return value is determined
118       by the sign of the difference between the values of the first  pair  of
119       bytes that differ in the strings being compared. The strncmp() function
120       makes the same comparison but looks at a maximum of n bytes. Bytes fol‐
121       lowing a null byte are not compared.
122
123   strcpy(), strncpy(), strlcpy()
124       The strcpy() function copies string s2 to s1, including the terminating
125       null character, stopping after the null character has been copied.  The
126       strncpy() function copies exactly n bytes, truncating s2 or adding null
127       characters to s1 if necessary. The result will not  be  null-terminated
128       if the length of s2 is n or more. Each function returns s1.  If copying
129       takes place between objects that overlap,  the  behavior  of  strcpy(),
130       strncpy(), and strlcpy() is undefined.
131
132
133       The  strlcpy()  function  copies  at most dstsize−1 characters (dstsize
134       being the  size of the  string buffer dst) from src to dst,  truncating
135       src  if necessary.  The  result is always null-terminated. The function
136       returns strlen(src). Buffer overflow can be checked as  follows:
137
138         if (strlcpy(dst, src, dstsize) >= dstsize)
139                 return −1;
140
141
142   strfree()
143       The strfree() function frees the  memory  associated  with  the  string
144       pointed  to  by  s.   This  memory  pointed  to  by  s  must be of size
145       strlen(s)+1, and must have been allocated  (either  directly  or  indi‐
146       rectly) by kmem_alloc(9F) or kmem_zalloc(9F).
147
148   strspn()
149       The  strspn()  function  returns  the  length of the initial segment of
150       string s1 that consists entirely of characters from string s2.
151
152   strdup(), ddi_strdup()
153       The ddi_strdup() function returns a pointer to a new string that  is  a
154       duplicate  of  the string pointed to by s1. The returned pointer can be
155       passed to strfree() or kmem_free(9F). The space for the new  string  is
156       obtained using kmem_alloc(). flag can be either KM_SLEEP or KM_NOSLEEP,
157       and determines whether the caller can sleep for memory. KM_SLEEP  allo‐
158       cations may sleep but are guaranteed to succeed. KM_NOSLEEP allocations
159       are guaranteed not to sleep but may fail (return NULL) if no memory  is
160       currently available.
161
162
163       The  strdup() function behaves the same as the ddi_strdup() when called
164       with the KM_SLEEP flag. This means that strdup() can sleep until memory
165       is available and will always succeed.
166
167   strlen(), strnlen()
168       The  strlen()  function returns the number of bytes in s, not including
169       the terminating null character.
170
171
172       The strnlen() function returns the smaller of n or the number of  bytes
173       in s, not including the terminating null character. The strnlen() func‐
174       tion never examines more than n bytes of the string pointed to by s.
175

CONTEXT

177       The strdup() and ddi_strdup() functions can be called from user or ker‐
178       nel context.
179
180
181       The  ddi_strdup() function can be called from interrupt context only if
182       the KM_NOSLEEP flag is set.
183
184
185       All the other string manipulation functions can be  called  from  user,
186       interrupt, or kernel context.
187

ATTRIBUTES

189       See attributes(5) for descriptions of the following attributes:
190
191
192
193
194       ┌─────────────────────────────┬─────────────────────────────┐
195       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
196       ├─────────────────────────────┼─────────────────────────────┤
197       │Interface Stability          │Committed                    │
198       └─────────────────────────────┴─────────────────────────────┘
199

SEE ALSO

201       string(3C), attributes(5), bcopy(9F), ddi_copyin(9F), kmem_alloc(9F)
202
203
204       Writing Device Drivers
205

NOTES

207       If  copying  takes  place between objects that overlap, the behavior of
208       strlcat(), strncat(), strcpy(), strlcpy(), and strncpy() is undefined.
209
210
211
212SunOS 5.11                        27 Feb 2009                       string(9F)
Impressum