mirror of https://github.com/mkerrisk/man-pages
confstr.3, strcasecmp.3, strcat.3, strcmp.3, strcpy.3, strdup.3, strftime.3, strlen.3, strnlen.3, strpbrk.3, strspn.3, strtok.3, strxfrm.3: Clarify that these functions operate on bytes, not (wide) characters
Change 'character(s)' to 'byte(s)' to make clear that these functions operate on bytes, not wide / UTF8 characters. (POSIX uses 'byte(s)' similarly, to make this point.) Reported-by: Andries E. Brouwer <Andries.Brouwer@cwi.nl> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
c95b6ae1ce
commit
a00b7454b8
|
@ -76,7 +76,7 @@ copies the value of the string to
|
||||||
.I buf
|
.I buf
|
||||||
truncated to
|
truncated to
|
||||||
.I len \- 1
|
.I len \- 1
|
||||||
characters if necessary, with a null byte (\(aq\\0\(aq) as terminator.
|
bytes if necessary, with a null byte (\(aq\\0\(aq) as terminator.
|
||||||
This can be detected by comparing the return value of
|
This can be detected by comparing the return value of
|
||||||
.BR confstr ()
|
.BR confstr ()
|
||||||
against
|
against
|
||||||
|
|
|
@ -48,7 +48,7 @@ respectively, to be less than, to match, or be greater than \fIs2\fP.
|
||||||
The
|
The
|
||||||
.BR strncasecmp ()
|
.BR strncasecmp ()
|
||||||
function is similar, except it only compares
|
function is similar, except it only compares
|
||||||
the first \fIn\fP characters of \fIs1\fP.
|
the first \fIn\fP bytes of \fIs1\fP.
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
The
|
The
|
||||||
.BR strcasecmp ()
|
.BR strcasecmp ()
|
||||||
|
|
|
@ -52,18 +52,18 @@ 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 characters from \fIsrc\fP; and
|
it will use at most \fIn\fP bytes from \fIsrc\fP; and
|
||||||
.IP *
|
.IP *
|
||||||
\fIsrc\fP does not need to be null-terminated if it contains
|
\fIsrc\fP does not need to be null-terminated if it contains
|
||||||
\fIn\fP or more characters.
|
\fIn\fP 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 \fIdest\fP is always null-terminated.
|
||||||
.PP
|
.PP
|
||||||
If \fIsrc\fP contains \fIn\fP or more characters,
|
If \fIsrc\fP contains \fIn\fP or more bytes,
|
||||||
.BR strncat ()
|
.BR strncat ()
|
||||||
writes \fIn+1\fP characters to \fIdest\fP (\fIn\fP
|
writes \fIn+1\fP bytes to \fIdest\fP (\fIn\fP
|
||||||
from \fIsrc\fP plus the terminating null byte).
|
from \fIsrc\fP plus the terminating null byte).
|
||||||
Therefore, the size of \fIdest\fP must be at least
|
Therefore, the size of \fIdest\fP must be at least
|
||||||
\fIstrlen(dest)+n+1\fP.
|
\fIstrlen(dest)+n+1\fP.
|
||||||
|
|
|
@ -50,7 +50,7 @@ to match, or be greater than \fIs2\fP.
|
||||||
The
|
The
|
||||||
.BR strncmp ()
|
.BR strncmp ()
|
||||||
function is similar, except it only compares
|
function is similar, except it only compares
|
||||||
the first (at most) \fIn\fP characters of \fIs1\fP and \fIs2\fP.
|
the first (at most) \fIn\fP bytes of \fIs1\fP and \fIs2\fP.
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
The
|
The
|
||||||
.BR strcmp ()
|
.BR strcmp ()
|
||||||
|
|
|
@ -108,7 +108,7 @@ the length of \fIsrc\fP, then
|
||||||
can be used.
|
can be used.
|
||||||
|
|
||||||
If there is no terminating null byte in the first \fIn\fP
|
If there is no terminating null byte in the first \fIn\fP
|
||||||
characters of \fIsrc\fP,
|
bytes of \fIsrc\fP,
|
||||||
.BR strncpy ()
|
.BR strncpy ()
|
||||||
produces an unterminated string in \fIdest\fP.
|
produces an unterminated string in \fIdest\fP.
|
||||||
Programmers often prevent this mistake by forcing termination
|
Programmers often prevent this mistake by forcing termination
|
||||||
|
|
|
@ -86,9 +86,9 @@ and can be freed with
|
||||||
The
|
The
|
||||||
.BR strndup ()
|
.BR strndup ()
|
||||||
function is similar, but only copies at most
|
function is similar, but only copies at most
|
||||||
\fIn\fP characters.
|
\fIn\fP bytes.
|
||||||
If \fIs\fP is longer than \fIn\fP, only \fIn\fP
|
If \fIs\fP is longer than \fIn\fP, only \fIn\fP
|
||||||
characters 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 ()
|
||||||
and
|
and
|
||||||
|
|
|
@ -308,7 +308,7 @@ See also
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
The
|
The
|
||||||
.BR strftime ()
|
.BR strftime ()
|
||||||
function returns the number of characters placed
|
function returns the number of bytes placed
|
||||||
in the array \fIs\fP, not including the terminating null byte,
|
in the array \fIs\fP, 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.
|
||||||
|
|
|
@ -25,7 +25,7 @@
|
||||||
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
|
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
|
||||||
.\" 386BSD man pages
|
.\" 386BSD man pages
|
||||||
.\" Modified Sat Jul 24 18:02:26 1993 by Rik Faith (faith@cs.unc.edu)
|
.\" Modified Sat Jul 24 18:02:26 1993 by Rik Faith (faith@cs.unc.edu)
|
||||||
.TH STRLEN 3 2011-09-28 "GNU" "Linux Programmer's Manual"
|
.TH STRLEN 3 2012-05-04 "GNU" "Linux Programmer's Manual"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
strlen \- calculate the length of a string
|
strlen \- calculate the length of a string
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
|
@ -42,7 +42,7 @@ function calculates the length of the string
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
The
|
The
|
||||||
.BR strlen ()
|
.BR strlen ()
|
||||||
function returns the number of characters in \fIs\fP.
|
function returns the number of bytes in the string \fIs\fP.
|
||||||
.SH "CONFORMING TO"
|
.SH "CONFORMING TO"
|
||||||
SVr4, 4.3BSD, C89, C99.
|
SVr4, 4.3BSD, C89, C99.
|
||||||
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
||||||
|
|
|
@ -39,20 +39,20 @@ _GNU_SOURCE
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
The
|
The
|
||||||
.BR strnlen ()
|
.BR strnlen ()
|
||||||
function returns the number of characters in the string
|
function returns the number of bytes in the string
|
||||||
pointed to by \fIs\fP, excluding the terminating null bye (\(aq\\0\(aq),
|
pointed to by \fIs\fP, excluding the terminating null bye (\(aq\\0\(aq),
|
||||||
but at most \fImaxlen\fP.
|
but at most \fImaxlen\fP.
|
||||||
In doing this,
|
In doing this,
|
||||||
.BR strnlen ()
|
.BR strnlen ()
|
||||||
looks only at the first
|
looks only at the first
|
||||||
\fImaxlen\fP characters at \fIs\fP and never beyond \fIs+maxlen\fP.
|
\fImaxlen\fP bytes at \fIs\fP and never beyond \fIs+maxlen\fP.
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
The
|
The
|
||||||
.BR strnlen ()
|
.BR strnlen ()
|
||||||
function returns \fIstrlen(s)\fP, if that is less than
|
function returns \fIstrlen(s)\fP, if that is less than
|
||||||
\fImaxlen\fP, or \fImaxlen\fP
|
\fImaxlen\fP, or \fImaxlen\fP
|
||||||
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 characters pointed to by \fIs\fP.
|
\fImaxlen\fP bytes pointed to by \fIs\fP.
|
||||||
.SH "CONFORMING TO"
|
.SH "CONFORMING TO"
|
||||||
POSIX.1-2008.
|
POSIX.1-2008.
|
||||||
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
||||||
|
|
|
@ -27,7 +27,7 @@
|
||||||
.\" Modified Sat Jul 24 18:01:24 1993 by Rik Faith (faith@cs.unc.edu)
|
.\" Modified Sat Jul 24 18:01:24 1993 by Rik Faith (faith@cs.unc.edu)
|
||||||
.TH STRPBRK 3 2010-09-20 "" "Linux Programmer's Manual"
|
.TH STRPBRK 3 2010-09-20 "" "Linux Programmer's Manual"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
strpbrk \- search a string for any of a set of characters
|
strpbrk \- search a string for any of a set of bytes
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.nf
|
.nf
|
||||||
.B #include <string.h>
|
.B #include <string.h>
|
||||||
|
@ -38,13 +38,13 @@ strpbrk \- search a string for any of a set of characters
|
||||||
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 characters in the string \fIaccept\fP.
|
string \fIs\fP of any of the bytes in the string \fIaccept\fP.
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
The
|
The
|
||||||
.BR strpbrk ()
|
.BR strpbrk ()
|
||||||
function returns a pointer to the character in
|
function returns a pointer to the byte in
|
||||||
\fIs\fP that matches one of the characters in \fIaccept\fP, or NULL
|
\fIs\fP that matches one of the bytes in \fIaccept\fP, or NULL
|
||||||
if no such character is found.
|
if no such byte is found.
|
||||||
.SH "CONFORMING TO"
|
.SH "CONFORMING TO"
|
||||||
SVr4, 4.3BSD, C89, C99.
|
SVr4, 4.3BSD, C89, C99.
|
||||||
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
||||||
|
|
|
@ -27,7 +27,7 @@
|
||||||
.\" Modified Sat Jul 24 17:57:50 1993 by Rik Faith (faith@cs.unc.edu)
|
.\" Modified Sat Jul 24 17:57:50 1993 by Rik Faith (faith@cs.unc.edu)
|
||||||
.TH STRSPN 3 2010-09-20 "" "Linux Programmer's Manual"
|
.TH STRSPN 3 2010-09-20 "" "Linux Programmer's Manual"
|
||||||
.SH NAME
|
.SH NAME
|
||||||
strspn, strcspn \- search a string for a set of characters
|
strspn, strcspn \- search a string for a set of bytes
|
||||||
.SH SYNOPSIS
|
.SH SYNOPSIS
|
||||||
.nf
|
.nf
|
||||||
.B #include <string.h>
|
.B #include <string.h>
|
||||||
|
@ -39,25 +39,25 @@ strspn, strcspn \- search a string for a set of characters
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
The
|
The
|
||||||
.BR strspn ()
|
.BR strspn ()
|
||||||
function calculates the length of the initial
|
function calculates the length (in bytes) of the initial
|
||||||
segment of \fIs\fP which consists entirely of characters in
|
segment of \fIs\fP which consists entirely of bytes in
|
||||||
\fIaccept\fP.
|
\fIaccept\fP.
|
||||||
.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 characters not in
|
segment of \fIs\fP which consists entirely of bytes not in
|
||||||
\fIreject\fP.
|
\fIreject\fP.
|
||||||
.SH "RETURN VALUE"
|
.SH "RETURN VALUE"
|
||||||
The
|
The
|
||||||
.BR strspn ()
|
.BR strspn ()
|
||||||
function returns the number of characters in
|
function returns the number of bytes in
|
||||||
the initial segment of \fIs\fP which consist only of characters
|
the initial segment of \fIs\fP which consist only of bytes
|
||||||
from \fIaccept\fP.
|
from \fIaccept\fP.
|
||||||
.PP
|
.PP
|
||||||
The
|
The
|
||||||
.BR strcspn ()
|
.BR strcspn ()
|
||||||
function returns the number of characters in
|
function returns the number of bytes in
|
||||||
the initial segment of \fIs\fP which are not in the string
|
the initial segment of \fIs\fP which are not in the string
|
||||||
\fIreject\fP.
|
\fIreject\fP.
|
||||||
.SH "CONFORMING TO"
|
.SH "CONFORMING TO"
|
||||||
|
|
|
@ -58,7 +58,7 @@ specified in \fIstr\fP.
|
||||||
In each subsequent call that should parse the same string,
|
In each subsequent call that should parse the same string,
|
||||||
\fIstr\fP should be NULL.
|
\fIstr\fP should be NULL.
|
||||||
|
|
||||||
The \fIdelim\fP argument specifies a set of characters that
|
The \fIdelim\fP 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 \fIdelim\fP in successive
|
||||||
calls that parse the same string.
|
calls that parse the same string.
|
||||||
|
@ -67,14 +67,14 @@ Each call to
|
||||||
.BR strtok ()
|
.BR strtok ()
|
||||||
returns a pointer to a
|
returns a pointer to a
|
||||||
null-terminated string containing the next token.
|
null-terminated string containing the next token.
|
||||||
This string does not include the delimiting character.
|
This string does not include the delimiting byte.
|
||||||
If no more tokens are found,
|
If no more tokens are found,
|
||||||
.BR strtok ()
|
.BR strtok ()
|
||||||
returns NULL.
|
returns NULL.
|
||||||
|
|
||||||
A sequence of two or more contiguous delimiter characters in
|
A sequence of two or more contiguous delimiter bytes in
|
||||||
the parsed string is considered to be a single delimiter.
|
the parsed string is considered to be a single delimiter.
|
||||||
Delimiter characters at the start or end of the string are ignored.
|
Delimiter bytes at the start or end of the string are ignored.
|
||||||
Put another way: the tokens returned by
|
Put another way: the tokens returned by
|
||||||
.BR strtok ()
|
.BR strtok ()
|
||||||
are always nonempty strings.
|
are always nonempty strings.
|
||||||
|
@ -123,7 +123,7 @@ These functions modify their first argument.
|
||||||
.IP *
|
.IP *
|
||||||
These functions cannot be used on constant strings.
|
These functions cannot be used on constant strings.
|
||||||
.IP *
|
.IP *
|
||||||
The identity of the delimiting character is lost.
|
The identity of the delimiting byte is lost.
|
||||||
.IP *
|
.IP *
|
||||||
The
|
The
|
||||||
.BR strtok ()
|
.BR strtok ()
|
||||||
|
@ -136,9 +136,9 @@ The program below uses nested loops that employ
|
||||||
.BR strtok_r ()
|
.BR strtok_r ()
|
||||||
to break a string into a two-level hierarchy of tokens.
|
to break a string into a two-level hierarchy of tokens.
|
||||||
The first command-line argument specifies the string to be parsed.
|
The first command-line argument specifies the string to be parsed.
|
||||||
The second argument specifies the delimiter character(s)
|
The second argument specifies the delimiter byte(s)
|
||||||
to be used to separate that string into "major" tokens.
|
to be used to separate that string into "major" tokens.
|
||||||
The third argument specifies the delimiter character(s)
|
The third argument specifies the delimiter byte(s)
|
||||||
to be used to separate the "major" tokens into subtokens.
|
to be used to separate the "major" tokens into subtokens.
|
||||||
.PP
|
.PP
|
||||||
An example of the output produced by this program is the following:
|
An example of the output produced by this program is the following:
|
||||||
|
|
|
@ -46,7 +46,7 @@ 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 characters of the transformed string are placed in
|
The first \fIn\fP bytes of the transformed string are placed in
|
||||||
\fIdest\fP.
|
\fIdest\fP.
|
||||||
The transformation is based on the program's current
|
The transformation is based on the program's current
|
||||||
locale for category \fBLC_COLLATE\fP. (See
|
locale for category \fBLC_COLLATE\fP. (See
|
||||||
|
|
Loading…
Reference in New Issue