strfmon(3)						     Library Functions Manual							strfmon(3)

NAME

       strfmon - Formats monetary strings

LIBRARY

       Standard C Library (libc)

SYNOPSIS

       #include <monetary.h>

       ssize_t strfmon(
	       char *s,
	       size_t maxsize,
	       const char *format
	       [,double value]...);

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       strfmon(): XSH5.0

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Contains  the  output  of  the strfmon() function.  Specifies the maximum number of bytes (including the null terminating byte) that may be
       placed in the s parameter.  Contains characters and conversion specifications.  Specifies the double data to be converted according to  the
       format parameter.

DESCRIPTION

       The  strfmon()  function  converts numeric values to monetary strings according to the specifications in the format parameter. The function
       converts the double-precision floating-point value parameters under the control of the format parameter and stores the result in the  array
       specified by the s parameter.

       The  format  parameter is a character string that contains two types of objects: Literal characters, which are copied to the output stream.
       Conversion specifications, each of which causes zero or more items to be fetched from the value parameter list.

       If there are insufficient parameters for the format parameter, the results are undefined. If parameters remain after the  format  parameter
       is exhausted, the excess parameters are ignored.

   Conversion Specifications
       A  conversion  specification  consists  of  a  %  (percent  sign) character, optional flags, optional field width, optional left precision,
       optional right precision, and a required conversion character that determines the conversion to be performed.

       Each conversion specification in the format parameter has the following syntax:

       A % (percent sign).  Zero or more optional flags can be specified to control the conversion. The flag characters and their meanings are	as
       follows:  An = (equal sign) followed by a single character that specifies the numeric fill character. The default numeric fill character is
       the space character. This flag does not affect field-width filling, which always uses the space character.  This flag is ignored  unless  a
       left precision is specified.  The ^ (circumflex) flag suppresses the grouping character when formatting the currency amount. The default is
       to group the digits and separate them with the grouping character if defined for the current locale.  The + (plus) character specifies that
       the   locale's  equivalent of + and - are used to indicate positive and negative values. You cannot specify both the + (plus) character and
       the ( (left-parenthesis) character. If you specify neither, the style specified in the locale for +  is	used.	The  (	(left-parenthesis)
       character specifies that the locale's equivalent of enclosing negative amounts within parentheses is used to indicate positive and negative
       values. See also the description of the + character.  The ! (exclamation mark) character suppresses the currency  symbol  from  the  output
       conversion.   The  -  (hyphen) character specifies that the field is left justified within the minimum field width rather than right justi-
       fied. This flag is ignored unless a minimum field width is specified.  An optional decimal digit string w that specifies  a  minimum  field
       width  in  which  the result of the conversion is right justified.  If the - (hyphen) flag is specified, the result is left justified.  The
       default value for w is 0 (zero).  An optional left precision consisting of a # (number sign), followed by a decimal  digit  string  n.  The
       decimal	digit  string  specifies  the  maximum number of digits to be formatted to the left of the radix character.  This option causes an
       amount to be formatted as if it has the number of digits specified by the n digit string.  If more than n  digit  positions  are  required,
       this  option  is ignored. Digit positions in excess of those required are filled with the numeric fill character set with the =f flag.  The
       #n option can be specified to keep the formatted output from multiple calls to the strfmon() function aligned  in  the  same  columns.  The
       option can also be used in conjunction with the =f flag to fill unused positions with a special character (for example, $***123.45).

	      If  grouping  is	defined  for  the current locale and has not been suppressed with the ^ (circumflex) flag, grouping separators are
	      inserted before the fill characters (if any) are added.  Therefore, grouping characters are not applied to  instances  of  the  fill
	      character,  even	when the fill character is a digit. For the following example in which the fill character is zero, assume that the
	      locale specifies that the thousands grouping character is a comma (,), that the grouping character should be delimit each  group	of
	      three characters to the left of the radix character, and that the radix character is the period (.):

	      strcpy(format,"%=0#10i");   monetary_value  =  1.23;  retval  =  strfmon(str,STR_SIZE,format,  monetary_value);  printf("(%s,%f)	=>
	      %sen",format,monetary_value, str);

	      This example prints 0000000000001.23 rather than 0,000,000,001.23.  An optional right precision consisting of a . (period)  followed
	      by  a  decimal digit string p that specifies the number of digits after the radix character. If the value of the p digit string is 0
	      (zero), no radix character is used. If a right precision is not specified, a default specified by the current locale  is	used.  The
	      amount  being  formatted	is  rounded to the specified number of digits prior to formatting.  A character that indicates the type of
	      conversion to be applied: No parameter is converted; the conversion specification %% (double percent sign) produces a  single  %	in
	      the  output string.  The double parameter is formatted according to the current locale's international currency format; for example,
	      in a U.S. locale: USD 1,234.56.  The double parameter is formatted according to the current locale's national currency  format;  for
	      example, in a U.S. locale: $1,234.56.

       The  following  table lists the default values used by the strfmon() function when there are no values defined in the locale for these mem-
       bers of the lconv structure. These are the defaults for the POSIX (C) locale. For all other lconv members, such as mon_thousands_sep, there
       are no defaults.

       ------------------------------------------------------------------
       lconv Structure	   Explanation		   Default Value
       ------------------------------------------------------------------
       mon_decimal_point   Radix character	   . (period)
       ------------------------------------------------------------------
       negative_sign	   Character to indicate   - (hyphen)
			   negative values
       ------------------------------------------------------------------
       int_frac_digits	   Default right	   2
			   precision for %i
       ------------------------------------------------------------------
       frac_digits	   Default right	   2
			   precision for %n
       ------------------------------------------------------------------
       left_parenthesis    Characters used	   ( (left parenthesis)
			   for ( flag
       ------------------------------------------------------------------
       right_parenthesis   Characters used	   ) (right parenthesis)
			   for ) flag
       ------------------------------------------------------------------

EXAMPLES

       The following table lists conversion specifications and the output.

       ------------------------------------------------------------------
       Conv.	 Output in	    Output in
       Spec.	 a US Locale	    C Locale	    Explanation
       ------------------------------------------------------------------
       %n		$100.35 	 100.35     Default
		      $1,225.15-       -1225.15     national format
       ------------------------------------------------------------------
       %i	     USD 100.35 	 100.35     Default
		   USD 1,225.15-       -1225.15     international format
       ------------------------------------------------------------------
       %(#6.3n	    $  9,876.543	9876.543    Explicit
		   ($ 25,832.000)    ( 25832.000)   left and right
						    precision with
						    parentheses
						    for negative values
       ------------------------------------------------------------------
       %=*#7n	  $****4,379.25      ***4379.25     Fill

		 -$****4,379.25     -***4379.25     character
       ------------------------------------------------------------------
       %=0#7n	   $0004,379.25      0004379.25     Zero fill
		   $0004,379.25-    -0004379.25
       ------------------------------------------------------------------
       %!.0n	       3,225		3225	    Suppress
		       3,225-	       -3225	    currency symbol
						    and round to
						    integer
       ------------------------------------------------------------------

RETURN VALUES

       If successful, and if the number of resulting bytes (including the terminating null byte) is not more than the number of bytes specified by
       the maxsize parameter, the strfmon() function returns the number of bytes placed into the array pointed to by the s parameter.  The  termi-
       nating  null  byte  is not included in the return count. Otherwise, the function returns -1, and the contents of the s array are indetermi-
       nate.

ERRORS

       If one of the following conditions occur, the strfmon() function sets errno to the corresponding value: Conversion stopped due to  lack	of
       space in the buffer.

RELATED INFORMATION

       Functions: localeconv(3), nl_langinfo(3), scanf(3), setlocale(3), strftime(3), wscanf(3)

       Files: locale(4)

       Others: i18n_intro(5), l10n_intro(5), standards(5)

       Writing Software for the International Market delim off

																	strfmon(3)