123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257 |
- .TH STRING 3 "$Revision$"
- .ad
- .SH NAME
- strcpy, strncpy, strcat, strncat, strcmp, strncmp,
- strlen, strindex, strrindex, strzero, str2bts,
- long2str, str2long,
- btscpy, btscat, btscmp, btszero, bts2str \- operations on and
- conversions between strings and row of bytes
- .SH SYNOPSIS
- .nf
- .B #include <ack_string.h>
- .PP
- .B char *strcpy(s1, s2)
- .B char *s1, *s2;
- .PP
- .B char *strncpy(s1, s2, n)
- .B char *s1, *s2;
- .PP
- .B char *strcat(s1, s2)
- .B char *s1, *s2;
- .PP
- .B char *strncat(s1, s2, n)
- .B char *s1, *s2;
- .PP
- .B int strcmp(s1, s2)
- .B char *s1, *s2;
- .PP
- .B int strncmp(s1, s2, n)
- .B char *s1, *s2;
- .PP
- .B int strlen(s)
- .B char *s;
- .PP
- .B char *strindex(s, c)
- .B char *s, c;
- .PP
- .B char *strrindex(s, c)
- .B char *s, c;
- .PP
- .B char *strzero(s)
- .B char *s;
- .PP
- .B char *str2bts(s, b, pn)
- .B char *s, *b;
- .B int *pn;
- .PP
- .B char *long2str(l, base)
- .B long l;
- .B int base;
- .PP
- .B long str2long(s, base)
- .B char *s;
- .B int base;
- .PP
- .B char *btscpy(b1, b2, n)
- .B char *b1, *b2;
- .B int n;
- .PP
- .B char *btscat(b1, n1, b2, n2)
- .B char *b1, *b2;
- .B int n1, n2;
- .PP
- .B int btscmp(b1, n1, b2, n2)
- .B char *b1, *b2;
- .B int n1, n2;
- .PP
- .B char *btszero(b, n)
- .B char *b;
- .B int n;
- .PP
- .B char *bts2str(b, n, s)
- .B char *b, *s;
- .B int n;
- .fi
- .SH DESCRIPTION
- The
- .IR str *
- functions operate on null-terminated strings.
- The
- .IR bts *
- functions operate on variable-length rows of bytes,
- regardless of null bytes.
- Neither of these functions check for overflow of any receiving area.
- .PP
- .I Strcpy
- copies string
- .I s2
- to
- .I s1,
- stopping after the null character has been moved.
- .I Strncpy
- copies exactly
- .I n
- characters,
- truncating or null-padding
- .I s2;
- the target may not be null-terminated if the length
- of
- .I s2
- is
- .I n
- or more.
- Both return
- .IR s1 .
- .PP
- .I Strcat
- appends a copy of string
- .I s2
- to the end of string
- .IR s1 .
- .I Strncat
- copies at most
- .I n
- characters.
- Both return a pointer to the null-terminated result
- .IR s1 .
- .PP
- .I Strcmp
- compares its arguments and returns an integer
- greater than, equal to, or less than 0, if
- .I s1
- is lexicographically greater than, equal to, or
- less than
- .IR s2 ,
- respectively.
- .I Strncmp
- makes the same comparison but checks at most
- .I n
- characters.
- .PP
- .I Strlen
- returns the number of characters before the null-character.
- .IR s .
- .PP
- .I Strindex
- .RI ( strrindex )
- returns a pointer to the first (last)
- occurrence of character
- .I c
- in string
- .I s,
- or zero if
- .I c
- does not occur in
- .IR s .
- .PP
- .I Strzero
- turns
- .I s
- into a null string.
- .PP
- .I Bts2str
- turns a row of
- .I n
- consecutive bytes, the first of which is pointed by
- .IR b ,
- into a null-terminated string, starting at
- .IR s .
- Printable characters are copied and non-printable characters are transformed
- into sequences of printable characters, representing those characters.
- Also, back-slashes and double quotes are escaped with a back-slash.
- The transformation agrees with the representation of non-printable
- characters in C strings.
- .br
- E.g., the row of 2 bytes
- .RS
- \&'\e0' '\en'
- .RE
- is turned into the string consisting of the following characters
- .RS
- \&'\e' '0' '0' '0' '\e' 'n' '\e0'
- .RE
- The latter string could be represented in C as "\e\e000\e\en".
- .PP
- .I Str2bts
- turns string
- .I s
- into a sequence of bytes pointed by
- .IR b .
- It has the inverse effect to
- .IR bts2str .
- The length of the resulting byte sequence is returned in
- .RI * pn .
- .br
- Both the functions
- .I bts2str
- and
- .I str2bts
- return a pointer to the result.
- .PP
- .I Long2str
- converts a long value
- .I l
- into a null-terminated string according to
- .IR base ,
- which indicates the base to use.
- This base may be any of 2..16.
- A negative base (in the range -16..-2) indicates that the long must be
- seen as unsigned.
- A pointer to the string is returned.
- .I Str2long
- returns the value that is represented in
- .IR s ,
- according to
- .IR base .
- .PP
- .I Btscpy
- copies
- .I n
- bytes from the string of bytes
- .I b2
- to
- .I b1
- and returns
- .IR b1 .
- .PP
- .I Btscat
- appends a copy of
- .I n2
- bytes from
- .I b2
- to the end of
- .IR b1 ,
- consisting of
- .I n1
- bytes.
- .I B1
- is returned.
- .PP
- .I Btscmp
- compares row of bytes
- .I b1
- with length
- .I n1
- and
- .I b2
- with length
- .I n2
- and returns an integer greater than, equal to, or less than 0, if
- .I b1
- is lexicographically greater then, equal to, or less than
- .IR b2 ,
- respectively.
- .PP
- .I Btszero
- places
- .I n
- null bytes in the string
- .IR b .
- .I B
- is returned.
- .SH FILES
- ~em/modules/lib/libstring.a
- .SH "SEE ALSO"
- string(3), bstring(3), atof(3)
- .SH BUGS
- No checks for overflow or illegal parameters.
|