.TH STRING 3ACK "86/03/18"
.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 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.
.SH AUTHOR
Erik Baalbergen <erikb@vu44.UUCP>