MATLAB Function Reference

fprintf

Write formatted data to file

Syntax

• [count, errmsg] = fprintf(fid, format, A, ...)
  

Description

[count, errmsg] = fprintf(fid, format, A, ...) formats the data in the real part of matrix A (and in any additional matrix arguments) under control of the specified format string, and writes it to the file associated with file identifier fid. fprintf returns a count of the number of bytes written. errmsg is an optional output argument that returns an error message string if an error occurred, or an empty string if an error did not occur.

Argument fid is an integer file identifier obtained from fopen. (It can also be 1 for standard output (the screen) or 2 for standard error. See fopen for more information.) Omitting fid causes output to appear on the screen.

Format String

The format argument is a string containing C language conversion specifications. A conversion specification controls the notation, alignment, significant digits, field width, and other aspects of output format. The format string can contain escape characters to represent nonprinting characters such as newline characters and tabs.

Conversion specifications begin with the % character and contain these optional and required elements:

• Flags (optional)
• Width and precision fields (optional)
• A subtype specifier (optional)
• Conversion character (required)

You specify these elements in the following order:

Flags

You can control the alignment of the output using any of these optional flags.

Character	Description	Example
Minus sign (-)	Left-justifies the converted argument in its field	%-5.2d
Plus sign (+)	Always prints a sign character (+ or -)	%+5.2d
Space character	Inserts a space before the value	% 5.2d
Zero (0)	Pads with zeros rather than spaces	%05.2d

Field Width and Precision Specifications

You can control the width and precision of the output by including these options in the format string.

Character	Description	Example
Field width	A digit string specifying the minimum number of digits to be printed	%6f
Precision	A digit string including a period (.) specifying the number of digits to be printed to the right of the decimal point	%6.2f

Conversion Characters

Conversion characters specify the notation of the output.

Specifier	Description
%c	Single character
%d	Decimal notation (signed)
%e	Exponential notation (using a lowercase e as in 3.1415e+00)
%E	Exponential notation (using an uppercase E as in 3.1415E+00)
%f	Fixed-point notation
%g	The more compact of %e or %f, as defined in [2]. Insignificant zeros do not print.
%G	Same as %g, but using an uppercase E
%i	Decimal notation (signed)
%o	Octal notation (unsigned)
%s	String of characters
%u	Decimal notation (unsigned)
%x	Hexadecimal notation (using lowercase letters a-f)
%X	Hexadecimal notation (using uppercase letters A-F)

Conversion characters %o, %u, %x, and %X support subtype specifiers. See Remarks for more information.

Escape Characters

This table lists the escape character sequences you use to specify nonprinting characters in a format specification.

Character	Description
\b	Backspace
\f	Form feed
\n	New line
\r	Carriage return
\t	Horizontal tab
\\	Backslash
\'' or '' (two single quotes)	Single quotation mark
%%	Percent character

Remarks

When writing text to a file on Windows, it is recommended that you open the file in write-text mode (e.g., fopen(file_id, 'wt')). This ensures that lines in the file are terminated in such a way as to be compatible with all applications that might use the file.

The fprintf function behaves like its ANSI C language namesake with these exceptions and extensions:

• If you use fprintf to convert a MATLAB double into an integer, and the double contains a value that cannot be represented as an integer (for example, it contains a fraction), MATLAB ignores the specified conversion and outputs the value in exponential format. To successfully perform this conversion, use the fix, floor, ceil, or round functions to change the value in the double into a value that can be represented as an integer before passing it to sprintf.
• The following nonstandard subtype specifiers are supported for the conversion characters %o, %u, %x, and %X.
  
  

  b	The underlying C data type is a double rather than an unsigned integer. For example, to print a double-precision value in hexadecimal, use a format like '%bx'.
  t	The underlying C data type is a float rather than an unsigned integer.

• For example, to print a double value in hexadecimal, use the format '%bx'.

• The fprintf function is vectorized for nonscalar arguments. The function recycles the format string through the elements of A (columnwise) until all the elements are used up. The function then continues in a similar manner through any additional matrix arguments.

Note    fprintf displays negative zero (-0) differently on some platforms, as shown in the following table.

	Conversion Character
Platform	%e or %E	%f	%g or %G
PC	0.000000e+000	0.000000	0
Others	-0.000000e+00	-0.000000	-0

Examples

Example 1

Create a text file called exp.txt containing a short table of the exponential function. (On Windows platforms, it is recommended that you use fopen with the mode set to 'wt' to open a text file for writing.)

• x = 0:.1:1;
  y = [x; exp(x)];
  fid = fopen('exp.txt', 'wt');
  fprintf(fid, '%6.2f %12.8f\n', y);
  fclose(fid)
  

Now examine the contents of exp.txt:

• type exp.txt
     0.00    1.00000000
     0.10    1.10517092
         ...
     1.00    2.71828183
  

Example 2

The command

• fprintf('A unit circle has circumference %g radians.\n',2*pi)
  

displays a line on the screen:

• A unit circle has circumference 6.283186 radians.
  

Example 3

To insert a single quotation mark in a string, use two single quotation marks together. For example,

• fprintf(1,'It''s Friday.\n')
  

displays on the screen

• It's Friday.
  

Example 4

The commands

• B = [8.8  7.7; 8800  7700]
  fprintf(1, 'X is %6.2f meters or %8.3f mm\n', 9.9, 9900, B)
  

display the lines

• X is 9.90 meters or 9900.000 mm
  X is 8.80 meters or 8800.000 mm
  X is 7.70 meters or 7700.000 mm
  

Example 5

Explicitly convert MATLAB double-precision variables to integer values for use with an integer conversion specifier. For instance, to convert signed 32-bit data to hexadecimal format,

• a = [6 10 14 44];
  fprintf('%9X\n', a + (a<0)*2^32)
          6
          A
          E
         2C
  

See Also

fclose, ferror, fopen, fread, fscanf, fseek, ftell, fwrite, disp

References

[1] Kernighan, B.W., and D.M. Ritchie, The C Programming Language, Second Edition, Prentice-Hall, Inc., 1988.

[2] ANSI specification X3.159-1989: "Programming Language C," ANSI, 1430 Broadway, New York, NY 10018.

fplot

frame2im

© 1994-2005 The MathWorks, Inc.