LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

stpcpy.3, stpncpy.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wctob.3, wcwidth.3, wprintf.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:17:14 +02:00
parent 5049da5bef
commit e4a0d6cb39
8 changed files with 200 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
man3/stpcpy.3
View File

@ -53,15 +53,20 @@ _GNU_SOURCE
.SH DESCRIPTION
The
.BR stpcpy ()
function copies the string pointed to by \fIsrc\fP
function copies the string pointed to by
.I src
(including the terminating null byte (\(aq\\0\(aq)) to the array pointed to by
\fIdest\fP.
.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.
.SH RETURN VALUE
.BR stpcpy ()
returns a pointer to the \fBend\fP of the string
\fIdest\fP (that is, the address of the terminating null byte)
returns a pointer to the
.B end
of the string
.I dest
(that is, the address of the terminating null byte)
rather than the beginning.
.SH CONFORMING TO
This function was added to POSIX.1-2008.
@ -76,8 +81,13 @@ This function may overrun the buffer
.SH EXAMPLE
For example, this program uses
.BR stpcpy ()
to concatenate \fBfoo\fP and
\fBbar\fP to produce \fBfoobar\fP, which it then prints.
to concatenate
.B foo
and
.B bar
to produce
.BR foobar ,
which it then prints.
.in +4n
.nf

51
man3/stpncpy.3
View File

@ -42,27 +42,52 @@ _GNU_SOURCE
.SH DESCRIPTION
The
.BR stpncpy ()
function copies at most \fIn\fP characters from the string
pointed to by \fIsrc\fP, including the terminating null byte (\(aq\\0\(aq),
to the array pointed to by \fIdest\fP.
Exactly \fIn\fP characters are written at
\fIdest\fP.
If the length \fIstrlen(src)\fP is smaller than \fIn\fP, the
remaining characters in the array pointed to by \fIdest\fP are filled
function copies at most
.I n
characters from the string
pointed to by
.IR src ,
including the terminating null byte (\(aq\\0\(aq),
to the array pointed to by
.IR dest .
Exactly
.I n
characters are written at
.IR dest .
If the length
.I strlen(src)
is smaller than
.IR n ,
the
remaining characters in the array pointed to by
.I dest
are filled
with null bytes (\(aq\\0\(aq),
If the length \fIstrlen(src)\fP is greater or equal to
\fIn\fP, the string pointed to by \fIdest\fP will
If the length
.I strlen(src)
is greater or equal to
.IR n ,
the string pointed to by
.I dest
will
not be null-terminated.
.PP
The strings may not overlap.
.PP
The programmer must ensure that there is room for at least \fIn\fP characters
at \fIdest\fP.
The programmer must ensure that there is room for at least
.I n
characters
at
.IR dest .
.SH RETURN VALUE
.BR stpncpy ()
returns a pointer to the terminating null byte
in \fIdest\fP, or, if \fIdest\fP is not null-terminated,
\fIdest + n\fP.
in
.IR dest ,
or, if
.I dest
is not null-terminated,
.IR "dest + n" .
.SH CONFORMING TO
This function was added to POSIX.1-2008.
Before that, it was a GNU extension.

14
man3/wcpcpy.3
View File

@ -46,20 +46,24 @@ The
function is the wide-character equivalent of the
.BR stpcpy (3)
function.
It copies the wide-character string pointed to by \fIsrc\fP,
It copies the wide-character string pointed to by
.IR src ,
including the terminating null wide character (L\(aq\\0\(aq),
to the array pointed to by
\fIdest\fP.
.IR dest .
.PP
The strings may not overlap.
.PP
The programmer must ensure that there
is room for at least \fIwcslen(src)+1\fP
wide characters at \fIdest\fP.
is room for at least
.IR wcslen(src)+1
wide characters at
.IR dest .
.SH RETURN VALUE
.BR wcpcpy ()
returns a pointer to the end of the wide-character string
\fIdest\fP, that is, a pointer to the terminating null wide character.
.IR dest ,
that is, a pointer to the terminating null wide character.
.SH CONFORMING TO
POSIX.1-2008.
.SH SEE ALSO

45
man3/wcpncpy.3
View File

@ -48,27 +48,48 @@ function is the wide-character equivalent
of the
.BR stpncpy (3)
function.
It copies at most \fIn\fP wide characters from the wide-character
string pointed to by \fIsrc\fP,
It copies at most
.I n
wide characters from the wide-character
string pointed to by
.IR src ,
including the terminating null wide (L\(aq\\0\(aq),
to the array pointed to by \fIdest\fP.
Exactly \fIn\fP wide characters are
written at \fIdest\fP.
If the length \fIwcslen(src)\fP is smaller than \fIn\fP,
to the array pointed to by
.IR dest .
Exactly
.I n
wide characters are
written at
.IR dest .
If the length
.IR wcslen(src)
is smaller than
.IR n ,
the remaining wide characters in the array pointed to
by \fIdest\fP are filled with L\(aq\\0\(aq characters.
If the length \fIwcslen(src)\fP is greater or equal
to \fIn\fP, the string pointed to by \fIdest\fP will
by
.I dest
are filled with L\(aq\\0\(aq characters.
If the length
.IR wcslen(src)
is greater or equal
to
.IR n ,
the string pointed to by
.I dest
will
not be L\(aq\\0\(aq terminated.
.PP
The strings may not overlap.
.PP
The programmer must ensure that there is room for at least \fIn\fP wide
characters at \fIdest\fP.
The programmer must ensure that there is room for at least
.I n
wide
characters at
.IR dest .
.SH RETURN VALUE
.BR wcpncpy ()
returns a pointer to the last wide character written, that is,
\fIdest + n \- 1\fP.
.IR dest + n \- 1" .
.SH CONFORMING TO
POSIX.1-2008.
.SH SEE ALSO

71
man3/wcrtomb.3
View File

@ -23,37 +23,60 @@ wcrtomb \- convert a wide character to a multibyte sequence
.BI "size_t wcrtomb(char *" s ", wchar_t " wc ", mbstate_t *" ps );
.fi
.SH DESCRIPTION
The main case for this function is when \fIs\fP is
not NULL and \fIwc\fP is not a null wide character (L\(aq\\0\(aq).
The main case for this function is when
.I s
is
not NULL and
.I wc
is not a null wide character (L\(aq\\0\(aq).
In this case, the
.BR wcrtomb ()
function
converts the wide character \fIwc\fP
converts the wide character
.I wc
to its multibyte representation and stores it
at the beginning of the character
array pointed to by \fIs\fP.
It updates the shift state \fI*ps\fP, and
array pointed to by
.IR s .
It updates the shift state
.IR *ps ,
and
returns the length of said multibyte representation,
that is, the number of bytes
written at \fIs\fP.
written at
.IR s .
.PP
A different case is when \fIs\fP is not NULL,
but \fIwc\fP is a null wide character (L\(aq\\0\(aq).
A different case is when
.I s
is not NULL,
but
.I wc
is a null wide character (L\(aq\\0\(aq).
In this
case the
.BR wcrtomb ()
function stores at
the character array pointed to by
\fIs\fP the shift sequence needed to
bring \fI*ps\fP back to the initial state,
.I s
the shift sequence needed to
bring
.I *ps
back to the initial state,
followed by a \(aq\\0\(aq byte.
It updates the shift state \fI*ps\fP (i.e., brings
It updates the shift state
.I *ps
(i.e., brings
it into the initial state),
and returns the length of the shift sequence plus
one, that is, the number of bytes written at \fIs\fP.
one, that is, the number of bytes written at
.IR s .
.PP
A third case is when \fIs\fP is NULL.
In this case \fIwc\fP is ignored,
A third case is when
.I s
is NULL.
In this case
.I wc
is ignored,
and the function effectively returns
wcrtomb(buf, L\(aq\\0\(aq, ps)
@ -62,7 +85,9 @@ where
.I buf
is an internal anonymous buffer.
.PP
In all of the above cases, if \fIps\fP is a NULL pointer, a static anonymous
In all of the above cases, if
.I ps
is a NULL pointer, a static anonymous
state known only to the
.BR wcrtomb ()
function is used instead.
@ -71,11 +96,17 @@ The
.BR wcrtomb ()
function returns the number of
bytes that have been or would
have been written to the byte array at \fIs\fP.
If \fIwc\fP can not be
have been written to the byte array at
.IR s .
If
.I wc
can not be
represented as a multibyte sequence (according to the current locale),
.I (size_t)\ \-1
is returned, and \fIerrno\fP set to \fBEILSEQ\fP.
is returned, and
.I errno
set to
.BR EILSEQ .
.SH CONFORMING TO
C99.
.SH NOTES
@ -86,6 +117,8 @@ depends on the
category of the
current locale.
.PP
Passing NULL as \fIps\fP is not multithread safe.
Passing NULL as
.I ps
is not multithread safe.
.SH SEE ALSO
.BR wcsrtombs (3)

11
man3/wctob.3
View File

@ -27,7 +27,9 @@ The
.BR wctob ()
function tests whether
the multibyte representation of the
wide character \fIc\fP, starting in the initial state, consists of a single
wide character
.IR c ,
starting in the initial state, consists of a single
byte.
If so, it is returned as an
.IR "unsigned char" .
@ -40,8 +42,11 @@ multibyte characters.
.SH RETURN VALUE
The
.BR wctob ()
function returns the single-byte representation of \fIc\fP,
if it exists, of \fBEOF\fP otherwise.
function returns the single-byte representation of
.IR c ,
if it exists, of
.B EOF
otherwise.
.SH CONFORMING TO
C99.
.SH NOTES

14
man3/wcwidth.3
View File

@ -26,16 +26,22 @@ wcwidth \- determine columns needed for a wide character
The
.BR wcwidth ()
function returns the number of columns
needed to represent the wide character \fIc\fP.
If \fIc\fP is a printable wide character, the value
needed to represent the wide character
.IR c .
If
.I c
is a printable wide character, the value
is at least 0.
If \fIc\fP is null wide character (L\(aq\\0\(aq), the value is 0.
If
.I c
is null wide character (L\(aq\\0\(aq), the value is 0.
Otherwise \-1 is returned.
.SH RETURN VALUE
The
.BR wcwidth ()
function returns the number of
column positions for \fIc\fP.
column positions for
.IR c .
.SH CONFORMING TO
POSIX.1-2001.

45
man3/wprintf.3
View File

@ -72,8 +72,10 @@ The
and
.BR vwprintf ()
functions
perform wide-character output to \fIstdout\fP.
\fIstdout\fP must not be byte oriented; see
perform wide-character output to
.IR stdout .
.I stdout
must not be byte oriented; see
.BR fwide (3)
for more information.
.PP
@ -82,8 +84,10 @@ The
and
.BR vfwprintf ()
functions
perform wide-character output to \fIstream\fP.
\fIstream\fP must not be byte oriented; see
perform wide-character output to
.IR stream .
.I stream
must not be byte oriented; see
.BR fwide (3)
for more information.
.PP
@ -95,8 +99,11 @@ functions
perform wide-character output
to an array of wide characters.
The programmer must ensure that there is
room for at least \fImaxlen\fP wide
characters at \fIwcs\fP.
room for at least
.I maxlen
wide
characters at
.IR wcs .
.PP
These functions are like
the
@ -110,7 +117,9 @@ functions except for the
following differences:
.TP
.B \(bu
The \fIformat\fP string is a wide-character string.
The
.I format
string is a wide-character string.
.TP
.B \(bu
The output consists of wide characters, not bytes.
@ -119,7 +128,9 @@ The output consists of wide characters, not bytes.
.BR swprintf ()
and
.BR vswprintf ()
take a \fImaxlen\fP argument,
take a
.I maxlen
argument,
.BR sprintf (3)
and
.BR vsprintf (3)
@ -127,10 +138,16 @@ do not.
.RB ( snprintf (3)
and
.BR vsnprintf (3)
take a \fImaxlen\fP argument, but these functions do not return \-1 upon
take a
.I maxlen
argument, but these functions do not return \-1 upon
buffer overflow on Linux.)
.PP
The treatment of the conversion characters \fBc\fP and \fBs\fP is different:
The treatment of the conversion characters
.BR c
and
.B s
is different:
.TP
.B c
If no
@ -204,7 +221,9 @@ on the
category of the
current locale.
.PP
If the \fIformat\fP string contains non-ASCII wide characters, the program
If the
.I format
string contains non-ASCII wide characters, the program
will work correctly only if the
.B LC_CTYPE
category of the current locale at
@ -221,7 +240,9 @@ platforms don't do this.
Also, the use of C99 universal character names
of the form \\unnnn does not solve this problem.)
Therefore, in
internationalized programs, the \fIformat\fP string should consist of ASCII
internationalized programs, the
.I format
string should consist of ASCII
wide characters only, or should be constructed at run time in an
internationalized way (e.g., using
.BR gettext (3)