strcasecmp.3, strcat.3, strchr.3, strcmp.3, strcoll.3, strcpy.3, strdup.3, strfry.3, strftime.3, strlen.3, strnlen.3, strpbrk.3, strsep.3, strsignal.3, strspn.3, strstr.3, strtok.3, strtol.3, strtoul.3, strxfrm.3: Convert inline formatting (\fX...\fP) to dot-directive formatting

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2013-06-07 19:02:51 +02:00
parent 022671eb41
commit 46d8df8ea4
20 changed files with 386 additions and 134 deletions

View File

@ -41,25 +41,38 @@ strcasecmp, strncasecmp \- compare two strings ignoring case
.SH DESCRIPTION .SH DESCRIPTION
The The
.BR strcasecmp () .BR strcasecmp ()
function compares the two strings \fIs1\fP and function compares the two strings
\fIs2\fP, ignoring the case of the characters. .I s1
and
.IR s2 ,
ignoring the case of the characters.
It returns an integer It returns an integer
less than, equal to, or greater than zero if \fIs1\fP is found, less than, equal to, or greater than zero if
respectively, to be less than, to match, or be greater than \fIs2\fP. .I s1
is found,
respectively, to be less than, to match, or be greater than
.IR s2 .
.PP .PP
The The
.BR strncasecmp () .BR strncasecmp ()
function is similar, except it compares function is similar, except it compares
the only first \fIn\fP bytes of \fIs1\fP. the only first
.I n
bytes of
.IR s1 .
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strcasecmp () .BR strcasecmp ()
and and
.BR strncasecmp () .BR strncasecmp ()
functions return functions return
an integer less than, equal to, or greater than zero if \fIs1\fP an integer less than, equal to, or greater than zero if
(or the first \fIn\fP bytes thereof) is found, respectively, to be .I s1
less than, to match, or be greater than \fIs2\fP. (or the first
.I n
bytes thereof) is found, respectively, to be
less than, to match, or be greater than
.IR s2 .
.SH CONFORMING TO .SH CONFORMING TO
4.4BSD, POSIX.1-2001. 4.4BSD, POSIX.1-2001.
.SH SEE ALSO .SH SEE ALSO

View File

@ -43,11 +43,17 @@ strcat, strncat \- concatenate two strings
.SH DESCRIPTION .SH DESCRIPTION
The The
.BR strcat () .BR strcat ()
function appends the \fIsrc\fP string to the function appends the
\fIdest\fP string, .I src
string to the
.I dest
string,
overwriting the terminating null byte (\(aq\\0\(aq) at the end of overwriting the terminating null byte (\(aq\\0\(aq) at the end of
\fIdest\fP, and then adds a terminating null byte. .IR dest ,
The strings may not overlap, and the \fIdest\fP string must have and then adds a terminating null byte.
The strings may not overlap, and the
.I dest
string must have
enough space for the result. enough space for the result.
If If
.I dest .I dest
@ -58,21 +64,41 @@ The
.BR strncat () .BR strncat ()
function is similar, except that function is similar, except that
.IP * 3 .IP * 3
it will use at most \fIn\fP bytes from \fIsrc\fP; and it will use at most
.I n
bytes from
.IR src ;
and
.IP * .IP *
\fIsrc\fP does not need to be null-terminated if it contains .I src
\fIn\fP or more bytes. does not need to be null-terminated if it contains
.I n
or more bytes.
.PP .PP
As with As with
.BR strcat (), .BR strcat (),
the resulting string in \fIdest\fP is always null-terminated. the resulting string in
.I dest
is always null-terminated.
.PP .PP
If \fIsrc\fP contains \fIn\fP or more bytes, If
.IR src
contains
.I n
or more bytes,
.BR strncat () .BR strncat ()
writes \fIn+1\fP bytes to \fIdest\fP (\fIn\fP writes
from \fIsrc\fP plus the terminating null byte). .I n+1
Therefore, the size of \fIdest\fP must be at least bytes to
\fIstrlen(dest)+n+1\fP. .I dest
.RI ( n
from
.I src
plus the terminating null byte).
Therefore, the size of
.I dest
must be at least
.IR "strlen(dest)+n+1" .
A simple implementation of A simple implementation of
.BR strncat () .BR strncat ()
@ -99,7 +125,8 @@ The
.BR strcat () .BR strcat ()
and and
.BR strncat () .BR strncat ()
functions return a pointer to the resulting string \fIdest\fP. functions return a pointer to the resulting string
.IR dest .
.SH CONFORMING TO .SH CONFORMING TO
SVr4, 4.3BSD, C89, C99. SVr4, 4.3BSD, C89, C99.
.SH NOTES .SH NOTES

View File

@ -96,7 +96,10 @@ The
function returns a pointer to function returns a pointer to
the matched character, the matched character,
or a pointer to the null or a pointer to the null
byte at the end of \fIs\fP (i.e., \fIs+strlen(s)\fP) byte at the end of
.I s
(i.e.,
.IR "s+strlen(s)" )
if the character is not found. if the character is not found.
.SH VERSIONS .SH VERSIONS
.BR strchrnul () .BR strchrnul ()

View File

@ -43,25 +43,39 @@ strcmp, strncmp \- compare two strings
.SH DESCRIPTION .SH DESCRIPTION
The The
.BR strcmp () .BR strcmp ()
function compares the two strings \fIs1\fP and function compares the two strings
\fIs2\fP. .I s1
and
.IR s2 .
It returns an integer less than, equal to, or greater It returns an integer less than, equal to, or greater
than zero if \fIs1\fP is found, respectively, to be less than, than zero if
to match, or be greater than \fIs2\fP. .I s1
is found, respectively, to be less than,
to match, or be greater than
.IR s2 .
.PP .PP
The The
.BR strncmp () .BR strncmp ()
function is similar, except it compares function is similar, except it compares
the only first (at most) \fIn\fP bytes of \fIs1\fP and \fIs2\fP. the only first (at most)
.IR n
bytes of
.I s1
and
.IR s2 .
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strcmp () .BR strcmp ()
and and
.BR strncmp () .BR strncmp ()
functions return an integer functions return an integer
less than, equal to, or greater than zero if \fIs1\fP (or the first less than, equal to, or greater than zero if
\fIn\fP bytes thereof) is found, respectively, to be less than, to .I s1
match, or be greater than \fIs2\fP. (or the first
.I n
bytes thereof) is found, respectively, to be less than, to
match, or be greater than
.IR s2 .
.SH CONFORMING TO .SH CONFORMING TO
SVr4, 4.3BSD, C89, C99. SVr4, 4.3BSD, C89, C99.
.SH SEE ALSO .SH SEE ALSO

View File

@ -39,27 +39,41 @@ strcoll \- compare two strings using the current locale
.SH DESCRIPTION .SH DESCRIPTION
The The
.BR strcoll () .BR strcoll ()
function compares the two strings \fIs1\fP and function compares the two strings
\fIs2\fP. .I s1
and
.IR s2 .
It returns an integer less than, equal to, or greater It returns an integer less than, equal to, or greater
than zero if \fIs1\fP is found, respectively, to be less than, than zero if
to match, or be greater than \fIs2\fP. .I s1
is found, respectively, to be less than,
to match, or be greater than
.IR s2 .
The comparison is based on The comparison is based on
strings interpreted as appropriate for the program's current locale strings interpreted as appropriate for the program's current locale
for category \fBLC_COLLATE\fP. for category
.BR LC_COLLATE .
(See (See
.BR setlocale (3).) .BR setlocale (3).)
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strcoll () .BR strcoll ()
function returns an integer less than, equal to, function returns an integer less than, equal to,
or greater than zero if \fIs1\fP is found, respectively, to be less or greater than zero if
than, to match, or be greater than \fIs2\fP, when both are interpreted .I s1
is found, respectively, to be less
than, to match, or be greater than
.IR s2 ,
when both are interpreted
as appropriate for the current locale. as appropriate for the current locale.
.SH CONFORMING TO .SH CONFORMING TO
SVr4, 4.3BSD, C89, C99. SVr4, 4.3BSD, C89, C99.
.SH NOTES .SH NOTES
In the \fI"POSIX"\fP or \fI"C"\fP locales In the
.I "POSIX"
or
.I ""C"
locales
.BR strcoll () .BR strcoll ()
is equivalent to is equivalent to
.BR strcmp (3). .BR strcmp (3).

View File

@ -46,22 +46,33 @@ strcpy, strncpy \- copy a string
.SH DESCRIPTION .SH DESCRIPTION
The The
.BR strcpy () .BR strcpy ()
function copies the string pointed to by \fIsrc\fP, function copies the string pointed to by
.IR src ,
including the terminating null byte (\(aq\\0\(aq), including the terminating null byte (\(aq\\0\(aq),
to the buffer pointed to by \fIdest\fP. to the buffer pointed to by
.IR dest .
The strings may not overlap, and the destination string The strings may not overlap, and the destination string
\fIdest\fP must be large enough to receive the copy. .I dest
must be large enough to receive the copy.
.IR "Beware of buffer overruns!" .IR "Beware of buffer overruns!"
(See BUGS.) (See BUGS.)
.PP .PP
The The
.BR strncpy () .BR strncpy ()
function is similar, except that at most function is similar, except that at most
\fIn\fP bytes of \fIsrc\fP are copied. .I n
bytes of
.I src
are copied.
.BR Warning : .BR Warning :
If there is no null byte If there is no null byte
among the first \fIn\fP bytes of \fIsrc\fP, among the first
the string placed in \fIdest\fP will not be null-terminated. .I n
bytes of
.IR src ,
the string placed in
.I dest
will not be null-terminated.
.PP .PP
If the length of If the length of
.I src .I src
@ -100,7 +111,8 @@ The
and and
.BR strncpy () .BR strncpy ()
functions return a pointer to functions return a pointer to
the destination string \fIdest\fP. the destination string
.IR dest .
.SH CONFORMING TO .SH CONFORMING TO
SVr4, 4.3BSD, C89, C99. SVr4, 4.3BSD, C89, C99.
.SH NOTES .SH NOTES
@ -108,8 +120,12 @@ Some programmers consider
.BR strncpy () .BR strncpy ()
to be inefficient and error prone. to be inefficient and error prone.
If the programmer knows (i.e., includes code to test!) If the programmer knows (i.e., includes code to test!)
that the size of \fIdest\fP is greater than that the size of
the length of \fIsrc\fP, then .I dest
is greater than
the length of
.IR src ,
then
.BR strcpy () .BR strcpy ()
can be used. can be used.
@ -122,10 +138,13 @@ and that unused bytes in the target buffer are zeroed out
written to media or transmitted to another process via an written to media or transmitted to another process via an
interprocess communication technique). interprocess communication technique).
If there is no terminating null byte in the first \fIn\fP If there is no terminating null byte in the first
bytes of \fIsrc\fP, .I n
bytes of
.IR src ,
.BR strncpy () .BR strncpy ()
produces an unterminated string in \fIdest\fP. produces an unterminated string in
.IR dest .
You can force termination using something like the following: You can force termination using something like the following:
.in +4n .in +4n
.nf .nf

View File

@ -78,7 +78,8 @@ _GNU_SOURCE
The The
.BR strdup () .BR strdup ()
function returns a pointer to a new string which function returns a pointer to a new string which
is a duplicate of the string \fIs\fP. is a duplicate of the string
.IR s .
Memory for the new string is Memory for the new string is
obtained with obtained with
.BR malloc (3), .BR malloc (3),
@ -88,8 +89,14 @@ and can be freed with
The The
.BR strndup () .BR strndup ()
function is similar, but copies at most function is similar, but copies at most
\fIn\fP bytes. .I n
If \fIs\fP is longer than \fIn\fP, only \fIn\fP bytes.
If
.I s
is longer than
.IR n ,
only
.I n
bytes are copied, and a terminating null byte (\(aq\\0\(aq) is added. bytes are copied, and a terminating null byte (\(aq\\0\(aq) is added.
.BR strdupa () .BR strdupa ()

View File

@ -41,11 +41,14 @@ strfry \- randomize a string
.SH DESCRIPTION .SH DESCRIPTION
The The
.BR strfry () .BR strfry ()
function randomizes the contents of \fIstring\fP by function randomizes the contents of
.I string
by
using using
.BR rand (3) .BR rand (3)
to randomly swap characters in the string. to randomly swap characters in the string.
The result is an anagram of \fIstring\fP. The result is an anagram of
.IR string .
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strfry () .BR strfry ()

View File

@ -47,9 +47,15 @@ strftime \- format date and time
.SH DESCRIPTION .SH DESCRIPTION
The The
.BR strftime () .BR strftime ()
function formats the broken-down time \fItm\fP function formats the broken-down time
according to the format specification \fIformat\fP and places the .I tm
result in the character array \fIs\fP of size \fImax\fP. according to the format specification
.I format
and places the
result in the character array
.I s
of size
.IR max .
.\" FIXME POSIX says: Local timezone information is used as though .\" FIXME POSIX says: Local timezone information is used as though
.\" strftime() called tzset(). But this doesn't appear to be the case .\" strftime() called tzset(). But this doesn't appear to be the case
.PP .PP
@ -63,7 +69,10 @@ All other character sequences are
.IR "ordinary character sequences". .IR "ordinary character sequences".
.PP .PP
The characters of ordinary character sequences (including the null byte) The characters of ordinary character sequences (including the null byte)
are copied verbatim from \fIformat\fP to \fIs\fP. are copied verbatim from
.I format
to
.IR s .
However, the characters However, the characters
of conversion specifications are replaced as follows: of conversion specifications are replaced as follows:
.TP .TP
@ -184,7 +193,9 @@ In the POSIX locale this is equivalent to
(SU) (SU)
.TP .TP
.B %R .B %R
The time in 24-hour notation (\fB%H:%M\fP). (SU) The time in 24-hour notation
.RB ( %H:%M ).
(SU)
For a version including the seconds, see For a version including the seconds, see
.B %T .B %T
below. below.
@ -200,7 +211,9 @@ The second as a decimal number (range 00 to 60).
A tab character. (SU) A tab character. (SU)
.TP .TP
.B %T .B %T
The time in 24-hour notation (\fB%H:%M:%S\fP). (SU) The time in 24-hour notation
.RB ( %H:%M:%S ).
(SU)
.TP .TP
.B %u .B %u
The day of the week as a decimal, range 1 to 7, Monday being 1. The day of the week as a decimal, range 1 to 7, Monday being 1.
@ -305,19 +318,26 @@ modifier is to use
alternative numeric symbols (say, roman numerals), and that of the alternative numeric symbols (say, roman numerals), and that of the
E modifier is to use a locale-dependent alternative representation. E modifier is to use a locale-dependent alternative representation.
.PP .PP
The broken-down time structure \fItm\fP is defined in \fI<time.h>\fP. The broken-down time structure
.I tm
is defined in
.IR <time.h> .
See also See also
.BR ctime (3). .BR ctime (3).
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strftime () .BR strftime ()
function returns the number of bytes placed function returns the number of bytes placed
in the array \fIs\fP, not including the terminating null byte, in the array
.IR s ,
not including the terminating null byte,
provided the string, including the terminating null byte, fits. provided the string, including the terminating null byte, fits.
Otherwise, it returns 0, and the contents of the array is undefined. Otherwise, it returns 0, and the contents of the array is undefined.
(This behavior applies since at least libc 4.4.4; (This behavior applies since at least libc 4.4.4;
very old versions of libc, such as libc 4.4.1, very old versions of libc, such as libc 4.4.1,
would return \fImax\fP if the array was too small.) would return
.I max
if the array was too small.)
.LP .LP
Note that the return value 0 does not necessarily indicate an error; Note that the return value 0 does not necessarily indicate an error;
for example, in many locales for example, in many locales
@ -374,7 +394,10 @@ of the preceding year.
For example, 1 January 2010 is a Friday, For example, 1 January 2010 is a Friday,
meaning that just three days of that calendar week fall in 2010. meaning that just three days of that calendar week fall in 2010.
Thus, the ISO\ 8601 week-based system considers these days to be part of Thus, the ISO\ 8601 week-based system considers these days to be part of
week 53 (\fB%V\fP) of the year 2009 (\fB%G\fP) ; week 53
.RB ( %V )
of the year 2009
.RB ( %G );
week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010. week 01 of ISO\ 8601 year 2010 starts on Monday, 4 January 2010.
.SS Glibc notes .SS Glibc notes
Glibc provides some extensions for conversion specifications. Glibc provides some extensions for conversion specifications.
@ -448,7 +471,9 @@ my_strftime(char *s, size_t max, const char *fmt,
Nowadays, Nowadays,
.BR gcc (1) .BR gcc (1)
provides the \fI\-Wno\-format\-y2k\fP option to prevent the warning, provides the
.IR \-Wno\-format\-y2k
option to prevent the warning,
so that the above workaround is no longer required. so that the above workaround is no longer required.
.SH EXAMPLE .SH EXAMPLE
.BR "RFC\ 2822-compliant date format" .BR "RFC\ 2822-compliant date format"

View File

@ -40,11 +40,13 @@ strlen \- calculate the length of a string
The The
.BR strlen () .BR strlen ()
function calculates the length of the string function calculates the length of the string
\fIs\fP, excluding the terminating null byte (\(aq\\0\(aq). .IR s ,
excluding the terminating null byte (\(aq\\0\(aq).
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strlen () .BR strlen ()
function returns the number of bytes in the string \fIs\fP. function returns the number of bytes in the string
.IR s .
.SH CONFORMING TO .SH CONFORMING TO
SVr4, 4.3BSD, C89, C99. SVr4, 4.3BSD, C89, C99.
.SH SEE ALSO .SH SEE ALSO

View File

@ -42,19 +42,32 @@ _GNU_SOURCE
The The
.BR strnlen () .BR strnlen ()
function returns the number of bytes in the string function returns the number of bytes in the string
pointed to by \fIs\fP, excluding the terminating null byte (\(aq\\0\(aq), pointed to by
but at most \fImaxlen\fP. .IR s ,
excluding the terminating null byte (\(aq\\0\(aq),
but at most
.IR maxlen .
In doing this, In doing this,
.BR strnlen () .BR strnlen ()
looks only at the first looks only at the first
\fImaxlen\fP bytes at \fIs\fP and never beyond \fIs+maxlen\fP. .I maxlen
bytes at
.I s
and never beyond
.IR s+maxlen .
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strnlen () .BR strnlen ()
function returns \fIstrlen(s)\fP, if that is less than function returns
\fImaxlen\fP, or \fImaxlen\fP .IR strlen(s) ,
if that is less than
.IR maxlen ,
or
.I maxlen
if there is no null byte (\(aq\\0\(aq) among the first if there is no null byte (\(aq\\0\(aq) among the first
\fImaxlen\fP bytes pointed to by \fIs\fP. .I maxlen
bytes pointed to by
.IR s .
.SH CONFORMING TO .SH CONFORMING TO
POSIX.1-2008. POSIX.1-2008.
.SH SEE ALSO .SH SEE ALSO

View File

@ -40,12 +40,18 @@ strpbrk \- search a string for any of a set of bytes
The The
.BR strpbrk () .BR strpbrk ()
function locates the first occurrence in the function locates the first occurrence in the
string \fIs\fP of any of the bytes in the string \fIaccept\fP. string
.I s
of any of the bytes in the string
.IR accept .
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strpbrk () .BR strpbrk ()
function returns a pointer to the byte in function returns a pointer to the byte in
\fIs\fP that matches one of the bytes in \fIaccept\fP, or NULL .I s
that matches one of the bytes in
.IR accept ,
or NULL
if no such byte is found. if no such byte is found.
.SH CONFORMING TO .SH CONFORMING TO
SVr4, 4.3BSD, C89, C99. SVr4, 4.3BSD, C89, C99.

View File

@ -48,23 +48,35 @@ Feature Test Macro Requirements for glibc (see
.BR strsep (): .BR strsep ():
_BSD_SOURCE _BSD_SOURCE
.SH DESCRIPTION .SH DESCRIPTION
If \fI*stringp\fP is NULL, the If
.I *stringp
is NULL, the
.BR strsep () .BR strsep ()
function returns NULL function returns NULL
and does nothing else. and does nothing else.
Otherwise, this function finds the first token Otherwise, this function finds the first token
in the string \fI*stringp\fP, where tokens in the string
are delimited by symbols in the string \fIdelim\fP. .IR *stringp ,
where tokens
are delimited by symbols in the string
.IR delim .
This token is terminated by overwriting the delimiter This token is terminated by overwriting the delimiter
with a null byte (\(aq\\0\(aq) with a null byte (\(aq\\0\(aq)
and \fI*stringp\fP is updated to point past the token. and
.I *stringp
is updated to point past the token.
In case no delimiter was found, the token is taken to be In case no delimiter was found, the token is taken to be
the entire string \fI*stringp\fP, and \fI*stringp\fP is made NULL. the entire string
.IR *stringp ,
and
.I *stringp
is made NULL.
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strsep () .BR strsep ()
function returns a pointer to the token, function returns a pointer to the token,
that is, it returns the original value of \fI*stringp\fP. that is, it returns the original value of
.IR *stringp .
.SH CONFORMING TO .SH CONFORMING TO
4.4BSD. 4.4BSD.
.SH NOTES .SH NOTES

View File

@ -61,11 +61,14 @@ _GNU_SOURCE
The The
.BR strsignal () .BR strsignal ()
function returns a string describing the signal function returns a string describing the signal
number passed in the argument \fIsig\fP. number passed in the argument
.IR sig .
The string can be used only until the next call to The string can be used only until the next call to
.BR strsignal (). .BR strsignal ().
.PP .PP
The array \fIsys_siglist\fP holds the signal description strings The array
.I sys_siglist
holds the signal description strings
indexed by signal number. indexed by signal number.
The The
.BR strsignal () .BR strsignal ()

View File

@ -42,26 +42,35 @@ strspn, strcspn \- search a string for a set of bytes
The The
.BR strspn () .BR strspn ()
function calculates the length (in bytes) of the initial function calculates the length (in bytes) of the initial
segment of \fIs\fP which consists entirely of bytes in segment of
\fIaccept\fP. .I s
which consists entirely of bytes in
.IR accept .
.PP .PP
The The
.BR strcspn () .BR strcspn ()
function calculates the length of the initial function calculates the length of the initial
segment of \fIs\fP which consists entirely of bytes not in segment of
\fIreject\fP. .I s
which consists entirely of bytes not in
.IR reject .
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strspn () .BR strspn ()
function returns the number of bytes in function returns the number of bytes in
the initial segment of \fIs\fP which consist only of bytes the initial segment of
from \fIaccept\fP. .I s
which consist only of bytes
from
.IR accept .
.PP .PP
The The
.BR strcspn () .BR strcspn ()
function returns the number of bytes in function returns the number of bytes in
the initial segment of \fIs\fP which are not in the string the initial segment of
\fIreject\fP. .I s
which are not in the string
.IR reject .
.SH CONFORMING TO .SH CONFORMING TO
SVr4, 4.3BSD, C89, C99. SVr4, 4.3BSD, C89, C99.
.SH SEE ALSO .SH SEE ALSO

View File

@ -49,7 +49,9 @@ strstr, strcasestr \- locate a substring
The The
.BR strstr () .BR strstr ()
function finds the first occurrence of the substring function finds the first occurrence of the substring
\fIneedle\fP in the string \fIhaystack\fP. .I needle
in the string
.IR haystack .
The terminating null bytes (\(aq\\0\(aq) are not compared. The terminating null bytes (\(aq\\0\(aq) are not compared.
The The
@ -69,10 +71,16 @@ The
function is a nonstandard extension. function is a nonstandard extension.
.SH BUGS .SH BUGS
Early versions of Linux libc (like 4.5.26) would not allow Early versions of Linux libc (like 4.5.26) would not allow
an empty \fIneedle\fP argument for an empty
.I needle
argument for
.BR strstr (). .BR strstr ().
Later versions (like 4.6.27) work correctly, Later versions (like 4.6.27) work correctly,
and return \fIhaystack\fP when \fIneedle\fP is empty. and return
.IR haystack
when
.I needle
is empty.
.SH SEE ALSO .SH SEE ALSO
.BR index (3), .BR index (3),
.BR memchr (3), .BR memchr (3),

View File

@ -58,13 +58,19 @@ function breaks a string into a sequence of zero or more nonempty tokens.
On the first call to On the first call to
.BR strtok () .BR strtok ()
the string to be parsed should be the string to be parsed should be
specified in \fIstr\fP. specified in
.IR str .
In each subsequent call that should parse the same string, In each subsequent call that should parse the same string,
\fIstr\fP must be NULL. .I str
must be NULL.
The \fIdelim\fP argument specifies a set of bytes that The
.I delim
argument specifies a set of bytes that
delimit the tokens in the parsed string. delimit the tokens in the parsed string.
The caller may specify different strings in \fIdelim\fP in successive The caller may specify different strings in
.I delim
in successive
calls that parse the same string. calls that parse the same string.
Each call to Each call to
@ -127,8 +133,11 @@ The
.BR strtok_r () .BR strtok_r ()
function is a reentrant version function is a reentrant version
.BR strtok (). .BR strtok ().
The \fIsaveptr\fP argument is a pointer to a The
\fIchar *\fP variable that is used internally by .I saveptr
argument is a pointer to a
.IR "char\ *"
variable that is used internally by
.BR strtok_r () .BR strtok_r ()
in order to maintain context between successive calls that parse the in order to maintain context between successive calls that parse the
same string. same string.
@ -139,12 +148,17 @@ On the first call to
should point to the string to be parsed, and the value of should point to the string to be parsed, and the value of
.I saveptr .I saveptr
is ignored. is ignored.
In subsequent calls, \fIstr\fP should be NULL, and In subsequent calls,
\fIsaveptr\fP should be unchanged since the previous call. .I str
should be NULL, and
.I saveptr
should be unchanged since the previous call.
Different strings may be parsed concurrently using sequences of calls to Different strings may be parsed concurrently using sequences of calls to
.BR strtok_r () .BR strtok_r ()
that specify different \fIsaveptr\fP arguments. that specify different
.I saveptr
arguments.
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strtok () .BR strtok ()

View File

@ -60,16 +60,23 @@ or
The The
.BR strtol () .BR strtol ()
function converts the initial part of the string function converts the initial part of the string
in \fInptr\fP to a long integer value according to the given \fIbase\fP, in
.I nptr
to a long integer value according to the given
.IR base ,
which must be between 2 and 36 inclusive, or be the special value 0. which must be between 2 and 36 inclusive, or be the special value 0.
.PP .PP
The string may begin with an arbitrary amount of white space (as The string may begin with an arbitrary amount of white space (as
determined by determined by
.BR isspace (3)) .BR isspace (3))
followed by a single optional \(aq+\(aq or \(aq\-\(aq sign. followed by a single optional \(aq+\(aq or \(aq\-\(aq sign.
If \fIbase\fP is zero or 16, the string may then include a If
.I base
is zero or 16, the string may then include a
"0x" prefix, and the number will be read in base 16; otherwise, a "0x" prefix, and the number will be read in base 16; otherwise, a
zero \fIbase\fP is taken as 10 (decimal) unless the next character zero
.I base
is taken as 10 (decimal) unless the next character
is \(aq0\(aq, in which case it is taken as 8 (octal). is \(aq0\(aq, in which case it is taken as 8 (octal).
.PP .PP
The remainder of the string is converted to a The remainder of the string is converted to a
@ -81,16 +88,25 @@ valid digit in the given base.
either upper or lower case represents 10, \(aqB\(aq represents 11, and so either upper or lower case represents 10, \(aqB\(aq represents 11, and so
forth, with \(aqZ\(aq representing 35.) forth, with \(aqZ\(aq representing 35.)
.PP .PP
If \fIendptr\fP is not NULL, If
.I endptr
is not NULL,
.BR strtol () .BR strtol ()
stores the address of the stores the address of the
first invalid character in \fI*endptr\fP. first invalid character in
.IR *endptr .
If there were no digits at If there were no digits at
all, all,
.BR strtol () .BR strtol ()
stores the original value of \fInptr\fP in stores the original value of
\fI*endptr\fP (and returns 0). .I nptr
In particular, if \fI*nptr\fP is not \(aq\\0\(aq but \fI**endptr\fP in
.I *endptr
(and returns 0).
In particular, if
.I *nptr
is not \(aq\\0\(aq but
.I **endptr
is \(aq\\0\(aq on return, the entire string is valid. is \(aq\\0\(aq on return, the entire string is valid.
.PP .PP
The The
@ -111,7 +127,9 @@ If an overflow occurs,
.BR strtol () .BR strtol ()
returns returns
.BR LONG_MAX . .BR LONG_MAX .
In both cases, \fIerrno\fP is set to In both cases,
.I errno
is set to
.BR ERANGE . .BR ERANGE .
Precisely the same holds for Precisely the same holds for
.BR strtoll () .BR strtoll ()
@ -134,7 +152,11 @@ contains an unsupported value.
.B ERANGE .B ERANGE
The resulting value was out of range. The resulting value was out of range.
.LP .LP
The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case The implementation may also set
.IR errno
to
.B EINVAL
in case
no conversion was performed (no digits seen, and 0 returned). no conversion was performed (no digits seen, and 0 returned).
.SH CONFORMING TO .SH CONFORMING TO
.BR strtol () .BR strtol ()

View File

@ -63,10 +63,14 @@ or
The The
.BR strtoul () .BR strtoul ()
function converts the initial part of the string function converts the initial part of the string
in \fInptr\fP to an in
.I nptr
to an
.I "unsigned long int" .I "unsigned long int"
value according to the value according to the
given \fIbase\fP, which must be between 2 and 36 inclusive, or be given
.IR base ,
which must be between 2 and 36 inclusive, or be
the special value 0. the special value 0.
.PP .PP
The string may begin with an arbitrary amount of white space (as The string may begin with an arbitrary amount of white space (as
@ -74,9 +78,13 @@ determined by
.BR isspace (3)) .BR isspace (3))
followed by a single optional \(aq+\(aq or \(aq\-\(aq followed by a single optional \(aq+\(aq or \(aq\-\(aq
sign. sign.
If \fIbase\fP is zero or 16, the string may then include a If
.I base
is zero or 16, the string may then include a
"0x" prefix, and the number will be read in base 16; otherwise, a "0x" prefix, and the number will be read in base 16; otherwise, a
zero \fIbase\fP is taken as 10 (decimal) unless the next character zero
.I base
is taken as 10 (decimal) unless the next character
is \(aq0\(aq, in which case it is taken as 8 (octal). is \(aq0\(aq, in which case it is taken as 8 (octal).
.PP .PP
The remainder of the string is converted to an The remainder of the string is converted to an
@ -88,16 +96,25 @@ valid digit in the given base.
either upper or lower case represents 10, \(aqB\(aq represents 11, and so either upper or lower case represents 10, \(aqB\(aq represents 11, and so
forth, with \(aqZ\(aq representing 35.) forth, with \(aqZ\(aq representing 35.)
.PP .PP
If \fIendptr\fP is not NULL, If
.I endptr
is not NULL,
.BR strtoul () .BR strtoul ()
stores the address of the stores the address of the
first invalid character in \fI*endptr\fP. first invalid character in
.IR *endptr .
If there were no digits at If there were no digits at
all, all,
.BR strtoul () .BR strtoul ()
stores the original value of \fInptr\fP in stores the original value of
\fI*endptr\fP (and returns 0). .I nptr
In particular, if \fI*nptr\fP is not \(aq\\0\(aq but \fI**endptr\fP in
.I *endptr
(and returns 0).
In particular, if
.I *nptr
is not \(aq\\0\(aq but
.I **endptr
is \(aq\\0\(aq on return, the entire string is valid. is \(aq\\0\(aq on return, the entire string is valid.
.PP .PP
The The
@ -118,7 +135,9 @@ the latter case,
.BR strtoul () .BR strtoul ()
returns returns
.B ULONG_MAX .B ULONG_MAX
and sets \fIerrno\fP to and sets
.I errno
to
.BR ERANGE . .BR ERANGE .
Precisely the same holds for Precisely the same holds for
.BR strtoull () .BR strtoull ()
@ -137,7 +156,11 @@ contains an unsupported value.
.B ERANGE .B ERANGE
The resulting value was out of range. The resulting value was out of range.
.LP .LP
The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case The implementation may also set
.IR errno
to
.B EINVAL
in case
no conversion was performed (no digits seen, and 0 returned). no conversion was performed (no digits seen, and 0 returned).
.SH CONFORMING TO .SH CONFORMING TO
.BR strtoul () .BR strtoul ()

View File

@ -39,7 +39,9 @@ strxfrm \- string transformation
.SH DESCRIPTION .SH DESCRIPTION
The The
.BR strxfrm () .BR strxfrm ()
function transforms the \fIsrc\fP string into a function transforms the
.I src
string into a
form such that the result of form such that the result of
.BR strcmp (3) .BR strcmp (3)
on two strings that have on two strings that have
@ -48,24 +50,37 @@ been transformed with
is the same as the result of is the same as the result of
.BR strcoll (3) .BR strcoll (3)
on the two strings before their transformation. on the two strings before their transformation.
The first \fIn\fP bytes of the transformed string are placed in The first
\fIdest\fP. .I n
bytes of the transformed string are placed in
.IR dest .
The transformation is based on the program's current The transformation is based on the program's current
locale for category \fBLC_COLLATE\fP. locale for category
.BR LC_COLLATE .
(See (See
.BR setlocale (3)). .BR setlocale (3)).
.SH RETURN VALUE .SH RETURN VALUE
The The
.BR strxfrm () .BR strxfrm ()
function returns the number of bytes required to function returns the number of bytes required to
store the transformed string in \fIdest\fP excluding the store the transformed string in
.I dest
excluding the
terminating null byte (\(aq\\0\(aq). terminating null byte (\(aq\\0\(aq).
If the value returned is \fIn\fP or more, the If the value returned is
contents of \fIdest\fP are indeterminate. .I n
or more, the
contents of
.I dest
are indeterminate.
.SH CONFORMING TO .SH CONFORMING TO
SVr4, 4.3BSD, C89, C99. SVr4, 4.3BSD, C89, C99.
.SH NOTES .SH NOTES
In the \fI"POSIX"\fP or \fI"C"\fP locales In the
.IR POSIX
or
.IR C
locales
.BR strxfrm () .BR strxfrm ()
is equivalent to is equivalent to
copying the string with copying the string with