.SH DESCRIPTION
The
.BR strcasecmp ()
-function compares the two strings \fIs1\fP and
-\fIs2\fP, ignoring the case of the characters.
+function compares the two strings
+.I s1
+and
+.IR s2 ,
+ignoring the case of the characters.
It returns an integer
-less than, equal to, or greater than zero if \fIs1\fP is found,
-respectively, to be less than, to match, or be greater than \fIs2\fP.
+less than, equal to, or greater than zero if
+.I s1
+is found,
+respectively, to be less than, to match, or be greater than
+.IR s2 .
.PP
The
.BR strncasecmp ()
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
The
.BR strcasecmp ()
and
.BR strncasecmp ()
functions return
-an integer less than, equal to, or greater than zero if \fIs1\fP
-(or the first \fIn\fP bytes thereof) is found, respectively, to be
-less than, to match, or be greater than \fIs2\fP.
+an integer less than, equal to, or greater than zero if
+.I s1
+(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
4.4BSD, POSIX.1-2001.
.SH SEE ALSO
.SH DESCRIPTION
The
.BR strcat ()
-function appends the \fIsrc\fP string to the
-\fIdest\fP string,
+function appends the
+.I src
+string to the
+.I dest
+string,
overwriting the terminating null byte (\(aq\\0\(aq) at the end of
-\fIdest\fP, and then adds a terminating null byte.
-The strings may not overlap, and the \fIdest\fP string must have
+.IR dest ,
+and then adds a terminating null byte.
+The strings may not overlap, and the
+.I dest
+string must have
enough space for the result.
If
.I dest
.BR strncat ()
function is similar, except that
.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 *
-\fIsrc\fP does not need to be null-terminated if it contains
-\fIn\fP or more bytes.
+.I src
+does not need to be null-terminated if it contains
+.I n
+or more bytes.
.PP
As with
.BR strcat (),
-the resulting string in \fIdest\fP is always null-terminated.
+the resulting string in
+.I dest
+is always null-terminated.
.PP
-If \fIsrc\fP contains \fIn\fP or more bytes,
+If
+.IR src
+contains
+.I n
+or more bytes,
.BR strncat ()
-writes \fIn+1\fP bytes to \fIdest\fP (\fIn\fP
-from \fIsrc\fP plus the terminating null byte).
-Therefore, the size of \fIdest\fP must be at least
-\fIstrlen(dest)+n+1\fP.
+writes
+.I n+1
+bytes to
+.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
.BR strncat ()
.BR strcat ()
and
.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
SVr4, 4.3BSD, C89, C99.
.SH NOTES
function returns a pointer to
the matched character,
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.
.SH VERSIONS
.BR strchrnul ()
.SH DESCRIPTION
The
.BR strcmp ()
-function compares the two strings \fIs1\fP and
-\fIs2\fP.
+function compares the two strings
+.I s1
+and
+.IR s2 .
It returns an integer less than, equal to, or greater
-than zero if \fIs1\fP is found, respectively, to be less than,
-to match, or be greater than \fIs2\fP.
+than zero if
+.I s1
+is found, respectively, to be less than,
+to match, or be greater than
+.IR s2 .
.PP
The
.BR strncmp ()
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
The
.BR strcmp ()
and
.BR strncmp ()
functions return an integer
-less than, equal to, or greater than zero if \fIs1\fP (or the first
-\fIn\fP bytes thereof) is found, respectively, to be less than, to
-match, or be greater than \fIs2\fP.
+less than, equal to, or greater than zero if
+.I s1
+(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
SVr4, 4.3BSD, C89, C99.
.SH SEE ALSO
.SH DESCRIPTION
The
.BR strcoll ()
-function compares the two strings \fIs1\fP and
-\fIs2\fP.
+function compares the two strings
+.I s1
+and
+.IR s2 .
It returns an integer less than, equal to, or greater
-than zero if \fIs1\fP is found, respectively, to be less than,
-to match, or be greater than \fIs2\fP.
+than zero if
+.I s1
+is found, respectively, to be less than,
+to match, or be greater than
+.IR s2 .
The comparison is based on
strings interpreted as appropriate for the program's current locale
-for category \fBLC_COLLATE\fP.
+for category
+.BR LC_COLLATE .
(See
.BR setlocale (3).)
.SH RETURN VALUE
The
.BR strcoll ()
function returns an integer less than, equal to,
-or greater than zero if \fIs1\fP is found, respectively, to be less
-than, to match, or be greater than \fIs2\fP, when both are interpreted
+or greater than zero if
+.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.
.SH CONFORMING TO
SVr4, 4.3BSD, C89, C99.
.SH NOTES
-In the \fI"POSIX"\fP or \fI"C"\fP locales
+In the
+.I "POSIX"
+or
+.I ""C"
+locales
.BR strcoll ()
is equivalent to
.BR strcmp (3).
.SH DESCRIPTION
The
.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),
-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
-\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!"
(See BUGS.)
.PP
The
.BR strncpy ()
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 :
If there is no null byte
-among the first \fIn\fP bytes of \fIsrc\fP,
-the string placed in \fIdest\fP will not be null-terminated.
+among the first
+.I n
+bytes of
+.IR src ,
+the string placed in
+.I dest
+will not be null-terminated.
.PP
If the length of
.I src
and
.BR strncpy ()
functions return a pointer to
-the destination string \fIdest\fP.
+the destination string
+.IR dest .
.SH CONFORMING TO
SVr4, 4.3BSD, C89, C99.
.SH NOTES
.BR strncpy ()
to be inefficient and error prone.
If the programmer knows (i.e., includes code to test!)
-that the size of \fIdest\fP is greater than
-the length of \fIsrc\fP, then
+that the size of
+.I dest
+is greater than
+the length of
+.IR src ,
+then
.BR strcpy ()
can be used.
written to media or transmitted to another process via an
interprocess communication technique).
-If there is no terminating null byte in the first \fIn\fP
-bytes of \fIsrc\fP,
+If there is no terminating null byte in the first
+.I n
+bytes of
+.IR src ,
.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:
.in +4n
.nf
The
.BR strdup ()
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
obtained with
.BR malloc (3),
The
.BR strndup ()
function is similar, but copies at most
-\fIn\fP bytes.
-If \fIs\fP is longer than \fIn\fP, only \fIn\fP
+.I n
+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.
.BR strdupa ()
.SH DESCRIPTION
The
.BR strfry ()
-function randomizes the contents of \fIstring\fP by
+function randomizes the contents of
+.I string
+by
using
.BR rand (3)
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
The
.BR strfry ()
.SH DESCRIPTION
The
.BR strftime ()
-function formats the broken-down time \fItm\fP
-according to the format specification \fIformat\fP and places the
-result in the character array \fIs\fP of size \fImax\fP.
+function formats the broken-down time
+.I tm
+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
.\" strftime() called tzset(). But this doesn't appear to be the case
.PP
.IR "ordinary character sequences".
.PP
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
of conversion specifications are replaced as follows:
.TP
(SU)
.TP
.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
.B %T
below.
A tab character. (SU)
.TP
.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
.B %u
The day of the week as a decimal, range 1 to 7, Monday being 1.
alternative numeric symbols (say, roman numerals), and that of the
E modifier is to use a locale-dependent alternative representation.
.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
.BR ctime (3).
.SH RETURN VALUE
The
.BR strftime ()
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.
Otherwise, it returns 0, and the contents of the array is undefined.
(This behavior applies since at least libc 4.4.4;
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
Note that the return value 0 does not necessarily indicate an error;
for example, in many locales
For example, 1 January 2010 is a Friday,
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
-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.
.SS Glibc notes
Glibc provides some extensions for conversion specifications.
Nowadays,
.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.
.SH EXAMPLE
.BR "RFC\ 2822-compliant date format"
The
.BR strlen ()
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
The
.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
SVr4, 4.3BSD, C89, C99.
.SH SEE ALSO
The
.BR strnlen ()
function returns the number of bytes in the string
-pointed to by \fIs\fP, excluding the terminating null byte (\(aq\\0\(aq),
-but at most \fImaxlen\fP.
+pointed to by
+.IR s ,
+excluding the terminating null byte (\(aq\\0\(aq),
+but at most
+.IR maxlen .
In doing this,
.BR strnlen ()
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
The
.BR strnlen ()
-function returns \fIstrlen(s)\fP, if that is less than
-\fImaxlen\fP, or \fImaxlen\fP
+function returns
+.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
-\fImaxlen\fP bytes pointed to by \fIs\fP.
+.I maxlen
+bytes pointed to by
+.IR s .
.SH CONFORMING TO
POSIX.1-2008.
.SH SEE ALSO
The
.BR strpbrk ()
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
The
.BR strpbrk ()
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.
.SH CONFORMING TO
SVr4, 4.3BSD, C89, C99.
.BR strsep ():
_BSD_SOURCE
.SH DESCRIPTION
-If \fI*stringp\fP is NULL, the
+If
+.I *stringp
+is NULL, the
.BR strsep ()
function returns NULL
and does nothing else.
Otherwise, this function finds the first token
-in the string \fI*stringp\fP, where tokens
-are delimited by symbols in the string \fIdelim\fP.
+in the string
+.IR *stringp ,
+where tokens
+are delimited by symbols in the string
+.IR delim .
This token is terminated by overwriting the delimiter
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
-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
The
.BR strsep ()
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
4.4BSD.
.SH NOTES
The
.BR strsignal ()
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
.BR strsignal ().
.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.
The
.BR strsignal ()
The
.BR strspn ()
function calculates the length (in bytes) of the initial
-segment of \fIs\fP which consists entirely of bytes in
-\fIaccept\fP.
+segment of
+.I s
+which consists entirely of bytes in
+.IR accept .
.PP
The
.BR strcspn ()
function calculates the length of the initial
-segment of \fIs\fP which consists entirely of bytes not in
-\fIreject\fP.
+segment of
+.I s
+which consists entirely of bytes not in
+.IR reject .
.SH RETURN VALUE
The
.BR strspn ()
function returns the number of bytes in
-the initial segment of \fIs\fP which consist only of bytes
-from \fIaccept\fP.
+the initial segment of
+.I s
+which consist only of bytes
+from
+.IR accept .
.PP
The
.BR strcspn ()
function returns the number of bytes in
-the initial segment of \fIs\fP which are not in the string
-\fIreject\fP.
+the initial segment of
+.I s
+which are not in the string
+.IR reject .
.SH CONFORMING TO
SVr4, 4.3BSD, C89, C99.
.SH SEE ALSO
The
.BR strstr ()
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
function is a nonstandard extension.
.SH BUGS
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 ().
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
.BR index (3),
.BR memchr (3),
On the first call to
.BR strtok ()
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,
-\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.
-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.
Each call to
.BR strtok_r ()
function is a reentrant version
.BR strtok ().
-The \fIsaveptr\fP argument is a pointer to a
-\fIchar *\fP variable that is used internally by
+The
+.I saveptr
+argument is a pointer to a
+.IR "char\ *"
+variable that is used internally by
.BR strtok_r ()
in order to maintain context between successive calls that parse the
same string.
should point to the string to be parsed, and the value of
.I saveptr
is ignored.
-In subsequent calls, \fIstr\fP should be NULL, and
-\fIsaveptr\fP should be unchanged since the previous call.
+In subsequent calls,
+.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
.BR strtok_r ()
-that specify different \fIsaveptr\fP arguments.
+that specify different
+.I saveptr
+arguments.
.SH RETURN VALUE
The
.BR strtok ()
The
.BR strtol ()
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.
.PP
The string may begin with an arbitrary amount of white space (as
determined by
.BR isspace (3))
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
-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).
.PP
The remainder of the string is converted to a
either upper or lower case represents 10, \(aqB\(aq represents 11, and so
forth, with \(aqZ\(aq representing 35.)
.PP
-If \fIendptr\fP is not NULL,
+If
+.I endptr
+is not NULL,
.BR strtol ()
stores the address of the
-first invalid character in \fI*endptr\fP.
+first invalid character in
+.IR *endptr .
If there were no digits at
all,
.BR strtol ()
-stores the original value of \fInptr\fP in
-\fI*endptr\fP (and returns 0).
-In particular, if \fI*nptr\fP is not \(aq\\0\(aq but \fI**endptr\fP
+stores the original value of
+.I nptr
+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.
.PP
The
.BR strtol ()
returns
.BR LONG_MAX .
-In both cases, \fIerrno\fP is set to
+In both cases,
+.I errno
+is set to
.BR ERANGE .
Precisely the same holds for
.BR strtoll ()
.B ERANGE
The resulting value was out of range.
.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).
.SH CONFORMING TO
.BR strtol ()
The
.BR strtoul ()
function converts the initial part of the string
-in \fInptr\fP to an
+in
+.I nptr
+to an
.I "unsigned long int"
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.
.PP
The string may begin with an arbitrary amount of white space (as
.BR isspace (3))
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
-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).
.PP
The remainder of the string is converted to an
either upper or lower case represents 10, \(aqB\(aq represents 11, and so
forth, with \(aqZ\(aq representing 35.)
.PP
-If \fIendptr\fP is not NULL,
+If
+.I endptr
+is not NULL,
.BR strtoul ()
stores the address of the
-first invalid character in \fI*endptr\fP.
+first invalid character in
+.IR *endptr .
If there were no digits at
all,
.BR strtoul ()
-stores the original value of \fInptr\fP in
-\fI*endptr\fP (and returns 0).
-In particular, if \fI*nptr\fP is not \(aq\\0\(aq but \fI**endptr\fP
+stores the original value of
+.I nptr
+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.
.PP
The
.BR strtoul ()
returns
.B ULONG_MAX
-and sets \fIerrno\fP to
+and sets
+.I errno
+to
.BR ERANGE .
Precisely the same holds for
.BR strtoull ()
.B ERANGE
The resulting value was out of range.
.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).
.SH CONFORMING TO
.BR strtoul ()
.SH DESCRIPTION
The
.BR strxfrm ()
-function transforms the \fIsrc\fP string into a
+function transforms the
+.I src
+string into a
form such that the result of
.BR strcmp (3)
on two strings that have
is the same as the result of
.BR strcoll (3)
on the two strings before their transformation.
-The first \fIn\fP bytes of the transformed string are placed in
-\fIdest\fP.
+The first
+.I n
+bytes of the transformed string are placed in
+.IR dest .
The transformation is based on the program's current
-locale for category \fBLC_COLLATE\fP.
+locale for category
+.BR LC_COLLATE .
(See
.BR setlocale (3)).
.SH RETURN VALUE
The
.BR strxfrm ()
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).
-If the value returned is \fIn\fP or more, the
-contents of \fIdest\fP are indeterminate.
+If the value returned is
+.I n
+or more, the
+contents of
+.I dest
+are indeterminate.
.SH CONFORMING TO
SVr4, 4.3BSD, C89, C99.
.SH NOTES
-In the \fI"POSIX"\fP or \fI"C"\fP locales
+In the
+.IR POSIX
+or
+.IR C
+locales
.BR strxfrm ()
is equivalent to
copying the string with
projects / thirdparty / man-pages.git / commitdiff
