string.3 4.3 KB

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