Performs processing relating to input/output of stream input/output file.
The following constants (macros) are all implementation-defined.
Implementation-Defined Specifications
(a) The output format of perror function is
<string>:<error message for the error number specified in error>
(b) Table 7.8 shows the format when displaying the floating-point infinity and not-a-number in printf and fprintf functions.
An example of a program that performs a series of input/output processing operations for a stream input/output file is shown in the following.
1 #include <stdio.h>
2
3 void main( )
4 {
5 int c;
6 FILE *ifp, *ofp;
7
8 if ((ifp=fopen("INPUT.DAT","r"))==NULL){
9 fprintf(stderr,"cannot open input file\n");
10 exit(1);
11 }
12 if ((ofp=fopen("OUTPUT.DAT","w"))==NULL){
13 fprintf(stderr,"cannot open output file\n");
14 exit(1);
15 }
16 while ((c=getc(ifp))!=EOF)
17 putc(c, ofp);
18 fclose(ifp);
19 fclose(ofp);
20 }
This program copies the contents of file INPUT.DAT to file OUTPUT.DAT.
Input file INPUT.DAT is opened by the fopen function in line 8, and output file OUTPUT.DAT is opened by the fopen function in line 12. If opening fails, NULL is returned as the return value of the fopen function, an error message is output, and the program is terminated.
If the fopen function ends normally, the pointer to the data (FILE type) that stores information on the opened files is returned; these are set in variables ifp and ofp.
After successful opening, input/output is performed using these FILE type data.
When file processing ends, the files are closed with the fclose function.
Closes a stream input/output file.
#include <stdio.h>
long fclose (FILE *fp);
The fclose function closes the stream input/output file indicated by file pointer fp.
If the output file of the stream input/output file is open and data that is not output remains in the buffer, that data is output to the file before it is closed.
If the input/output buffer was automatically allocated by the system, it is released.
Outputs the stream input/output file buffer contents to the file.
#include <stdio.h>
long fflush (FILE *fp);
When the output file of the stream input/output file is open, the fflush function outputs the contents of the buffer that is not output for the stream input/output file specified by file pointer fp to the file. When the input file is open, the ungetc function specification is invalidated.
Opens a stream input/output file under the specified file name.
#include <stdio.h>
FILE *fopen (const char *fname, const char *mode);
fname Pointer to string indicating file name
mode Pointer to string indicating file access mode
Normal: File pointer indicating file information on opened file
The fopen function opens the stream input/output file whose file name is the string pointed to by fname. If a file that does not exist is opened in write mode or append mode, a new file is created wherever possible. When an existing file is opened in write mode, writing processing is performed from the beginning of the file, and previously written file contents are erased.
When a file is opened in append mode, write processing is performed from the end-of-file position. When a file is opened in update mode, both input and output processing can be performed on the file. However, input cannot directly follow output without intervening execution of the fflush, fseek, or rewind function. Similarly, output cannot directly follow input without intervening execution of the fflush, fseek, or rewind function.
A string indicating the opening method may be added after the string indicating the file access mode.
Closes a currently open stream input/output file and reopens a new file under the specified file name.
#include <stdio.h>
FILE *freopen (const char *fname, const char *mode, FILE *fp);
fname Pointer to string indicating new file name
mode Pointer to string indicating file access mode
fp File pointer to currently open stream input/output file
The freopen function first closes the stream input/output file indicated by file pointer fp (the following processing is carried out even if this close processing is unsuccessful). Next, the freopen function opens the file indicated by file name fname for stream input/output, reusing the FILE structure pointed to by fp.
The freopen function is useful when there is a limit on the number of files being opened at one time.
The freopen function normally returns the same value as fp, but returns NULL when an error occurs.
Defines and sets a stream input/output buffer area by the user program.
#include <stdio.h>
void setbuf (FILE *fp, char buf[BUFSIZ]);
The setbuf function defines the storage area pointed to by buf so that it can be used as an input/output buffer area for the stream input/output file indicated by file pointer fp. As a result, input/output processing is performed using a buffer area of size BUFSIZ.
Defines and sets a stream input/output buffer area by the user program.
#include <stdio.h>
long setvbuf (FILE *fp, char *buf, long type, size_t size);
The setvbuf function defines the storage area pointed to by buf so that it can be used as an input/output buffer area for the stream input/output file indicated by file pointer fp.
There are three ways of using this buffer area, as follows:
(a) When _IOFBF is specified as type
Input/output is fully buffered.
(b) When _IOLBF is specified as type
Input/output is line buffered; that is, input/output data is fetched from the buffer area when a new-line character is written, when the buffer area is full, or when input is requested.
(c) When _IONBF is specified as type
Input/output is unbuffered.
The setvbuf function usually returns 0. However, when an illegal value is specified for type or size, or when the request on how to use the buffer could not be accepted, a value other than 0 is returned.
The buffer area must not be released before the open stream input/output file is closed. In addition, the setvbuf function must be used between opening of the stream input/output file and execution of input/output processing.
Outputs data to a stream input/output file according to the format.
#include <stdio.h>
long fprintf (FILE *fp, const char *control[, arg]...);
control Pointer to string indicating format
arg, List of data to be output according to format
Normal: Number of characters converted and output
The fprintf function converts and edits parameter arg according to the string that represents the format pointed to by control, and outputs the result to the stream input/output file indicated by file pointer fp.
The fprintf function returns the number of characters converted and output when the function is terminated successfully, or a negative value if an error occurs.
The format specifications are shown below.
The string that represents the format is made up of two kinds of string.
A character other than a conversion specification shown below is output unchanged.
A conversion specification is a string beginning with % that specifies the conversion method for the following parameter. The conversion specifications format conforms to the following rules:
When there is no parameter to be actually output according to this conversion specification, the behavior is not guaranteed. In addition, when the number of parameters to be actually output is greater than the conversion specification, the excess parameters are ignored.
Description of Conversion Specifications
Flags specify modifications to the data to be output, such as addition of a sign. The types of flag that can be specified and their meanings are shown in Table 7.9.
The number of characters in the converted data to be output is specified as a decimal number.
If the number of converted data characters is less than the field width, the data is prefixed with spaces up to the field width. (However, if '-' is specified as a flag, spaces are suffixed to the data.)
If the number of converted data characters exceeds the field width, the field width is extended to allow the converted result to be output.
If the field width specification begins with 0, the output data is prefixed with characters "0", not spaces.
The precision of the converted data is specified according to the type of conversion, as described in table 6.10.
The precision is specified in the form of a period (.) followed by a decimal integer. If the decimal integer is omitted, 0 is assumed to be specified.
If the specified precision is incompatible with the field width specification, the field width specification is ignored.
The precision specification has the following meanings according to the conversion type.
The minimum number of digits in the converted data is specified.
The number of digits after the decimal point in the converted data is specified.
The maximum number of significant digits in the converted data is specified.
The maximum number of printed digits is specified.
(d) Parameter size specification
For d, i, o, u, x, X, e, E, f, g, and G conversions (see table 6.10), the size (short type, long type, long long type, or long double type) of the data to be converted is specified. In other conversions, this specification is ignored. Table 7.10 shows the types of size specification and their meanings.
The format into which the data is to be converted is specified.
If the data to be converted is structure or array type, or is a pointer pointing to those types, the behavior is not guaranteed except when a character array is converted by s conversion or when a pointer is converted by p conversion. Table 7.11 shows the conversion specifier and conversion methods. If a letter which is not shown in this table is specified as the conversion specifier, the behavior is not guaranteed. The behavior, if a character that is not a letter is specified, depends on the compiler.
(f) * specification for field width or precision
* can be specified as the field width or precision specification value.
In this case, the value of the parameter corresponding to the conversion specification is used as the field width or precision specification value. When this parameter has a negative field width, it is interpreted as flag '' and a positive field width. When the parameter has a negative precision, the precision is interpreted as being omitted.
Converts data according to a format and outputs it to the specified area.
#include <stdio.h>
long snprintf(char *restrict s, size_t n, const char *restrict control
[, arg]...);
s Pointer to storage area to which data is to be output
n Number of characters to be output
control Pointer to string indicating format
arg, Data to be output according to format
Number of characters converted
The snprintf function converts and edits parameter arg according to the format-representing string pointed to by control, and outputs the result to the storage area pointed to by s.
A null character is appended at the end of the converted and output string. This null character is not included in the return value (number of characters output). For details of the format specifications, see the description of the fprintf function.
Converts data according to a format and outputs it to the specified area.
#include <stdarg.h>
#include <stdio.h>
long vsnprintf(char *restrict s, size_t n, const char *restrict control, va_list arg)
s Pointer to storage area to which data is to be output
n Number of characters to be output
control Pointer to string indicating format
Number of characters converted
The vsnprintf function is equivalent to snprintf with arg specified instead of the variable parameters.
Initialize arg through the va_start macro before calling the vsnprintf function.
The vsnprintf function does not call the va_end macro.
Inputs data from a stream input/output file and converts it according to a format.
#include <stdio.h>
long fscanf (FILE *fp, const char *control[, ptr]...);
control Pointer to string indicating format
ptr,... Pointer to storage area that stores input data
Normal: Number of data items successfully input and converted
Abnormal: Input data ends before input data conversion is performed: EOF
The fscanf function inputs data from the stream input/output file indicated by file pointer fp, converts and edits it according to the string that represents the format pointed to by control, and stores the result in the storage area pointed to by ptr.
The format specifications for inputting data are shown below.
The string that represents the format is made up of the following three kinds of string.
If a space (' '), horizontal tab ('\t'), or new-line character ('\n') is specified, processing is performed to skip to the next non-white-space character in the input data.
If a character that is neither one of the space characters listed above nor % is specified, one input data character is input. The input character must match a character specified in the string that represents the format.
A conversion specification is a string beginning with % that specifies the method of converting the input data and storing it in the area pointed to by the following parameter. The conversion specification format conforms to the following rules:
% [*] [Field width] [Converted data size] Conversion specifier
If there is no pointer to the storage area that stores input data corresponding to the conversion specification in the format, the behavior is not guaranteed. In addition, when a pointer to a storage area that stores input data remains though the format is exhausted, that pointer is ignored.
Description of Conversion Specifications
Suppresses storage of the input data in the storage area pointed to by the parameter.
The maximum number of characters in the data to be input is specified as a decimal number.
For d, i, o, u, x, X, e, E, and f conversions (see table 6.12), the size (short type, long type, long long type, or long double type) of the converted data is specified. In other conversions, this specification is ignored. Table 7.12 shows the types of size specification and their meanings.
The input data is converted according to the type of conversion specified by the conversion specifier. However, processing is terminated when a white-space character is read, when a character for which conversion is not permitted is read, or when the specified field width has been exceeded.
If the conversion specifier is a letter not shown in table 6.12, the behavior is not guaranteed. For the other characters, the behavior is implementation-defined.
Converts data according to a format and outputs it to the standard output file (stdout).
#include <stdio.h>
long printf (const char *control[, arg]...);
control Pointer to string indicating format
arg,... Data to be output according to format
Normal: Number of characters converted and output
The printf function converts and edits parameter arg according to the string that represents the format pointed to by control, and outputs the result to the standard output file (stdout).
For details of the format specifications, see the description of the fprintf function.
Inputs data from a stream input/output file and converts it according to a format.
#include <stdarg.h>
#include <stdio.h>
long vfscanf(FILE *restrict fp, const char *restrict control, va_list arg)
control Pointer to wide string indicating format
Normal: Number of data items successfully input and converted
Abnormal: Input data ends before input data conversion is performed: EOF
The vfscanf function is equivalent to fscanf with arg specified instead of the variable parameter list.
Initialize arg through the va_start macro before calling the vfscanf function.
The vfscanf function does not call the va_end macro.
Inputs data from the standard input file (stdin) and converts it according to a format.
#include <stdio.h>
long scanf (const char *control[, ptr]);
control Pointer to string indicating format
ptr,... Pointer to storage area that stores input and converted data
Normal: Number of data items successfully input and converted
The scanf function inputs data from the standard input file (stdin), converts and edits it according to the string that represents the format pointed to by control, and stores the result in the storage area pointed to by ptr.
The scanf function returns the number of data items successfully input and converted as the return value. EOF is returned if the standard input file ends before the first conversion.
For details of the format specifications, see the description of the fscanf function.
For %e conversion, specify l for double type, and specify L for long double type. The default type is float.
Inputs data from the specified storage area and converts it according to a format.
#include <stdarg.h>
#include <stdio.h>
long vscanf(const char *restrict control, va_list arg)
control Pointer to string indicating format
Normal: Number of data items successfully input and converted
Abnormal: Input data ends before input data conversion is performed: EOF
The vscanf function is equivalent to scanf with arg specified instead of the variable parameters.
Initialize arg through the va_start macro before calling the vscanf function.
The vscanf function does not call the va_end macro.
Converts data according to a format and outputs it to the specified area.
#include <stdio.h>
long sprintf (char *s, const char *control[, arg]);
s Pointer to storage area to which data is to be output
control Pointer to string indicating format
arg,... Data to be output according to format
Number of characters converted
The sprintf function converts and edits parameter arg according to the string that represents the format pointed to by control, and outputs the result to the storage area pointed to by s.
A null character is appended at the end of the converted and output string. This null character is not included in the return value (number of characters output).
For details of the format specifications, see the description of the fprintf function.
Inputs data from the specified storage area and converts it according to a format.
#include <stdio.h>
long sscanf (const char *s, const char *control[, ptr]);
s Storage area containing data to be input
control Pointer to string indicating format
ptr,... Pointer to storage area that stores input and converted data
Normal: Number of data items successfully input and converted
The sscanf function inputs data from the storage area pointed to by s, converts and edits it according to the string that represents the format pointed to by control, and stores the result in the storage area pointed to by ptr.
The sscanf function returns the number of data items successfully input and converted. EOF is returned when the input data ends before the first conversion.
For details of the format specifications, see the description of the fscanf function.
Inputs data from the specified storage area and converts it according to a format.
#include <stdarg.h>
#include <stdio.h>
long vsscanf(const char *restrict s, const char *restrict control, va_list arg)
s Storage area containing data to be input
control Pointer to string indicating format
Normal: Number of data items successfully input and converted
Abnormal: nput data ends before input data conversion is performed: EOF
The vsscanf function is equivalent to sscanf with arg specified instead of the variable parameters.
Initialize arg through the va_start macro before calling the vsscanf function.
The vsscanf function does not call the va_end macro.
Outputs a variable parameter list to the specified stream input/output file according to a format.
#include <stdarg.h>
#include <stdio.h>
long vfprintf (FILE *fp, const char *control, va_list arg)
control Pointer to string indicating format
Normal: Number of characters converted and output
The vfprintf function sequentially converts and edits a variable parameter list according to the string that represents the format pointed to by control, and outputs the result to the stream input/output file indicated by fp.
The vfprintf function returns the number of data items converted and output, or a negative value when an error occurs.
Within the vfprintf function, the va_end macro is not invoked.
For details of the format specifications, see the description of the fprintf function.
Parameter arg, indicating the parameter list, must be initialized beforehand by the va_start macro (and the succeeding va_arg macro).
Outputs a variable parameter list to the standard output file (stdout) according to a format.
#include <stdarg.h>
#include <stdio.h>
long vprintf (const char *control, va_list arg)
control Pointer to string indicating format
Normal: Number of characters converted and output
The vprintf function sequentially converts and edits a variable parameter list according to the string that represents the format pointed to by control, and outputs the result to the standard output file.
The vprintf function returns the number of data items converted and output, or a negative value when an error occurs.
Within the vprintf function, the va_end macro is not invoked.
For details of the format specifications, see the description of the fprintf function.
Parameter arg, indicating the parameter list, must be initialized beforehand by the va_start macro (and the succeeding va_arg macro).
Outputs a variable parameter list to the specified storage area according to a format.
#include <stdarg.h>
#include <stdio.h>
long vsprintf (char *s, const char *control, va_list arg)
s Pointer to storage area to which data is to be output
control Pointer to string indicating format
Normal: Number of characters converted
The vsprintf function sequentially converts and edits a variable parameter list according to the string that represents the format pointed to by control, and outputs the result to the storage area pointed to by s.
A null character is appended at the end of the converted and output string. This null character is not included in the return value (number of characters output).
For details of the format specifications, see the description of the fprintf function.
Parameter arg, indicating the parameter list, must be initialized beforehand by the va_start macro (and the succeeding va_arg macro).
Inputs one character from a stream input/output file.
#include <stdio.h>
long fgetc (FILE *fp);
When a read error occurs, the error indicator for that file is set.
The fgetc function inputs one character from the stream input/output file indicated by file pointer fp.
The fgetc function normally returns the input character, but returns EOF at end-of-file or when an error occurs. At end-of-file, the end-of-file indicator for that file is set.
Inputs a string from a stream input/output file.
#include <stdio.h>
char *fgets (char *s, long n, FILE *fp);
s Pointer to storage area to which string is input
n Number of bytes of storage area to which string is input
The fgets function inputs a string from the stream input/output file indicated by file pointer fp to the storage area pointed to by s.
The fgets function performs input up to the (n1)th character or a new-line character, or until end-of-file, and appends a null character at the end of the input string.
The fgets function normally returns s, the pointer to the storage area to which the string is input, but returns NULL at end-of-file or if an error occurs.
The contents of the storage area pointed to by s do not change at end-of-file, but are not guaranteed when an error occurs.
Outputs one character to a stream input/output file.
#include <stdio.h>
long fputc (long c, FILE *fp);
When a write error occurs, the error indicator for that file is set.
The fputc function outputs character c to the stream input/output file indicated by file pointer fp.
The fputc function normally returns c, the output character, but returns EOF when an error occurs.
Outputs a string to a stream input/output file.
#include <stdio.h>
long fputs (const char *s, FILE *fp);
s Pointer to string to be output
The fputs function outputs the string pointed to by s up to the character preceding the null character to the stream input/output file indicated by file pointer fp. The null character indicating the end of the string is not output.
The fputs function normally returns zero, but returns nonzero when an error occurs.
Inputs one character from a stream input/output file.
#include <stdio.h>
long getc (FILE *fp);
When a read error occurs, the error indicator for that file is set.
The getc function inputs one character from the stream input/output file indicated by file pointer fp.
The getc function normally returns the input character, but returns EOF at end-of-file or when an error occurs. At end-of-file, the end-of-file indicator for that file is set.
Inputs one character from the standard input file (stdin).
#include <stdio.h>
long getchar (void);
When a read error occurs, the error indicator for that file is set.
The getchar function inputs one character from the standard input file (stdin).
The getchar function normally returns the input character, but returns EOF at end-of-file or when an error occurs. At end-of-file, the end-of-file indicator for that file is set.
Inputs a string from the standard input file (stdin).
#include <stdio.h>
char *gets (char *s);
s Pointer to storage area to which string is input
The gets function inputs a string from the standard input file (stdin) to the storage area starting at s.
The gets function inputs characters up to end-of-file or until a new-line character is input, and appends a null character instead of a new-line character.
The gets function normally returns s, the pointer to the storage area to which the string is input, but returns NULL at the end of the standard input file or when an error occurs.
The contents of the storage area pointed to by s do not change at the end of the standard input file, but are not guaranteed when an error occurs.
Outputs one character to a stream input/output file.
#include <stdio.h>
long putc (long c, FILE *fp);
When a write error occurs, the error indicator for that file is set.
The putc function outputs character c to the stream input/output file indicated by file pointer fp.
The putc function normally returns c, the output character, but returns EOF when an error occurs.
Outputs one character to the standard output file (stdout).
#include <stdio.h>
long putchar (long c);
When a write error occurs, the error indicator for that file is set.
The putchar function outputs character c to the standard output file (stdout).
The putchar function normally returns c, the output character, but returns EOF when an error occurs.
Outputs a string to the standard output file (stdout).
#include <stdio.h>
long puts (const char *s);
s Pointer to string to be output
The puts function outputs the string pointed to by s to the standard output file (stdout). The null character indicating the end of the string is not output, but a new-line character is output instead.
The puts function normally returns zero, but returns nonzero when an error occurs.
Returns one character to a stream input/output file.
#include <stdio.h>
long ungetc (long c, FILE *fp);
The ungetc function returns character c to the stream input/output file indicated by file pointer fp. Unless the fflush, fseek, or rewind function is called, this returned character will be the next input data.
The ungetc function normally returns c, which is the returned character, but returns EOF when an error occurs.
The behavior is not guaranteed when the ungetc function is called more than once without intervening fflush, fseek, or rewind function execution. When the ungetc function is executed, the current file position indicator for that file is moved back one position; however, when this file position indicator has already been positioned at the beginning of the file, its value is not guaranteed.
Inputs data from a stream input/output file to the specified storage area.
#include <stdio.h>
size_t fread (void *ptr, size_t size, size_t n, FILE *fp);
ptr Pointer to storage area to which data is input
size Number of bytes in one member
n Number of members to be input
When size and n are both nonzero: Number of successfully input members
The fread function inputs n members whose size is specified by size, from the stream input/output file indicated by file pointer fp, into the storage area pointed to by ptr. The file position indicator for the file is advanced by the number of bytes input.
The fread function returns the number of members successfully input, which is normally the same as the value of n. However, at end-of-file or when an error occurs, the number of members successfully input so far is returned, and then the return value will be less than n. The ferror and feof functions should be used to distinguish between end-of-file and error occurrence.
When the value of size or n is zero, zero is returned as the return value and the contents of the storage area pointed to by ptr do not change. When an error occurs or when only a part of the members can be input, the file position indicator is not guaranteed.
Outputs data from a memory area to a stream input/output file.
#include <stdio.h>
size_t fwrite (const void *ptr, size_t size, size_t n, FILE *fp);
ptr Pointer to storage area storing data to be output
size Number of bytes in one member
n Number of members to be output
Number of successfully output members
The fwrite function outputs n members whose size is specified by size, from the storage area pointed to by ptr, to the stream input/output file indicated by file pointer fp. The file position indicator for the file is advanced by the number of bytes output.
The fwrite function returns the number of members successfully output, which is normally the same as the value of n. However, when an error occurs, the number of members successfully output so far is returned, and then the return value will be less than n.
When an error occurs, the file position indicator is not guaranteed.
Shifts the current read/write position in a stream input/output file.
#include <stdio.h>
long fseek (FILE *fp, long offset, long type) ;
offset Offset from position specified by type of offset
The fseek function shifts the current read/write position in the stream input/output file indicated by file pointer fp by offset bytes from the position specified by type (the type of offset).
The types of offset are shown in table 6.13.
The fseek function normally returns zero, but returns nonzero in response to an invalid request.
For a text file, the type of offset must be SEEK_SET and offset must be zero or the value returned by the ftell function for that file. Note also that calling the fseek function cancels the effect of the ungetc function.
Obtains the current read/write position in a stream input/output file.
#include <stdio.h>
long ftell (FILE *fp);
Current file position indicator position (text file)
Number of bytes from beginning of file to current position (binary file)
The ftell function obtains the current read/write position in the stream input/output file indicated by file pointer fp.
For a binary file, the ftell function returns the number of bytes from the beginning of the file to the current position. For a text file, it returns, as the position of the file position indicator, an implementation-defined value that can be used by the fseek function.
When the ftell function is used twice for a text file, the difference in the return values will not necessarily represent the actual distance in the file.
Shifts the current read/write position in a stream input/output file to the beginning of the file.
#include <stdio.h>
void rewind (FILE *fp);
The rewind function shifts the current read/write position in the stream input/output file indicated by file pointer fp, to the beginning of the file.
The rewind function clears the end-of-file indicator and error indicator for the file.
Note that calling the rewind function cancels the effect of the ungetc function.
Clears the error state of a stream input/output file.
#include <stdio.h>
void clearerr (FILE *fp);
The clearerr function clears the error indicator and end-of-file indicator for the stream input/output file indicated by file pointer fp.
Tests for the end of a stream input/output file.
#include <stdio.h>
long feof (FILE *fp);
The feof function tests for the end of the stream input/output file indicated by file pointer fp.
The feof function tests the end-of-file indicator for the specified stream input/output file, and if the indicator is set, returns nonzero to indicate that the file is at its end. If the end-of-file indicator is not set, the feof function returns zero to show that the file is not yet at its end.
Tests for stream input/output file error state.
#include <stdio.h>
long ferror (FILE *fp);
If file is in error state: Nonzero
The ferror function tests whether the stream input/output file indicated by file pointer fp is in the error state.
The ferror function tests the error indicator for the specified stream input/output file, and if the indicator is set, returns nonzero to show that the file is in the error state. If the error indicator is not set, the ferror function returns zero to show that the file is not in the error state.
Outputs an error message corresponding to the error number to the standard error file (stderr).
#include <stdio.h>
void perror (const char *s)
The perror function maps errno to the error message indicated by s, and outputs the message to the standard error file (stderr).
If s is not NULL and the string pointed to by s is not a null character, the output format is as follows: the string pointed to by s followed by a colon and space, then the implementation-defined error message, and finally a new-line character.