string.3 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255
  1. .TH STRING 3 "$Revision$"
  2. .ad
  3. .SH NAME
  4. strcpy, strncpy, strcat, strncat, strcmp, strncmp,
  5. strlen, strindex, strrindex, strzero, str2bts,
  6. long2str, str2long,
  7. btscpy, btscat, btscmp, btszero, bts2str \- operations on and
  8. conversions between strings and row of bytes
  9. .SH SYNOPSIS
  10. .nf
  11. .B char *strcpy(s1, s2)
  12. .B char *s1, *s2;
  13. .PP
  14. .B char *strncpy(s1, s2, n)
  15. .B char *s1, *s2;
  16. .PP
  17. .B char *strcat(s1, s2)
  18. .B char *s1, *s2;
  19. .PP
  20. .B char *strncat(s1, s2, n)
  21. .B char *s1, *s2;
  22. .PP
  23. .B int strcmp(s1, s2)
  24. .B char *s1, *s2;
  25. .PP
  26. .B int strncmp(s1, s2, n)
  27. .B char *s1, *s2;
  28. .PP
  29. .B int strlen(s)
  30. .B char *s;
  31. .PP
  32. .B char *strindex(s, c)
  33. .B char *s, c;
  34. .PP
  35. .B char *strrindex(s, c)
  36. .B char *s, c;
  37. .PP
  38. .B char *strzero(s)
  39. .B char *s;
  40. .PP
  41. .B char *str2bts(s, b, pn)
  42. .B char *s, *b;
  43. .B int *pn;
  44. .PP
  45. .B char *long2str(l, base)
  46. .B long l;
  47. .B int base;
  48. .PP
  49. .B long str2long(s, base)
  50. .B char *s;
  51. .B int base;
  52. .PP
  53. .B char *btscpy(b1, b2, n)
  54. .B char *b1, *b2;
  55. .B int n;
  56. .PP
  57. .B char *btscat(b1, n1, b2, n2)
  58. .B char *b1, *b2;
  59. .B int n1, n2;
  60. .PP
  61. .B int btscmp(b1, n1, b2, n2)
  62. .B char *b1, *b2;
  63. .B int n1, n2;
  64. .PP
  65. .B char *btszero(b, n)
  66. .B char *b;
  67. .B int n;
  68. .PP
  69. .B char *bts2str(b, n, s)
  70. .B char *b, *s;
  71. .B int n;
  72. .fi
  73. .SH DESCRIPTION
  74. The
  75. .IR str *
  76. functions operate on null-terminated strings.
  77. The
  78. .IR bts *
  79. functions operate on variable-length rows of bytes,
  80. regardless of null bytes.
  81. Neither of these functions check for overflow of any receiving area.
  82. .PP
  83. .I Strcpy
  84. copies string
  85. .I s2
  86. to
  87. .I s1,
  88. stopping after the null character has been moved.
  89. .I Strncpy
  90. copies exactly
  91. .I n
  92. characters,
  93. truncating or null-padding
  94. .I s2;
  95. the target may not be null-terminated if the length
  96. of
  97. .I s2
  98. is
  99. .I n
  100. or more.
  101. Both return
  102. .IR s1 .
  103. .PP
  104. .I Strcat
  105. appends a copy of string
  106. .I s2
  107. to the end of string
  108. .IR s1 .
  109. .I Strncat
  110. copies at most
  111. .I n
  112. characters.
  113. Both return a pointer to the null-terminated result
  114. .IR s1 .
  115. .PP
  116. .I Strcmp
  117. compares its arguments and returns an integer
  118. greater than, equal to, or less than 0, if
  119. .I s1
  120. is lexicographically greater than, equal to, or
  121. less than
  122. .IR s2 ,
  123. respectively.
  124. .I Strncmp
  125. makes the same comparison but checks at most
  126. .I n
  127. characters.
  128. .PP
  129. .I Strlen
  130. returns the number of characters before the null-character.
  131. .IR s .
  132. .PP
  133. .I Strindex
  134. .RI ( strrindex )
  135. returns a pointer to the first (last)
  136. occurrence of character
  137. .I c
  138. in string
  139. .I s,
  140. or zero if
  141. .I c
  142. does not occur in
  143. .IR s .
  144. .PP
  145. .I Strzero
  146. turns
  147. .I s
  148. into a null string.
  149. .PP
  150. .I Bts2str
  151. turns a row of
  152. .I n
  153. consecutive bytes, the first of which is pointed by
  154. .IR b ,
  155. into a null-terminated string, starting at
  156. .IR s .
  157. Printable characters are copied and non-printable characters are transformed
  158. into sequences of printable characters, representing those characters.
  159. Also, back-slashes and double quotes are escaped with a back-slash.
  160. The transformation agrees with the representation of non-printable
  161. characters in C strings.
  162. .br
  163. E.g., the row of 2 bytes
  164. .RS
  165. \&'\e0' '\en'
  166. .RE
  167. is turned into the string consisting of the following characters
  168. .RS
  169. \&'\e' '0' '0' '0' '\e' 'n' '\e0'
  170. .RE
  171. The latter string could be represented in C as "\e\e000\e\en".
  172. .PP
  173. .I Str2bts
  174. turns string
  175. .I s
  176. into a sequence of bytes pointed by
  177. .IR b .
  178. It has the inverse effect to
  179. .IR bts2str .
  180. The length of the resulting byte sequence is returned in
  181. .RI * pn .
  182. .br
  183. Both the functions
  184. .I bts2str
  185. and
  186. .I str2bts
  187. return a pointer to the result.
  188. .PP
  189. .I Long2str
  190. converts a long value
  191. .I l
  192. into a null-terminated string according to
  193. .IR base ,
  194. which indicates the base to use.
  195. This base may be any of 2..16.
  196. A negative base (in the range -16..-2) indicates that the long must be
  197. seen as unsigned.
  198. A pointer to the string is returned.
  199. .I Str2long
  200. returns the value that is represented in
  201. .IR s ,
  202. according to
  203. .IR base .
  204. .PP
  205. .I Btscpy
  206. copies
  207. .I n
  208. bytes from the string of bytes
  209. .I b2
  210. to
  211. .I b1
  212. and returns
  213. .IR b1 .
  214. .PP
  215. .I Btscat
  216. appends a copy of
  217. .I n2
  218. bytes from
  219. .I b2
  220. to the end of
  221. .IR b1 ,
  222. consisting of
  223. .I n1
  224. bytes.
  225. .I B1
  226. is returned.
  227. .PP
  228. .I Btscmp
  229. compares row of bytes
  230. .I b1
  231. with length
  232. .I n1
  233. and
  234. .I b2
  235. with length
  236. .I n2
  237. and returns an integer greater than, equal to, or less than 0, if
  238. .I b1
  239. is lexicographically greater then, equal to, or less than
  240. .IR b2 ,
  241. respectively.
  242. .PP
  243. .I Btszero
  244. places
  245. .I n
  246. null bytes in the string
  247. .IR b .
  248. .I B
  249. is returned.
  250. .SH FILES
  251. ~em/modules/lib/libstring.a
  252. .SH "SEE ALSO"
  253. string(3), bstring(3), atof(3)
  254. .SH BUGS
  255. No checks for overflow or illegal parameters.