---

Standard I/O
[C Runtime Library.]

Standard stream interface to Nut/OS devices. More...

Defines
#define	EOF
	End of file.
#define	_IOFBF
	Fully buffered.
#define	_IOLBF
	Line buffered.
#define	_IONBF
	Unbuffered.
#define	stdin
	Standard input stream.
#define	stdout
	Standard output stream.
#define	stderr
	Standard error output stream.
Typedefs
typedef __iobuf	FILE
	Stream structure type.
Functions
void	clearerr (FILE *stream)
	Reset error status of a stream.
int	fclose (FILE *stream)
	Close a stream.
void	fcloseall (void)
	Close all open streams.
FILE *	_fdopen (int fd, CONST char *mode)
	Open a stream associated with a file, device or socket descriptor.
int	feof (FILE *stream)
	Test if a stream reached the end of file.
int	ferror (FILE *stream)
	Test for an error on a stream.
int	fflush (FILE *stream)
	Flush a stream.
int	fgetc (FILE *stream)
	Read a character from a stream.
char *	fgets (char *buffer, int count, FILE *stream)
	Read a line from a stream.
int	_fileno (FILE *stream)
	Get the file descriptor associated with a stream.
void	_flushall (void)
	Flushes all streams.
FILE *	fopen (CONST char *name, CONST char *mode)
	Open a stream.
int	fprintf (FILE *stream, CONST char *fmt,...)
	Print formatted data to a stream.
int	fprintf_P (FILE *stream, PGM_P fmt,...)
	Print formatted data to a stream.
int	fputc (int c, FILE *stream)
	Write a character to a stream.
int	fputs (CONST char *string, FILE *stream)
	Write a string to a stream.
int	fputs_P (PGM_P string, FILE *stream)
	Write a string from progam memory to a stream.
size_t	fread (void *buffer, size_t size, size_t count, FILE *stream)
	Read data from a stream.
FILE *	freopen (CONST char *name, CONST char *mode, FILE *stream)
	Reassign a stream.
int	fscanf (FILE *stream, CONST char *fmt,...)
	Read formatted data from a stream.
int	fscanf_P (FILE *stream, PGM_P fmt,...)
	Read formatted data from a stream.
int	fseek (FILE *stream, long offset, int origin)
	Move read/write position of a stream.
long	ftell (FILE *stream)
	Return the read/write position of a stream.
size_t	fwrite (CONST void *data, size_t size, size_t count, FILE *stream)
	Write data to a stream.
size_t	fwrite_P (PGM_P data, size_t size, size_t count, FILE *stream)
	Write data from program space to a stream.
int	getc (FILE *stream)
	Read a character from a stream.
int	getchar (void)
	Read a character from a standard input.
int	_getf (int _getb(int, void *, size_t), int fd, CONST char *fmt, va_list ap)
	Read formatted data using a given input function.
char *	gets (char *buffer)
	Get a line from the standard input stream.
int	printf (CONST char *fmt,...)
	Print formatted data to the standard output stream.
int	printf_P (PGM_P fmt,...)
	Print formatted output to the standard output stream.
int	putc (int c, FILE *stream)
	Write a character to a stream.
int	putchar (int c)
	Write a character to standard output.
int	_putf (int _putb(int, CONST void *, size_t), int fd, CONST char *fmt, va_list ap)
	Write formatted data using a given output function.
int	puts (CONST char *string)
	Write a string to stdout.
int	puts_P (PGM_P string)
	Write a string from program memory to stdout.
int	scanf (CONST char *fmt,...)
	Read formatted data from the standard input stream.
int	scanf_P (PGM_P fmt,...)
	Read formatted data from the standard input stream.
int	sprintf (char *buffer, CONST char *fmt,...)
	Write formatted data to a string.
int	sprintf_P (char *buffer, PGM_P fmt,...)
	Write formatted data to a string.
int	sscanf (CONST char *string, CONST char *fmt,...)
	Read formatted data from a string.
int	sscanf_P (CONST char *string, CONST char *fmt,...)
	Read formatted data from a string.
int	ungetc (int c, FILE *stream)
	Push a character back onto a stream.
int	vfprintf (FILE *stream, CONST char *fmt, va_list ap)
	Write argument list to a stream using a given format.
int	vfprintf_P (FILE *stream, PGM_P fmt, va_list ap)
	Write argument list to a stream using a given format.
int	vfscanf (FILE *stream, CONST char *fmt, va_list ap)
	Read formatted data from a stream.
int	vfscanf_P (FILE *stream, PGM_P fmt, va_list ap)
	Read formatted data from a stream.
int	vsprintf (char *buffer, CONST char *fmt, va_list ap)
	Write argument list to a string using a given format.
int	vsprintf_P (char *buffer, PGM_P fmt, va_list ap)
	Write argument list to a string using a given format.
int	vsscanf (CONST char *string, CONST char *fmt, va_list ap)
	Read formatted data from a string.
int	vsscanf_P (CONST char *string, PGM_P fmt, va_list ap)
	Read formatted data from a string.

---

Detailed Description

Standard stream interface to Nut/OS devices.

 #include <stdio.h> 

In contrast to the standard, Nut/OS streams do not maintain there own buffers. Any input or output buffering is done in the device driver.

Nut/OS will not associate the standard streams stdin, stdout and stderr to a device when starting the application. Instead, freopen() can be used by the application to redirect any of these stream to any previously opened file, device or connected socket.

As an extension to the standard, many function come in an additional flavour with _P appended to their name. These functions accept specific parameters pointing into program space.

---

Define Documentation

#define EOF

End of file. Returned by an input or output operation when the end of a file is encountered. Some routines return this value to indicate an error.

---

Typedef Documentation

typedef struct __iobuf FILE

Stream structure type. A pointer to this type is used for all standard I/O functions to specify a stream. Note: Applications should make any assumptions about the contents of this structure as it may change without further notice.

---

Function Documentation

FILE* _fdopen (  int    fd, CONST char *    mode )

Open a stream associated with a file, device or socket descriptor. Parameters: fd  Descriptor of a previously opened file, device or connected socket. mode  Specifies the access mode. "r" Read only. "w" Write only. "a" Write only at the end of file. "r+" Read and write existing file. "w+" Read and write, destroys existing file contents. "a+" Read and write, preserves existing file contents. "b" May be appended to any of the above strings to specify binary access. Returns: A pointer to the open stream or a null pointer to indicate an error. Examples: httpd/httpserv.c, inetq/inetq.c, portdio/portdio.c, and tcps/tcps.c.

int _fileno (  FILE *    stream )

Get the file descriptor associated with a stream. In contrast to other implementations, the standard streams stdin, stdout and stderr do not return 0, 1 and 2 resp. Parameters: stream  Pointer to a previously opened stream. Returns: The file descriptor. Warning: The function will not check, if the stream pointer points to a valid stream. Examples: httpd/httpserv.c, inetq/inetq.c, playmp3/playmp3.c, tcps/tcps.c, threads/threads.c, timers/timers.c, and uart/uart.c.

void _flushall (  void    )

Flushes all streams.

int _getf (  int     _getb(int, void *, size_t), int    fd, CONST char *    fmt, va_list    ap )

Read formatted data using a given input function. Parameters: _getb  Input function for reading data. fd  Descriptor of a previously opened file, device or connected socket. fmt  Format string containing coversion specifications. ap  List of pointer arguments. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion.

int _putf (  int     _putb(int, CONST void *, size_t), int    fd, CONST char *    fmt, va_list    ap )

Write formatted data using a given output function. Parameters: _putb  Output function for writing data. fd  Descriptor of a previously opened file, device or connected socket. fmt  Format string containing conversion specifications. ap  List of arguments.

void clearerr (  FILE *    stream )

Reset error status of a stream. Parameters: stream  Pointer to a previously opened stream. Bug: This function does nothing.

int fclose (  FILE *    stream )

Close a stream. The calling thread may be suspended until all buffered output data has been written. Parameters: stream  Pointer to a previously opened stream. Returns: 0 if the stream is successfully closed, EOF otherwise. Examples: httpd/httpserv.c, inetq/inetq.c, portdio/portdio.c, and tcps/tcps.c.

void fcloseall (  void    )

Close all open streams. The standard streams stdin, stdout and stderr are not closed. The calling thread may be suspended until all buffered output data has been written.

int feof (  FILE *    stream )

Test if a stream reached the end of file. Parameters: stream  Pointer to a previously opened stream. Returns: 0 if the current position is not the end of the file. Bug: The function always returns 0.

int ferror (  FILE *    stream )

Test for an error on a stream. Parameters: stream  Pointer to a previously opened stream. Returns: 0 if no error occured. Bug: The function always returns 0.

int fflush (  FILE *    stream )

Flush a stream. The calling thread may be suspended until all buffered output data has been written. Parameters: stream  Pointer to a previously opened stream. Returns: 0 if the buffer was successfully flushed, EOF if an error occured. Warning: The function will not check, if the stream pointer points to a valid stream. Examples: httpd/httpserv.c, inetq/inetq.c, portdio/portdio.c, tcps/tcps.c, and uart/uart.c.

int fgetc (  FILE *    stream )

Read a character from a stream. Parameters: stream  Pointer to a previously opened stream. Returns: Character read or EOF to indicate an error or end of file. Warning: The function will not check, if the stream pointer points to a valid stream.

char* fgets (  char *    buffer, int    count, FILE *    stream )

Read a line from a stream. Read at most one less than the specified number of characters from a stream or stop when a newline has been read. Parameters: buffer  Pointer to the buffer that receives the data including the linefeed character. count  Maximum number of characters to read. stream  Pointer to a previously opened stream. Returns: Pointer to the given buffer or NULL to indicate an error or the end of the file. Warning: The function will not check, if the stream pointer points to a valid stream. Examples: inetq/inetq.c, portdio/portdio.c, tcps/tcps.c, and uart/uart.c.

FILE* fopen (  CONST char *    name, CONST char *    mode )

Open a stream. Parameters: name  The name of a registered device, optionally followed by a colon and a filename. mode  Specifies the access mode. "r" Read only. "w" Write only. "a" Write only at the end of file. "r+" Read and write existing file. "w+" Read and write, destroys existing file contents. "a+" Read and write, preserves existing file contents. "b" May be appended to any of the above strings to specify binary access. Returns: A pointer to the open stream or a null pointer to indicate an error. Examples: uart/uart.c.

int fprintf (  FILE *    stream, CONST char *    fmt, ...    )

Print formatted data to a stream. Parameters: stream  Pointer to a previously opened stream. fmt  Format string containing conversion specifications. Returns: The number of characters written or a negative value to indicate an error. Warning: The function will not check, if the stream pointer points to a valid stream. Examples: inetq/inetq.c, portdio/portdio.c, tcps/tcps.c, and uart/uart.c.

int fprintf_P (  FILE *    stream, PGM_P    fmt, ...    )

Print formatted data to a stream. Similar to fprintf() except that the format string is located in program memory. Parameters: stream  Pointer to a previously opened stream. fmt  Format string in program space containing conversion specifications. Returns: The number of bytes written or a negative value to indicate an error. Warning: The function will not check, if the stream pointer points to a valid stream. Do not use this function with a debug device while running in interrupt context. Examples: httpd/httpserv.c, and tcps/tcps.c.

int fputc (  int    c, FILE *    stream )

Write a character to a stream. Parameters: c  Character to write. stream  Pointer to a previously opened stream. Returns: The character written or EOF to indicate an error. Warning: The function will not check, if the stream pointer points to a valid stream.

int fputs (  CONST char *    string, FILE *    stream )

Write a string to a stream. Parameters: stream  Pointer to a previously opened stream. string  String to write. Returns: A non-negative value if successful or EOF to indicate an error. Warning: The function will not check, if the stream pointer points to a valid stream. Examples: httpd/httpserv.c, inetq/inetq.c, portdio/portdio.c, tcps/tcps.c, and uart/uart.c.

int fputs_P (  PGM_P    string, FILE *    stream )

Write a string from progam memory to a stream. Similar to fputs() except that the string is located in program space. Parameters: stream  Pointer to a previously opened stream. string  String in program memory to write. Returns: A non-negative value if successful or EOF to indicate an error. Warning: The function will not check, if the stream pointer points to a valid stream. Examples: httpd/httpserv.c, tcps/tcps.c, and uart/uart.c.

size_t fread (  void *    buffer, size_t    size, size_t    count, FILE *    stream )

Read data from a stream. Parameters: buffer  Pointer to the buffer that receives the data. size  Item size in bytes. count  Maximum number of items to read. stream  Pointer to a previously opened stream. Returns: The number of full items read, which may be less then the specified number. Warning: The function will not check, if the stream pointer points to a valid stream.

FILE* freopen (  CONST char *    name, CONST char *    mode, FILE *    stream )

Reassign a stream. Parameters: name  The name of a registered device, optionally followed by a colon and a filename. mode  Specifies the access mode. "r" Read only. "w" Write only. "a" Write only at the end of file. "r+" Read and write existing file. "w+" Read and write, destroys existing file contents. "a+" Read and write, preserves existing file contents. "b" May be appended to any of the above strings to specify binary access. stream  Pointer to a previously opened stream. Returns: A pointer to the open stream or a null pointer to indicate an error. Examples: httpd/httpserv.c, inetq/inetq.c, playmp3/playmp3.c, tcps/tcps.c, threads/threads.c, and timers/timers.c.

int fscanf (  FILE *    stream, CONST char *    fmt, ...    )

Read formatted data from a stream. Parameters: stream  Pointer to a previously opened stream. fmt  Format string containing conversion specifications. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion. Warning: The function will not check, if the stream pointer points to a valid stream.

int fscanf_P (  FILE *    stream, PGM_P    fmt, ...    )

Read formatted data from a stream. Similar to fscanf() except that the format string is expected in program space. Parameters: stream  Pointer to a previously opened stream. fmt  Format string in program space containing conversion specifications. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion. Warning: The function will not check, if the stream pointer points to a valid stream.

int fseek (  FILE *    stream, long    offset, int    origin )

Move read/write position of a stream. Parameters: stream  Pointer to a previously opened stream. offset  Number of bytes from initial position. origin  Initial position to seek from. Returns: 0 if no error occured. Bug: The function does nothing and always returns -1.

long ftell (  FILE *    stream )

Return the read/write position of a stream. Parameters: stream  Pointer to a previously opened stream. Returns: The current position. Bug: The function does nothing and always returns -1.

size_t fwrite (  CONST void *    data, size_t    size, size_t    count, FILE *    stream )

Write data to a stream. Parameters: data  Pointer to items to be written. size  Item size in bytes. count  Number of items to write. stream  Pointer to a previously opened stream. Returns: The number of items written, which may be less than the specified number. Warning: The function will not check, if the stream pointer points to a valid stream.

size_t fwrite_P (  PGM_P    data, size_t    size, size_t    count, FILE *    stream )

Write data from program space to a stream. Similar to fwrite() except that the data is located in program memory. Parameters: data  Pointer to items in program space to be written. size  Item size in bytes. count  Number of items to write. stream  Pointer to a previously opened stream. Returns: The number of items written, which may be less than the specified number. Warning: The function will not check, if the stream pointer points to a valid stream.

int getc (  FILE *    stream )

Read a character from a stream. Same as fgetc(). Parameters: stream  Pointer to a previously opened stream. Returns: Character read or EOF to indicate an error or end of file. Warning: The function will not check, if the stream pointer points to a valid stream.

int getchar (  void    )

Read a character from a standard input. Returns: Character read or EOF to indicate an error or end of file.

char* gets (  char *    buffer )

Get a line from the standard input stream. Read characters from a stream until a newline has been read. Parameters: buffer  Pointer to the buffer that receives the line excluding the linefeed character. Returns: The given argument on success, 0 otherwise. Warning: This function is potentially unsafe, because it may write pass the end of the buffer.

int printf (  CONST char *    fmt, ...    )

Print formatted data to the standard output stream. Parameters: fmt  Format string containing conversion specifications. Returns: The number of characters written or a negative value to indicate an error. Examples: httpd/httpserv.c, inetq/inetq.c, playmp3/playmp3.c, tcps/tcps.c, and timers/timers.c.

int printf_P (  PGM_P    fmt, ...    )

Print formatted output to the standard output stream. Similar to printf() except that the format string is located in program memory. Parameters: fmt  Format string in program space containing conversion specifications. Returns: The number of characters written or a negative value to indicate an error. Warning: Do not use this function with a debug device while running in interrupt context. Examples: tcps/tcps.c.

int putc (  int    c, FILE *    stream )

Write a character to a stream. Same as fputc(). Parameters: c  Character to write. stream  Pointer to a previously opened stream. Returns: The character written or EOF to indicate an error. Warning: The function will not check, if the stream pointer points to a valid stream.

int putchar (  int    c )

Write a character to standard output. Parameters: c  Character to write. Returns: The character written or EOF to indicate an error. Examples: threads/threads.c.

int puts (  CONST char *    string )

Write a string to stdout. Parameters: string  String to write. Returns: A non-negative value or EOF to indicate an error. Examples: httpd/httpserv.c, inetq/inetq.c, playmp3/playmp3.c, tcps/tcps.c, threads/threads.c, and timers/timers.c.

int puts_P (  PGM_P    string )

Write a string from program memory to stdout. Similar to puts() except that the string is located in program memory. Parameters: string  String in program memory to write. Returns: A non-negative value or EOF to indicate an error.

int scanf (  CONST char *    fmt, ...    )

Read formatted data from the standard input stream. Parameters: fmt  Format string containing conversion specifications. Returns: The number of fields successfully converted and assigned. The return value is EOF, ff an error occurs or if the end of the stream is reached before the first conversion.

int scanf_P (  PGM_P    fmt, ...    )

Read formatted data from the standard input stream. Similar to scanf() except that the format string is located in program space. Parameters: fmt  Format string containing conversion specifications. Returns: The number of fields successfully converted and assigned. The return value is EOF, ff an error occurs or if the end of the stream is reached before the first conversion.

int sprintf (  char *    buffer, CONST char *    fmt, ...    )

Write formatted data to a string. Parameters: buffer  Pointer to a buffer that receives the output string. fmt  Format string containing conversion specifications. Returns: The number of characters written or a negative value to indicate an error.

int sprintf_P (  char *    buffer, PGM_P    fmt, ...    )

Write formatted data to a string. Similar to sprintf() except that the format string is located in program memory. Parameters: buffer  Pointer to a buffer that receives the output string. fmt  Format string in program space containing conversion specifications. Returns: The number of characters written or a negative value to indicate an error.

int sscanf (  CONST char *    string, CONST char *    fmt, ...    )

Read formatted data from a string. Parameters: string  Pointer to the string that contains the data. fmt  Format string containing conversion specifications. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion.

int sscanf_P (  CONST char *    string, CONST char *    fmt, ...    )

Read formatted data from a string. Similar to sscanf() except that the format string is located in program space. Parameters: string  Pointer to the string that contains the data. fmt  Format string in program space containing conversion specifications. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion.

int ungetc (  int    c, FILE *    stream )

Push a character back onto a stream. Parameters: c  Character to push back. stream  Pointer to a previously opened stream. Warning: Only a single character can be pushed back. Any previously pushed and not yet read character will be lost.

int vfprintf (  FILE *    stream, CONST char *    fmt, va_list    ap )

Write argument list to a stream using a given format. Parameters: stream  Pointer to a previously opened stream. fmt  Format string containing conversion specifications. ap  List of arguments. Returns: The number of characters written or a negative value to indicate an error.

int vfprintf_P (  FILE *    stream, PGM_P    fmt, va_list    ap )

Write argument list to a stream using a given format. Similar to vfprintf() except that the format string is located in program memory. Parameters: stream  Pointer to a previously opened stream. fmt  Format string in program space containing conversion specifications. ap  List of arguments. Returns: The number of characters written or a negative value to indicate an error.

int vfscanf (  FILE *    stream, CONST char *    fmt, va_list    ap )

Read formatted data from a stream. Parameters: stream  Pointer to a previously opened stream. fmt  Format string containing conversion specifications. ap  List of pointer arguments. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion.

int vfscanf_P (  FILE *    stream, PGM_P    fmt, va_list    ap )

Read formatted data from a stream. Similar to vfscanf() except that the format string is located in program space. Parameters: stream  Pointer to a previously opened stream. fmt  Format string in program space containing conversion specifications. ap  List of pointer arguments. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion.

int vsprintf (  char *    buffer, CONST char *    fmt, va_list    ap )

Write argument list to a string using a given format. Parameters: buffer  Pointer to a buffer that receives the output string. fmt  Format string containing conversion specifications. ap  List of arguments. Returns: The number of characters written or a negative value to indicate an error.

int vsprintf_P (  char *    buffer, PGM_P    fmt, va_list    ap )

Write argument list to a string using a given format. Similar to vsprintf() except that the format string is located in program memory. Parameters: buffer  Pointer to a buffer that receives the output string. fmt  Format string in program space containing conversion specifications. ap  List of arguments. Returns: The number of characters written or a negative value to indicate an error.

int vsscanf (  CONST char *    string, CONST char *    fmt, va_list    ap )

Read formatted data from a string. Parameters: string  Pointer to a string that contains the data. fmt  Format string containing conversion specifications. ap  List of pointer arguments. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion.

int vsscanf_P (  CONST char *    string, PGM_P    fmt, va_list    ap )

Read formatted data from a string. Similar to vsscanf() except that the format string is located in program space. Parameters: string  Pointer to a string that contains the data. fmt  Format string in program space containing conversion specifications. ap  List of pointer arguments. Returns: The number of fields successfully converted and assigned. The return value is EOF, if an error occurs or if the end of the stream is reached before the first conversion.

---