modules/src/string/string.3

   1 .TH STRING 3 "$Revision: 1.8 $"
   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.