Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
curl_printf(3)		   Library Functions Manual		curl_printf(3)

NAME
       curl_maprintf,	  curl_mfprintf,     curl_mprintf,     curl_msnprintf,
       curl_msprintf, curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvs-
       nprintf,	curl_mvsprintf - formatted output conversion

SYNOPSIS
       #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);

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 applica-
       tions.

       Functions in the	curl_mprintf() family produce output  according	 to  a
       format	as   described	 below.	  The	functions  curl_mprintf()  and
       curl_mvprintf() write output to stdout,	the  standard  output  stream;
       curl_mfprintf()	and  curl_mvfprintf() write output to the given	output
       stream;	curl_msprintf(),   curl_msnprintf(),   curl_mvsprintf(),   and
       curl_mvsnprintf() write to the character	string buffer.

       The  functions  curl_msnprintf()	 and  curl_mvsnprintf()	 write at most
       maxlength bytes (including the terminating null byte ('0')) to buffer.

       The  functions  curl_mvprintf(),	 curl_mvfprintf(),   curl_mvsprintf(),
       curl_mvsnprintf()  are  equivalent  to  the  functions  curl_mprintf(),
       curl_mfprintf(),	curl_msprintf(), curl_msnprintf(),  respectively,  ex-
       cept  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 curl_maprintf() and curl_mvaprintf()  return  the	output
       string as pointer to a newly allocated memory area. The returned	string
       must be curl_free(3)ed 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  out-
       put.

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	intro-
       duced  by the character %, and ends with	a conversion specifier.	In be-
       tween there may be (in this order) zero or more flags, an optional min-
       imum field width, an optional precision and an  optional	 length	 modi-
       fier.

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, in-
       dexed 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 con-
       versions	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 arguments	specified  using  '$';
       for  example,  if arguments 1 and 3 are specified, argument 2 must also
       be specified somewhere in the format string.

Flag characters
       The character % is followed by zero or more of the following flags:

       #      The value	should be converted to its "alternate form".

       0      The value	should be zero padded.

       -      The converted value is to	be left	adjusted on the	 field	bound-
	      ary.  (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.

       (space)
	      (a space:	' ') A blank should be left before a  positive	number
	      (or empty	string)	produced by a signed conversion.

       +      A	sign (+	or -) should always be placed before a number produced
	      by a signed conversion. By default, a sign is used only for neg-
	      ative numbers. A '+' overrides a space if	both are used.

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 gets	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  ar-
       gument, respectively, 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.

Precision
       An  optional precision in the form of a period ('.') followed by	an op-
       tional 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,  re-
       spectively,  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 d, i, o,	u, x, and X conversions, the number of
       digits to appear	after the radix	character for a, A, e,	E,  f,	and  F
       conversions,  the maximum number	of significant digits for g and	G con-
       versions, or the	maximum	number of characters  to  be  printed  from  a
       string for s and	S conversions.

Length modifier
       h      A	 following  integer  conversion	 corresponds to	a short	or un-
	      signed short argument.

       l      (ell) A following	integer	conversion corresponds to  a  long  or
	      unsigned	long argument, or a following n	conversion corresponds
	      to a pointer to a	long argument

       ll     (ell-ell). A following integer conversion	corresponds to a  long
	      long or unsigned long long argument, or a	following n conversion
	      corresponds to a pointer to a long long argument.

       q      A	synonym	for ll.

       L      A	 following a, A, e, E, f, F, g,	or G conversion	corresponds to
	      a	long double argument.

       z      A	following  integer  conversion	corresponds  to	 a  size_t  or
	      ssize_t argument.

Conversion specifiers
       A  character  that  specifies the type of conversion to be applied. The
       conversion specifiers and their meanings	are:

       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.

       o, u, x,	X
	      The unsigned int argument	is converted to	 unsigned  octal  (o),
	      unsigned	decimal	 (u),  or unsigned hexadecimal (x and X) nota-
	      tion. The	letters	abcdef are used	for x conversions; the letters
	      ABCDEF are used for X 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  ze-
	      ros.  The	 default precision is 1. When 0	is printed with	an ex-
	      plicit precision 0, the output is	empty.

       e, E   The  double  argument  is	 rounded  and  output  in  the	 style
	      "[-]d.ddde{+|-}dd"

       f, F   The double argument is rounded and output	to decimal notation in
	      the style	"[-]ddd.ddd".

       g, G   The double argument is converted in style	f or e.

       c      The  int	argument is converted to an unsigned char, and the re-
	      sulting character	is written.

       s      The const	char * argument	is expected to be a pointer to an  ar-
	      ray 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 spec-
	      ified 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.

       p      The void * pointer argument is printed in	hexadecimal.

       n      The number of characters written so far is stored	into the inte-
	      ger pointed to by	the corresponding argument.

       %      A	'%' symbol is written. No argument is converted.

PROTOCOLS
       This functionality affects all supported	protocols

EXAMPLE
       const char *name	= "John";

       int main(void)
       {
	 curl_mprintf("My name is %s\n", name);
	 curl_mprintf("Pi is almost %f\n", (double)25.0/8);
       }

AVAILABILITY
       Added in	curl 7.1

RETURN VALUE
       The  curl_maprintf  and	curl_mvaprintf 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.

SEE ALSO
       fprintf(3), printf(3), sprintf(3), vprintf(3)

libcurl				  2025-06-03			curl_printf(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=curl_mprintf&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help