You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference
Previous     Contents     Next     

Chapter 20   Formatted Printing

NSPR contains formatted printing facilities modeled after ANSI C's stdlib offering. The routines offered are thread aware and do place extra burdens on the clients to deal with resource allocation and deallocation.

Formatting Specification
Output Functions
Scanning Function

Formatting Specification

The output functions translate internal values to characters under the control of a format string. The format string contains two types of objects: ordinary characters, which are copied to the output stream, and conversion specifications, each of which causes conversion and printing of the next successive argument of the calling function. Each conversion specification begins with a percent character (%) and ends with a conversion character. Between the percent and the conversion character there can be, in order:

  • A minus sign, which specifies left adjustment of the converted argument.

  • A number that specifies the minimum field width. The converted argument will be printed in a field at least this wide. If necessary, it will be padded on the left (or right, if left adjustment is called for) to make up the field width.

  • A period, which separates the field width from the precision.

  • A number, the precision, that specifies the maximum number of characters to be printed for a string, or the number of digits after the decimal point of a floating point value, or the minimum number of digits for an integer.

  • An h if the integer is to be printed as a 16 bit value, a l if 32 bits, or ll if 64 bits.

The conversion characters are shown in the following table.




Character

Argument Type

Printed as

d

 

 PRIntn

 

 Signed decimal number

 
o

 

 PRUintn

 

 Unsigned octal number

 
x, X

 

 PRUintn

 

 Unsigned hexadecimal number, lower and upper case, respectively

 
u

 

 PRUintn

 

 Unsigned decimal number

 
c

 

 PRInt8

 

 Single character

 
s

 

 char*

 

 Print characters from the string until '\0' or the number of characters given by the precision

 
f, g

 

 PRFloat64

 

 Double floating point number

 
p

 

 void*

 

 Pointer (implementation-dependent representation)

 

Output Functions

Output functions are:

PR_snprintf
PR_smprintf
PR_sprintf_append
PR_smprintf_free
PR_sxprintf
PR_fprintf

Each of these functions has a corresponding version implemented with a variable length argument list:

va_list Versions of Output Functions

PR_snprintf

Formats output into a fixed-size buffer.


Syntax 
PRUint32 PR_snprintf (
   char *out,
   PRUint32 outlen, 
   const char *fmt,
   ...);


Parameters
The function has these parameters:

out

The character buffer that will hold the result of the translation.

outlen

The length in bytes of the buffer.

fmt

The string that is used as the formatting specification.

...

An arbitrary number of parameters. The number and type of the parameters are governed by the fmt string.


Returns
Returns the length of the written output not including the NULL terminator, or
-1 if an error occurs.


Description
This function formats the specified parameters according to the specified format string, and stores the output in the specified buffer of the specified size. It guarantees that a NULL is at the end of the buffer.

PR_smprintf

Formats output into a buffer allocated at run time.


Syntax 
char* PR_smprintf (
   const char *fmt,
   ...);


Parameter
The function has these parameters:

fmt

The string that is used as the formatting specification.

...

An arbitrary number of parameters. The number and type of the parameters are governed by the fmt string.


Returns
If the translation is successful, returns a non-NULL character pointer. A NULL return value indicates an error in processing. Retrieve the reason for the error using PR_GetError.


Description
This function formats the specified parameters according to the specified format string, and returns the output in a character buffer. It guarantees that a NULL is at the end of the buffer.

This function is identical to PR_snprintf except that the output buffer is allocated by the runtime rather than passed into the function. If the function is successful, the returned buffer belongs to the caller. When it is no longer used, free it using PR_smprintf_free.

PR_sprintf_append

Appends a formatted string to an existing string.


Syntax 
char* PR_sprintf_append (
   char *last, 
   const char *fmt,
   ...);


Parameters
The function has these parameters:

last

A string that was previously returned from this function, or NULL for the first call.

fmt

The string that is used as the formatting specification.

...

An arbitrary number of parameters. The number and type of the parameters are governed by the fmt string.


Returns
If the transformation is successful, returns a non-NULL character pointer. The result should be treated as a new string. In case of error, returns NULL.


Description
This function formats the specified parameters according to the specified format string, and appends the translation to the specified existing string. The function returns a new character buffer containing the contents of the string passed in as the parameter last, plus the result of the current transformation.

If no string is specified, the function allocates a new character buffer. The function extends the buffer as needed, using standard heap allocators. If the value of last is not NULL, the function reallocates a new buffer sufficient to hold the existing string plus the result of the new translation, and deletes the passed string.

The buffer returned by the function belongs to the caller. When it is no longer used, free it using PR_smprintf_free.

PR_smprintf_free

Releases the string buffer returned by PR_smprintf.


Syntax 
void PR_smprintf_free (char *str);


Parameters
The function has this parameter:

str

A string buffer returned by a previous call to PR_smprintf.


Returns
Nothing


Description
This function frees the memory associated with the specified string buffer, which was allocated by a previous call to PR_smprintf or PR_sprintf_append. If the specified buffer was not allocated by one of these functions, the result is undefined.

PR_sxprintf

Formats output to a location determined by a callback function.


Syntax 
PRUint32 PR_sxprintf (
   PRStuffFunc f, 
   void *arg, 
   const char *fmt,
   ...);


Parameters
The function has these parameters:

f

The stuff function that will be called for each transformation indicated by the formatting string, fmt.

arg

A pointer to a client-managed object that possesses enough state to deal with the multiple calls to the stuff function. This argument is passed directly through and not interpreted by the runtime.

fmt

The string that is used as the formatting specification.

...

An arbitrary number of parameters. The number and type of the parameters are governed by the fmt string.


Returns
The total number of bytes in the transformed area, or 0xffffffff if the transformation fails.


Description
This function formats the specified parameters according to the specified format string, then calls the specified "stuff function," passing the transformed string and a pointer to an object that contains the state needed to handle that string.

The stuff function may be called more than once for each call to PR_sxprintf. Each call should return the number of bytes actually accepted by the stuff function for that particular call, or -1 if the function fails.

The stuff function must be supplied by the client, and must conform to the following signature: 

typedef PRIntn (*PRStuffFunc)
   (void *arg, const char *s, PRUint32 slen);

The stuff function has these parameters:

arg

A pointer to an object referenced by the caller of PR_sxprintf that contains sufficient state for the stuff function to know where to put the new transformed fragment.

s

A character buffer containing a transformed fragment that is to be added to the state of the object referenced by arg.

slen

The length of the buffer s.

PR_fprintf

Formats output into a file.


Syntax 
PRUint32 PR_fprintf (
   struct PRFileDesc* fd,
   const char *fmt,
   ...);


Parameters
The function has these parameters:

fd

A valid, open file descriptor.

fmt

The string that is used as the formatting specification.

...

An arbitrary number of parameters. The number and type of the parameters are governed by the fmt string.


Returns
Returns the total number of bytes written to the file descriptor, or 0xffffffff if the transformation fails. It is possible for some transformed bytes to be written to the file before the function fails.


Description
This function formats the specified parameters according to the specified format string, then directs the result of the transformation to the specified file descriptor using PR_Write. The output function may be called multiple times.

va_list Versions of Output Functions

The following function prototypes define va_list forms of the output functions described above. The functions are:

PR_vsnprintf
PR_vsmprintf
PR_vsprintf_append
PR_vsxprintf
PR_vfprintf

PR_vsnprintf


Syntax 
PRUint32 PR_vsnprintf (
   char *out,
   PRUint32 outlen, 
   const char *fmt, 
   va_list ap);

PR_vsmprintf


Syntax 
char* PR_vsmprintf (
   const char *fmt, 
   va_list ap);

PR_vsprintf_append


Syntax 
char* PR_vsprintf_append (
   char *last, 
   const char *fmt, 
   va_list ap);

PR_vsxprintf


Syntax 
PRUint32 PR_vsxprintf (
   PRStuffFunc f, 
   void *arg, 
   const char *fmt,
   va_list ap);

PR_vfprintf


Syntax 
PRUint32 PR_vfprintf (
   struct PRFileDesc* fd, 
   const char *fmt, 
   va_list ap);

Scanning Function

One scanning function is provided, PR_sscanf.

PR_sscanf

Scans a character string and performs data conversions.


Syntax 
PRInt32 PR_sscanf (
   const char *buf, 
   const char *fmt, 
   ...);


Parameters
The function has these parameters:

buf

A character array holding the data to be scanned.

fmt

The string that is used as the formatting specification.

...

An arbitrary number of parameters, each of which is a pre-allocated location in which to return the results. The number and type of the parameters are governed by the fmt string.


Returns
The number of items scanned and stored, or -1 if the conversion failed.


Description
This function scans the specified character string, performs data conversions according to the specified format control string, and stores the converted values in the data objects pointed to by its arguments.

This function behaves the same way as the sscanf() function in the Standard C Library (stdio.h), with the following exceptions:

  • PR_sscanf handles the NSPR integer and floating point types, such as PRInt16, PRInt32, PRInt64, and PRFloat64,

  • PR_sscanf has no multibyte character support.

Previous     Contents     Next     

Last Updated May 18, 2001