sys/man/2/strcat

   1 .TH STRCAT 2
   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, int 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, int c)
  42 .PP
  43 .B
  44 char*   strrchr(char *s, int 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 nil if
 165 .I c
 166 does not occur in the string.
 167 The null byte terminating a string is considered to
 168 be part of the string.
 169 .PP
 170 .I Strpbrk
 171 returns a pointer to the first occurrence in string
 172 .I s1
 173 of any byte from string
 174 .IR s2 ,
 175 nil if no byte from
 176 .I s2
 177 exists in
 178 .IR s1 .
 179 .PP
 180 .I Strspn
 181 .RI ( strcspn )
 182 returns the length of the initial segment of string
 183 .I s1
 184 which consists entirely of bytes from (not from) string
 185 .IR s2 .
 186 .PP
 187 .I Strtok
 188 considers the string
 189 .I s1
 190 to consist of a sequence of zero or more text tokens separated
 191 by spans of one or more bytes from the separator string
 192 .IR s2 .
 193 The first call, with pointer
 194 .I s1
 195 specified, returns a pointer to the first byte of the first
 196 token, and will have written a
 197 null byte into
 198 .I s1
 199 immediately following the returned token.
 200 The function
 201 keeps track of its position in the string
 202 between separate calls; subsequent calls,
 203 signified by
 204 .I s1
 205 being nil, will work through the string
 206 .I s1
 207 immediately following that token.
 208 The separator string
 209 .I s2
 210 may be different from call to call.
 211 When no token remains in
 212 .IR s1 ,
 213 nil is returned.
 214 .PP
 215 .I Strdup
 216 returns a pointer to a distinct copy of the null-terminated string
 217 .I s
 218 in space obtained from
 219 .IR malloc (2)
 220 or nil if no space can be obtained.
 221 .PP
 222 .I Strstr
 223 returns a pointer to the first occurrence of
 224 .I s2
 225 as a substring of
 226 .IR s1 ,
 227 or nil if there is none.
 228 If
 229 .I s2
 230 is the null string,
 231 .I strstr
 232 returns
 233 .IR s1 .
 234 .I Cistrstr
 235 operates analogously, but ignores ASCII case differences when comparing strings.
 236 .SH SOURCE
 237 All these routines have portable C implementations in
 238 .BR /sys/src/libc/port .
 239 Many also have machine-dependent assembly language
 240 implementations in
 241 .BR /sys/src/libc/$objtype .
 242 .SH SEE ALSO
 243 .IR memory (2),
 244 .IR rune (2),
 245 .IR runestrcat (2),
 246 .IR string (2)
 247 .SH BUGS
 248 These routines know nothing about
 249 .SM UTF.
 250 Use the routines in
 251 .IR rune (2)
 252 as appropriate.
 253 Note, however, that the definition of
 254 .SM UTF
 255 guarantees that
 256 .I strcmp
 257 compares
 258 .SM UTF
 259 strings correctly.
 260 .PP
 261 The outcome of overlapping moves varies among implementations.