strcat.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.