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