strcat 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268
  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, 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. .IR malloc (2)
  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. All these routines have portable C implementations in
  246. .BR /sys/src/libc/port .
  247. Many also have machine-dependent assembly language
  248. implementations in
  249. .BR /sys/src/libc/$objtype .
  250. .SH SEE ALSO
  251. .IR memory (2),
  252. .IR rune (2),
  253. .IR runestrcat (2)
  254. .SH BUGS
  255. These routines know nothing about
  256. .SM UTF.
  257. Use the routines in
  258. .IR rune (2)
  259. as appropriate.
  260. Note, however, that the definition of
  261. .SM UTF
  262. guarantees that
  263. .I strcmp
  264. compares
  265. .SM UTF
  266. strings correctly.
  267. .PP
  268. The outcome of overlapping moves varies among implementations.