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:
Michael Kerrisk 2012-05-04 16:15:02 +12:00
parent c95b6ae1ce
commit a00b7454b8
13 changed files with 36 additions and 36 deletions

View File

@ -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

View File

@ -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 ()

View File

@ -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.

View File

@ -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 ()

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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"

View File

@ -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"

View File

@ -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"

View File

@ -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"

View File

@ -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:

View File

@ -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