mirror of
https://github.com/curl/curl.git
synced 2024-12-09 06:30:06 +08:00
230bb3e278
Make all libcurl related options use .nf (no fill) for the SYNOPSIS section - for consistent look. roffit then renders that section using <pre> (monospace font) in html for the website. Extended manpage-syntax (test 1173) with a basic check for it. Closes #8062
253 lines
11 KiB
Groff
253 lines
11 KiB
Groff
.\" **************************************************************************
|
||
.\" * _ _ ____ _
|
||
.\" * Project ___| | | | _ \| |
|
||
.\" * / __| | | | |_) | |
|
||
.\" * | (__| |_| | _ <| |___
|
||
.\" * \___|\___/|_| \_\_____|
|
||
.\" *
|
||
.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
|
||
.\" *
|
||
.\" * This software is licensed as described in the file COPYING, which
|
||
.\" * you should have received as part of this distribution. The terms
|
||
.\" * are also available at https://curl.se/docs/copyright.html.
|
||
.\" *
|
||
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
||
.\" * copies of the Software, and permit persons to whom the Software is
|
||
.\" * furnished to do so, under the terms of the COPYING file.
|
||
.\" *
|
||
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
||
.\" * KIND, either express or implied.
|
||
.\" *
|
||
.\" **************************************************************************
|
||
.TH curl_printf 3 "30 April 2004" "libcurl 7.12" "libcurl Manual"
|
||
.SH NAME
|
||
curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf
|
||
curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf,
|
||
curl_mvsprintf - formatted output conversion
|
||
.SH SYNOPSIS
|
||
.nf
|
||
#include <curl/mprintf.h>
|
||
|
||
int curl_mprintf(const char *format, ...);
|
||
int curl_mfprintf(FILE *fd, const char *format, ...);
|
||
int curl_msprintf(char *buffer, const char *format, ...);
|
||
int curl_msnprintf(char *buffer, size_t maxlength, const char *format, ...);
|
||
int curl_mvprintf(const char *format, va_list args);
|
||
int curl_mvfprintf(FILE *fd, const char *format, va_list args);
|
||
int curl_mvsprintf(char *buffer, const char *format, va_list args);
|
||
int curl_mvsnprintf(char *buffer, size_t maxlength, const char *format,
|
||
va_list args);
|
||
char *curl_maprintf(const char *format , ...);
|
||
char *curl_mvaprintf(const char *format, va_list args);
|
||
.fi
|
||
.SH DESCRIPTION
|
||
These functions produce output according to the format string and given
|
||
arguments. They are mostly clones of the well-known C-style functions but
|
||
there are slight differences in behavior.
|
||
|
||
We discourage users from using any of these functions in new applications.
|
||
|
||
Functions in the curl_mprintf() family produce output according to a format as
|
||
described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP
|
||
write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and
|
||
\fBcurl_mvfprintf()\fP write output to the given output stream;
|
||
\fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and
|
||
\fBcurl_mvsnprintf()\fP write to the character string \fBbuffer\fP.
|
||
|
||
The functions \fBcurl_msnprintf()\fP and \fBcurl_mvsnprintf()\fP write at most
|
||
\fImaxlength\fP bytes (including the terminating null byte ('\\0')) to
|
||
\fIbuffer\fP.
|
||
|
||
The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP,
|
||
\fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the
|
||
functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP,
|
||
\fBcurl_msnprintf()\fP, respectively, except that they are called with a
|
||
va_list instead of a variable number of arguments. These functions do not
|
||
call the va_end macro. Because they invoke the va_arg macro, the value of ap
|
||
is undefined after the call.
|
||
|
||
The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the
|
||
output string as pointer to a newly allocated memory area. The returned string
|
||
must be \fIcurl_free(3)\fPed by the receiver.
|
||
|
||
All of these functions write the output under the control of a format string
|
||
that specifies how subsequent arguments are converted for output.
|
||
|
||
.SH FORMAT STRING
|
||
The format string is composed of zero or more directives: ordinary characters
|
||
(not %), which are copied unchanged to the output stream; and conversion
|
||
specifications, each of which results in fetching zero or more subsequent
|
||
arguments. Each conversion specification is introduced by the character %, and
|
||
ends with a conversion specifier. In between there may be (in this order) zero
|
||
or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional
|
||
\fIprecision\fP and an optional \fIlength modifier\fP.
|
||
|
||
.SH "The $ modifier"
|
||
The arguments must correspond properly with the conversion specifier. By
|
||
default, the arguments are used in the order given, where each '*' (see Field
|
||
width and Precision below) and each conversion specifier asks for the next
|
||
argument (and it is an error if insufficiently many arguments are given). One
|
||
can also specify explicitly which argument is taken, at each place where an
|
||
argument is required, by writing "%m$" instead of '%' and "*m$" instead
|
||
of '*', where the decimal integer m denotes the position in the argument list
|
||
of the desired argument, indexed starting from 1. Thus,
|
||
|
||
curl_mprintf("%*d", width, num);
|
||
|
||
and
|
||
|
||
curl_mprintf("%2$*1$d", width, num);
|
||
|
||
are equivalent. The second style allows repeated references to the same
|
||
argument.
|
||
|
||
If the style using '$' is used, it must be used throughout for all conversions
|
||
taking an argument and all width and precision arguments, but it may be mixed
|
||
with "%%" formats, which do not consume an argument. There may be no gaps in
|
||
the numbers of argu‐ ments specified using '$'; for example, if arguments 1
|
||
and 3 are specified, argument 2 must also be specified somewhere in the format
|
||
string.
|
||
|
||
.SH "Flag characters"
|
||
The character % is followed by zero or more of the following flags:
|
||
.TP
|
||
.B #
|
||
The value should be converted to its "alternate form".
|
||
.TP
|
||
.B 0
|
||
The value should be zero padded.
|
||
.TP
|
||
.B -
|
||
The converted value is to be left adjusted on the field boundary. (The
|
||
default is right justification.) The converted value is padded on the right
|
||
with blanks, rather than on the left with blanks or zeros. A '-' overrides a
|
||
\&'0' if both are given.
|
||
.TP
|
||
.B ' '
|
||
(a space) A blank should be left before a positive number (or empty string)
|
||
produced by a signed conversion.
|
||
.TP
|
||
.B +
|
||
A sign (+ or -) should always be placed before a number produced by a signed
|
||
conversion. By default, a sign is used only for negative numbers. A '+'
|
||
overrides a space if both are used.
|
||
.SH "Field width"
|
||
An optional decimal digit string (with nonzero first digit) specifying a
|
||
minimum field width. If the converted value has fewer characters than the
|
||
field width, it will be padded with spaces on the left (or right, if the
|
||
left-adjustment flag has been given). Instead of a decimal digit string one
|
||
may write "*" or "*m$" (for some decimal integer m) to specify that the field
|
||
width is given in the next argument, or in the m-th argument, respec‐ tively,
|
||
which must be of type int. A negative field width is taken as a '-' flag
|
||
followed by a positive field width. In no case does a nonexistent or small
|
||
field width cause truncation of a field; if the result of a conversion is
|
||
wider than the field width, the field is expanded to contain the conversion
|
||
result.
|
||
.SH "Precision"
|
||
An optional precision in the form of a period ('.') followed by an optional
|
||
decimal digit string. Instead of a decimal digit string one may write "*" or
|
||
"*m$" (for some decimal integer m) to specify that the precision is given in
|
||
the next argument, or in the m-th argument, respectively, which must be of
|
||
type int. If the precision is given as just '.', the precision is taken to be
|
||
zero. A negative precision is taken as if the precision were omitted. This
|
||
gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP,
|
||
\fBu\fP, \fBx\fP, and \fBX\fP conversions, the number of digits to appear
|
||
after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and
|
||
\fBF\fP conversions, the maximum number of significant digits for \fBg\fP and
|
||
\fBG\fP conversions, or the maximum number of characters to be printed from a
|
||
string for \fBs\fP and \fBS\fP conversions.
|
||
.SH "Length modifier"
|
||
.TP
|
||
.B h
|
||
A following integer conversion corresponds to a \fIshort\fP or \fIunsigned
|
||
short\fP argument.
|
||
.TP
|
||
.B l
|
||
(ell) A following integer conversion corresponds to a \fIlong\fP or
|
||
\fIunsigned long\fP argument, or a following n conversion corresponds to a
|
||
pointer to a long argument
|
||
.TP
|
||
.B ll
|
||
(ell-ell). A following integer conversion corresponds to a \fIlong long\fP or
|
||
\fIunsigned long long\fP argument, or a following n conversion corresponds to
|
||
a pointer to a long long argument.
|
||
.TP
|
||
.B q
|
||
A synonym for \fBll\fP.
|
||
.TP
|
||
.B L
|
||
A following a, A, e, E, f, F, g, or G conversion corresponds to a long double
|
||
argument.
|
||
.TP
|
||
.B z
|
||
A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP
|
||
argument.
|
||
.SH "Conversion specifiers"
|
||
A character that specifies the type of conversion to be applied. The
|
||
conversion specifiers and their meanings are:
|
||
.TP
|
||
.B d, i
|
||
The int argument is converted to signed decimal notation. The precision, if
|
||
any, gives the minimum number of digits that must appear; if the converted
|
||
value requires fewer digits, it is padded on the left with zeros. The default
|
||
precision is 1. When 0 is printed with an explicit precision 0, the output is
|
||
empty.
|
||
.TP
|
||
.B o, u, x, X
|
||
The unsigned int argument is converted to unsigned octal (o), unsigned decimal
|
||
(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters
|
||
abcdef are used for \fBx\fP conversions; the letters ABCDEF are used for
|
||
\fBX\fP conversions. The precision, if any, gives the minimum number of digits
|
||
that must appear; if the converted value requires fewer digits, it is padded
|
||
on the left with zeros. The default precision is 1. When 0 is printed with
|
||
an explicit precision 0, the output is empty.
|
||
.TP
|
||
.B e, E
|
||
The double argument is rounded and output in the style "[-]d.ddde±dd"
|
||
.TP
|
||
.B f, F
|
||
The double argument is rounded and output to decimal notiation in the style
|
||
[-]ddd.ddd.
|
||
.TP
|
||
.B g, G
|
||
The double argument is converted in style f or e.
|
||
.TP
|
||
.B c
|
||
The int argument is converted to an unsigned char, and the resulting character
|
||
is written.
|
||
.TP
|
||
.B s
|
||
The const char * argument is expected to be a pointer to an array of character
|
||
type (pointer to a string). Characters from the array are written up to (but
|
||
not including) a terminating null byte. If a precision is specified, no more
|
||
than the number specified are written. If a precision is given, no null byte
|
||
need be present; if the precision is not specified, or is greater than the
|
||
size of the array, the array must contain a terminating null byte.
|
||
.TP
|
||
.B p
|
||
The \fIvoid *\fP pointer argument is printed in hexadecimal.
|
||
.TP
|
||
.B n
|
||
The number of characters written so far is stored into the integer pointed to
|
||
by the corresponding argument.
|
||
.TP
|
||
.B %
|
||
A '%' is written. No argument is converted.
|
||
.SH EXAMPLE
|
||
.nf
|
||
mprintf("My name is %s\\n", name);
|
||
mprintf("Pi is almost %f\\n", 25/8);
|
||
.fi
|
||
.SH AVAILABILITY
|
||
These functions will be removed from the public libcurl API in the future. Do
|
||
not use them in new programs or projects.
|
||
.SH RETURN VALUE
|
||
The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to
|
||
a newly allocated string, or NULL if it failed.
|
||
|
||
All other functions return the number of characters actually printed
|
||
(excluding the null byte used to end output to strings). Note that this
|
||
sometimes differ from how the POSIX versions of these functions work.
|
||
.SH "SEE ALSO"
|
||
.BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) "
|