1 cfa37a7b 2004-04-10 devnull .TH STRCAT 3
  2 cfa37a7b 2004-04-10 devnull .SH NAME
  3 cfa37a7b 2004-04-10 devnull strcat, strncat, strcmp, strncmp, cistrcmp, cistrncmp, strcpy, strncpy, strecpy, strlen, strchr, strrchr, strpbrk, strspn, strcspn, strtok, strdup, strstr, cistrstr \- string operations
  4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
  5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
  6 cfa37a7b 2004-04-10 devnull .br
  7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
  8 cfa37a7b 2004-04-10 devnull .PP
  9 cfa37a7b 2004-04-10 devnull .ta \w'\fLchar* \fP'u
 10 cfa37a7b 2004-04-10 devnull .B
 11 cfa37a7b 2004-04-10 devnull char*	strcat(char *s1, char *s2)
 12 cfa37a7b 2004-04-10 devnull .PP
 13 cfa37a7b 2004-04-10 devnull .B
 14 cfa37a7b 2004-04-10 devnull char*	strncat(char *s1, char *s2, long n)
 15 cfa37a7b 2004-04-10 devnull .PP
 16 cfa37a7b 2004-04-10 devnull .B
 17 cfa37a7b 2004-04-10 devnull int	strcmp(char *s1, char *s2)
 18 cfa37a7b 2004-04-10 devnull .PP
 19 cfa37a7b 2004-04-10 devnull .B
 20 cfa37a7b 2004-04-10 devnull int	strncmp(char *s1, char *s2, long n)
 21 cfa37a7b 2004-04-10 devnull .PP
 22 cfa37a7b 2004-04-10 devnull .B
 23 cfa37a7b 2004-04-10 devnull int	cistrcmp(char *s1, char *s2)
 24 cfa37a7b 2004-04-10 devnull .PP
 25 cfa37a7b 2004-04-10 devnull .B
 26 cfa37a7b 2004-04-10 devnull int	cistrncmp(char *s1, char *s2, long n)
 27 cfa37a7b 2004-04-10 devnull .PP
 28 cfa37a7b 2004-04-10 devnull .B
 29 cfa37a7b 2004-04-10 devnull char*	strcpy(char *s1, char *s2)
 30 cfa37a7b 2004-04-10 devnull .PP
 31 cfa37a7b 2004-04-10 devnull .B
 32 cfa37a7b 2004-04-10 devnull char*	strecpy(char *s1, char *es1, char *s2)
 33 cfa37a7b 2004-04-10 devnull .PP
 34 cfa37a7b 2004-04-10 devnull .B
 35 cfa37a7b 2004-04-10 devnull char*	strncpy(char *s1, char *s2, long n)
 36 cfa37a7b 2004-04-10 devnull .PP
 37 cfa37a7b 2004-04-10 devnull .B
 38 cfa37a7b 2004-04-10 devnull long	strlen(char *s)
 39 cfa37a7b 2004-04-10 devnull .PP
 40 cfa37a7b 2004-04-10 devnull .B
 41 cfa37a7b 2004-04-10 devnull char*	strchr(char *s, char c)
 42 cfa37a7b 2004-04-10 devnull .PP
 43 cfa37a7b 2004-04-10 devnull .B
 44 cfa37a7b 2004-04-10 devnull char*	strrchr(char *s, char c)
 45 cfa37a7b 2004-04-10 devnull .PP
 46 cfa37a7b 2004-04-10 devnull .B
 47 cfa37a7b 2004-04-10 devnull char*	strpbrk(char *s1, char *s2)
 48 cfa37a7b 2004-04-10 devnull .PP
 49 cfa37a7b 2004-04-10 devnull .B
 50 cfa37a7b 2004-04-10 devnull long	strspn(char *s1, char *s2)
 51 cfa37a7b 2004-04-10 devnull .PP
 52 cfa37a7b 2004-04-10 devnull .B
 53 cfa37a7b 2004-04-10 devnull long	strcspn(char *s1, char *s2)
 54 cfa37a7b 2004-04-10 devnull .PP
 55 cfa37a7b 2004-04-10 devnull .B
 56 cfa37a7b 2004-04-10 devnull char*	strtok(char *s1, char *s2)
 57 cfa37a7b 2004-04-10 devnull .PP
 58 cfa37a7b 2004-04-10 devnull .B
 59 cfa37a7b 2004-04-10 devnull char*	strdup(char *s)
 60 cfa37a7b 2004-04-10 devnull .PP
 61 cfa37a7b 2004-04-10 devnull .B
 62 cfa37a7b 2004-04-10 devnull char*	strstr(char *s1, char *s2)
 63 cfa37a7b 2004-04-10 devnull .PP
 64 cfa37a7b 2004-04-10 devnull .B
 65 cfa37a7b 2004-04-10 devnull char*	cistrstr(char *s1, char *s2)
 66 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
 67 cfa37a7b 2004-04-10 devnull The arguments
 68 cfa37a7b 2004-04-10 devnull .I s1, s2
 69 cfa37a7b 2004-04-10 devnull and
 70 cfa37a7b 2004-04-10 devnull .I s
 71 cfa37a7b 2004-04-10 devnull point to null-terminated strings.
 72 cfa37a7b 2004-04-10 devnull The functions
 73 cfa37a7b 2004-04-10 devnull .IR strcat ,
 74 cfa37a7b 2004-04-10 devnull .IR strncat ,
 75 cfa37a7b 2004-04-10 devnull .IR strcpy ,
 76 cfa37a7b 2004-04-10 devnull .IR strecpy ,
 77 cfa37a7b 2004-04-10 devnull and
 78 cfa37a7b 2004-04-10 devnull .I strncpy
 79 cfa37a7b 2004-04-10 devnull all alter
 80 cfa37a7b 2004-04-10 devnull .IR s1 .
 81 cfa37a7b 2004-04-10 devnull .I Strcat
 82 cfa37a7b 2004-04-10 devnull and
 83 cfa37a7b 2004-04-10 devnull .I strcpy
 84 cfa37a7b 2004-04-10 devnull do not check for overflow of
 85 cfa37a7b 2004-04-10 devnull the array pointed to by
 86 cfa37a7b 2004-04-10 devnull .IR s1 .
 87 cfa37a7b 2004-04-10 devnull .PP
 88 cfa37a7b 2004-04-10 devnull .I Strcat
 89 cfa37a7b 2004-04-10 devnull appends a copy of string
 90 cfa37a7b 2004-04-10 devnull .I s2
 91 cfa37a7b 2004-04-10 devnull to the end of string
 92 cfa37a7b 2004-04-10 devnull .IR s1 .
 93 cfa37a7b 2004-04-10 devnull .I Strncat
 94 cfa37a7b 2004-04-10 devnull appends at most
 95 cfa37a7b 2004-04-10 devnull .I n
 96 cfa37a7b 2004-04-10 devnull bytes.
 97 cfa37a7b 2004-04-10 devnull Each returns a pointer to the null-terminated result.
 98 cfa37a7b 2004-04-10 devnull .PP
 99 cfa37a7b 2004-04-10 devnull .I Strcmp
100 cfa37a7b 2004-04-10 devnull compares its arguments and returns an integer
101 cfa37a7b 2004-04-10 devnull less than, equal to, or greater than 0,
102 cfa37a7b 2004-04-10 devnull according as
103 cfa37a7b 2004-04-10 devnull .I s1
104 cfa37a7b 2004-04-10 devnull is lexicographically less than, equal to, or
105 cfa37a7b 2004-04-10 devnull greater than
106 cfa37a7b 2004-04-10 devnull .IR s2 .
107 cfa37a7b 2004-04-10 devnull .I Strncmp
108 cfa37a7b 2004-04-10 devnull makes the same comparison but examines at most
109 cfa37a7b 2004-04-10 devnull .I n
110 cfa37a7b 2004-04-10 devnull bytes.
111 cfa37a7b 2004-04-10 devnull .I Cistrcmp
112 cfa37a7b 2004-04-10 devnull and
113 cfa37a7b 2004-04-10 devnull .I cistrncmp
114 cfa37a7b 2004-04-10 devnull ignore ASCII case distinctions when comparing strings.
115 cfa37a7b 2004-04-10 devnull The comparisons are made with unsigned bytes.
116 cfa37a7b 2004-04-10 devnull .PP
117 cfa37a7b 2004-04-10 devnull .I Strcpy
118 cfa37a7b 2004-04-10 devnull copies string
119 cfa37a7b 2004-04-10 devnull .I s2
120 cfa37a7b 2004-04-10 devnull to
121 cfa37a7b 2004-04-10 devnull .IR s1 ,
122 cfa37a7b 2004-04-10 devnull stopping after the null byte has been copied.
123 cfa37a7b 2004-04-10 devnull .I Strncpy
124 cfa37a7b 2004-04-10 devnull copies exactly
125 cfa37a7b 2004-04-10 devnull .I n
126 cfa37a7b 2004-04-10 devnull bytes,
127 cfa37a7b 2004-04-10 devnull truncating
128 cfa37a7b 2004-04-10 devnull .I s2
129 cfa37a7b 2004-04-10 devnull or adding
130 cfa37a7b 2004-04-10 devnull null bytes to
131 cfa37a7b 2004-04-10 devnull .I s1
132 cfa37a7b 2004-04-10 devnull if necessary.
133 cfa37a7b 2004-04-10 devnull The result will not be null-terminated if the length
134 cfa37a7b 2004-04-10 devnull of
135 cfa37a7b 2004-04-10 devnull .I s2
136 cfa37a7b 2004-04-10 devnull is
137 cfa37a7b 2004-04-10 devnull .I n
138 cfa37a7b 2004-04-10 devnull or more.
139 cfa37a7b 2004-04-10 devnull Each function returns
140 cfa37a7b 2004-04-10 devnull .IR s1 .
141 cfa37a7b 2004-04-10 devnull .PP
142 cfa37a7b 2004-04-10 devnull .I Strecpy
143 cfa37a7b 2004-04-10 devnull copies bytes until a null byte has been copied, but writes no bytes beyond
144 cfa37a7b 2004-04-10 devnull .IR es1 .
145 cfa37a7b 2004-04-10 devnull If any bytes are copied,
146 cfa37a7b 2004-04-10 devnull .I s1
147 cfa37a7b 2004-04-10 devnull is terminated by a null byte, and a pointer to that byte is returned.
148 cfa37a7b 2004-04-10 devnull Otherwise, the original
149 cfa37a7b 2004-04-10 devnull .I s1
150 cfa37a7b 2004-04-10 devnull is returned.
151 cfa37a7b 2004-04-10 devnull .PP
152 cfa37a7b 2004-04-10 devnull .I Strlen
153 cfa37a7b 2004-04-10 devnull returns the number of bytes in
154 cfa37a7b 2004-04-10 devnull .IR s ,
155 cfa37a7b 2004-04-10 devnull not including the terminating null byte.
156 cfa37a7b 2004-04-10 devnull .PP
157 cfa37a7b 2004-04-10 devnull .I Strchr
158 cfa37a7b 2004-04-10 devnull .RI ( strrchr )
159 cfa37a7b 2004-04-10 devnull returns a pointer to the first (last)
160 cfa37a7b 2004-04-10 devnull occurrence of byte
161 cfa37a7b 2004-04-10 devnull .I c
162 cfa37a7b 2004-04-10 devnull in string
163 cfa37a7b 2004-04-10 devnull .IR s ,
164 cfa37a7b 2004-04-10 devnull or
165 cfa37a7b 2004-04-10 devnull .L 0
166 cfa37a7b 2004-04-10 devnull if
167 cfa37a7b 2004-04-10 devnull .I c
168 cfa37a7b 2004-04-10 devnull does not occur in the string.
169 cfa37a7b 2004-04-10 devnull The null byte terminating a string is considered to
170 cfa37a7b 2004-04-10 devnull be part of the string.
171 cfa37a7b 2004-04-10 devnull .PP
172 cfa37a7b 2004-04-10 devnull .I Strpbrk
173 cfa37a7b 2004-04-10 devnull returns a pointer to the first occurrence in string
174 cfa37a7b 2004-04-10 devnull .I s1
175 cfa37a7b 2004-04-10 devnull of any byte from string
176 cfa37a7b 2004-04-10 devnull .IR s2 ,
177 cfa37a7b 2004-04-10 devnull .L 0
178 cfa37a7b 2004-04-10 devnull if no byte from
179 cfa37a7b 2004-04-10 devnull .I s2
180 cfa37a7b 2004-04-10 devnull exists in
181 cfa37a7b 2004-04-10 devnull .IR s1 .
182 cfa37a7b 2004-04-10 devnull .PP
183 cfa37a7b 2004-04-10 devnull .I Strspn
184 cfa37a7b 2004-04-10 devnull .RI ( strcspn )
185 cfa37a7b 2004-04-10 devnull returns the length of the initial segment of string
186 cfa37a7b 2004-04-10 devnull .I s1
187 cfa37a7b 2004-04-10 devnull which consists entirely of bytes from (not from) string
188 cfa37a7b 2004-04-10 devnull .IR s2 .
189 cfa37a7b 2004-04-10 devnull .PP
190 cfa37a7b 2004-04-10 devnull .I Strtok
191 cfa37a7b 2004-04-10 devnull considers the string
192 cfa37a7b 2004-04-10 devnull .I s1
193 cfa37a7b 2004-04-10 devnull to consist of a sequence of zero or more text tokens separated
194 cfa37a7b 2004-04-10 devnull by spans of one or more bytes from the separator string
195 cfa37a7b 2004-04-10 devnull .IR s2 .
196 cfa37a7b 2004-04-10 devnull The first call, with pointer
197 cfa37a7b 2004-04-10 devnull .I s1
198 cfa37a7b 2004-04-10 devnull specified, returns a pointer to the first byte of the first
199 cfa37a7b 2004-04-10 devnull token, and will have written a
200 cfa37a7b 2004-04-10 devnull null byte into
201 cfa37a7b 2004-04-10 devnull .I s1
202 cfa37a7b 2004-04-10 devnull immediately following the returned token.
203 cfa37a7b 2004-04-10 devnull The function
204 cfa37a7b 2004-04-10 devnull keeps track of its position in the string
205 cfa37a7b 2004-04-10 devnull between separate calls; subsequent calls,
206 cfa37a7b 2004-04-10 devnull signified by
207 cfa37a7b 2004-04-10 devnull .I s1
208 cfa37a7b 2004-04-10 devnull being
209 cfa37a7b 2004-04-10 devnull .LR 0 ,
210 cfa37a7b 2004-04-10 devnull will work through the string
211 cfa37a7b 2004-04-10 devnull .I s1
212 cfa37a7b 2004-04-10 devnull immediately following that token.
213 cfa37a7b 2004-04-10 devnull The separator string
214 cfa37a7b 2004-04-10 devnull .I s2
215 cfa37a7b 2004-04-10 devnull may be different from call to call.
216 cfa37a7b 2004-04-10 devnull When no token remains in
217 cfa37a7b 2004-04-10 devnull .IR s1 ,
218 cfa37a7b 2004-04-10 devnull .L 0
219 cfa37a7b 2004-04-10 devnull is returned.
220 cfa37a7b 2004-04-10 devnull .PP
221 cfa37a7b 2004-04-10 devnull .I Strdup
222 cfa37a7b 2004-04-10 devnull returns a pointer to a distinct copy of the null-terminated string
223 cfa37a7b 2004-04-10 devnull .I s
224 cfa37a7b 2004-04-10 devnull in space obtained from
225 d32deab1 2020-08-16 rsc .MR malloc (3)
226 cfa37a7b 2004-04-10 devnull or
227 cfa37a7b 2004-04-10 devnull .L 0
228 cfa37a7b 2004-04-10 devnull if no space can be obtained.
229 cfa37a7b 2004-04-10 devnull .PP
230 cfa37a7b 2004-04-10 devnull .I Strstr
231 cfa37a7b 2004-04-10 devnull returns a pointer to the first occurrence of
232 cfa37a7b 2004-04-10 devnull .I s2
233 cfa37a7b 2004-04-10 devnull as a substring of
234 cfa37a7b 2004-04-10 devnull .IR s1 ,
235 cfa37a7b 2004-04-10 devnull or 0 if there is none.
236 cfa37a7b 2004-04-10 devnull If
237 cfa37a7b 2004-04-10 devnull .I s2
238 cfa37a7b 2004-04-10 devnull is the null string,
239 cfa37a7b 2004-04-10 devnull .I strstr
240 cfa37a7b 2004-04-10 devnull returns
241 cfa37a7b 2004-04-10 devnull .IR s1 .
242 cfa37a7b 2004-04-10 devnull .I Cistrstr
243 cfa37a7b 2004-04-10 devnull operates analogously, but ignores ASCII case differences when comparing strings.
244 cfa37a7b 2004-04-10 devnull .SH SOURCE
245 c3674de4 2005-01-11 devnull .B \*9/src/lib9
246 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
247 d32deab1 2020-08-16 rsc .MR memory (3) ,
248 d32deab1 2020-08-16 rsc .MR rune (3) ,
249 d32deab1 2020-08-16 rsc .MR runestrcat (3)
250 cfa37a7b 2004-04-10 devnull .SH BUGS
251 cfa37a7b 2004-04-10 devnull These routines know nothing about
252 cfa37a7b 2004-04-10 devnull .SM UTF.
253 cfa37a7b 2004-04-10 devnull Use the routines in
254 d32deab1 2020-08-16 rsc .MR rune (3)
255 cfa37a7b 2004-04-10 devnull as appropriate.
256 cfa37a7b 2004-04-10 devnull Note, however, that the definition of
257 cfa37a7b 2004-04-10 devnull .SM UTF
258 cfa37a7b 2004-04-10 devnull guarantees that
259 cfa37a7b 2004-04-10 devnull .I strcmp
260 cfa37a7b 2004-04-10 devnull compares
261 cfa37a7b 2004-04-10 devnull .SM UTF
262 cfa37a7b 2004-04-10 devnull strings correctly.
263 cfa37a7b 2004-04-10 devnull .PP
264 cfa37a7b 2004-04-10 devnull The outcome of overlapping moves varies among implementations.