This chapter provides reference material for the standard IO API:
The header files StdIOPalm.h
and StdIOProvider.h
declare the standard IO API. For more information on using the standard IO API, see the chapter "Standard IO Applications"in the Palm OS Programmer's Companion, vol. I.
Standard IO Functions and Macros
The macros and functions in this section enable standard IO.
fgetc Macro
Purpose
Calls Siofgetc()
to return the next character from the input stream.
Declared In
StdIOPalm.h
Prototype
#define fgetc ( fs )
Parameters
-
→
fs
- An input stream from which to read the next character. You can specify only the value
stdin
for this parameter; alternate streams are not currently implemented.
Returns
The next character from the input stream. The return value EOF
indicates an error occurred.
fgets Macro
Purpose
Calls Siofgets()
to return a string from the input stream.
Declared In
StdIOPalm.h
Prototype
#define fgets ( strP, maxChars, fs )
Parameters
-
←
strP
- A pointer to the returned string.
-
→
maxChars
- The number of characters to read from the input stream, plus one for the null terminator.
-
→
fs
- An input stream from which to read the next character. You can specify only the value
stdin
for this parameter; alternate streams are not currently implemented.
Returns
A pointer to the string read from the input stream. If an error or EOF occurs before any characters are read, returns NULL
.
Comments
The returned string is always terminated by a null character.
fprintf Macro
Purpose
Calls Siofprintf()
to write formatted output to an output stream.
Declared In
StdIOPalm.h
Prototype
#define fprintf ( fs, formatP, ... )
Parameters
-
→
fs
- An output stream to which to write the formatted output. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented. -
→
formatP
- A pointer to a format string that controls how subsequent arguments are converted for output.
-
→
...
- Zero or more parameters to be formatted as specified by the
formatP
string.
Returns
Returns the number of characters written out (not including the null terminator used to end output strings). Returns a negative number if there is an error.
Comments
This function internally calls StrVPrintF()
to do the formatting. See that function for details on which format specifications are supported.
fputc Macro
Purpose
Calls Siofputc()
to write a character to the output stream.
Declared In
StdIOPalm.h
Prototype
#define fputc ( c, fs )
Parameters
-
→
c
- A character to write to the output stream.
-
→
fs
- An output stream to which to write the character. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented.
Returns
The character that was written. If an error occurs, the value EOF
is returned.
fputs Macro
Purpose
Calls Siofputs()
to write a string to the output stream.
Declared In
StdIOPalm.h
Prototype
#define fputs ( strP, fs )
Parameters
-
→
strP
- A pointer to the string to write.
-
→
fs
- An output stream to which to write the string. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented.
Returns
Returns 0 on success and the value EOF
on error.
getchar Macro
Purpose
Calls Siofgetc()
to read the next character from the stdin
input stream.
Declared In
StdIOPalm.h
Prototype
#define getchar ()
Returns
The next character from the input stream. The return value EOF
indicates an error occurred.
gets Macro
Purpose
Calls Siogets()
to read a string from the stdin
input stream.
Declared In
StdIOPalm.h
Prototype
#define gets ( strP )
Parameters
Returns
A pointer to the string read from the input stream. If an error or EOF occurs before any characters are read, returns NULL
.
Comments
The returned string does not include a null terminator. You must ensure that the input line, if any, is sufficiently short to fit in the string.
printf Macro
Purpose
Calls Sioprintf()
to write formatted output to the stdout output stream.
Declared In
StdIOPalm.h
Prototype
#define printf ( formatP, ... )
Parameters
-
→
formatP
- A pointer to a format string that controls how subsequent arguments are converted for output.
-
→ ...
- Zero or more parameters to be formatted as specified by the
formatP
string.
Returns
Returns the number of characters written out (not including the null terminator used to end output strings).
Comments
This function internally calls StrVPrintF()
to do the formatting. See that function for details on which format specifications are supported. Returns a negative number if there is an error.
putc Macro
Purpose
Calls Siofputc()
to write a character to the output stream.
Declared In
StdIOPalm.h
Prototype
#define putc ( c, fs )
Parameters
-
→
c
- A character to write to the output stream.
-
→
fs
- An output stream to which to write the character. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented.
Returns
The character that was written. If an error occurs, the value EOF
is returned.
putchar Macro
Purpose
Calls Siofputc()
to write a character to the stdout
output stream.
Declared In
StdIOPalm.h
Prototype
#define putchar ( c )
Parameters
Returns
The character that was written. If an error occurs, the value EOF
is returned.
puts Macro
Purpose
Calls Sioputs()
to write a string to the output stream stdout
.
Declared In
StdIOPalm.h
Prototype
#define puts ( strP )
Parameters
Returns
Returns a nonnegative value on success and the value EOF
on error.
SioAddCommand Function
Purpose
Adds a built-in command that is supplied by the standard IO provider application.
Declared In
StdIOPalm.h
Prototype
void SioAddCommand ( const Char *cmdStr, SioMainProcPtr cmdProcP )
Parameters
-
→
cmdStr
- Pointer to a string that is the command name.
-
→
cmdProcP
- Pointer to the command entry point function (the
SioMain()
function).
Returns
Comments
This routine is useful for registering a command that is inside the standard IO provider application instead of in its own database.
This routine must be used to test commands under the Simulator since it can't launch application databases.
Siofgetc Function
Purpose
Return the next character from the input stream.
Declared In
StdIOPalm.h
Prototype
Int16 Siofgetc ( FILE *fs )
Parameters
-
→
fs
- An input stream from which to read the next character. You can specify only the value
stdin
for this parameter; alternate streams are not currently implemented.
Returns
The next character from the input stream. The return value EOF
indicates an error occurred.
See Also
Siofgets Function
Purpose
Return a string from the input stream.
Declared In
StdIOPalm.h
Prototype
Char *Siofgets ( Char *strP, UInt16 maxChars, FILE *fs )
Parameters
-
←
strP
- A pointer to the returned string.
-
→
maxChars
- The number of characters to read from the input stream, plus one for the null terminator.
-
→
fs
- An input stream from which to read the next character. You can specify only the value
stdin
for this parameter; alternate streams are not currently implemented.
Returns
A pointer to the string read from the input stream. If an error or EOF occurs before any characters are read, returns NULL
.
Comments
The returned string is always terminated by a null character.
See Also
Siofprintf Function
Purpose
Write formatted output to an output stream.
Declared In
StdIOPalm.h
Prototype
Int16 Siofprintf ( FILE *fs, const Char *formatP, ... )
Parameters
-
→
fs
- An output stream to which to write the formatted output. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented. -
→
formatP
- A pointer to a format string that controls how subsequent arguments are converted for output.
-
→ ...
- Zero or more parameters to be formatted as specified by the
formatP
string.
Returns
Returns the number of characters written out (not including the null terminator used to end output strings). Returns a negative number if there is an error.
Comments
This function internally calls StrVPrintF()
to do the formatting. See that function for details on which format specifications are supported.
See Also
Siofputc Function
Purpose
Write a character to the output stream.
Declared In
StdIOPalm.h
Prototype
Int16 Siofputc ( Int16 c, FILE *fs )
Parameters
-
→
c
- A character to write to the output stream.
-
→
fs
- An output stream to which to write the character. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented.
Returns
The character that was written. If an error occurs, the value EOF
is returned.
See Also
Siofputs Function
Purpose
Write a string to the output stream.
Declared In
StdIOPalm.h
Prototype
Int16 Siofputs ( const Char *strP, FILE *fs )
Parameters
-
→
strP
- A pointer to the string to write.
-
→
fs
- An output stream to which to write the string. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented.
Returns
Returns 0 on success and the value EOF
on error.
See Also
Siogets Function
Purpose
Read a string from the stdin
input stream.
Declared In
StdIOPalm.h
Prototype
Char *Siogets ( Char *strP )
Parameters
Returns
A pointer to the string read from the input stream. If an error or EOF occurs before any characters are read, returns NULL
.
Comments
The returned string does not include a null terminator. You must ensure that the input line, if any, is sufficiently short to fit in the string.
See Also
Sioprintf Function
Purpose
Write formatted output to the stdout
output stream.
Declared In
StdIOPalm.h
Prototype
Int16 Sioprintf ( const Char *formatP, ... )
Parameters
-
→
formatP
- A pointer to a format string that controls how subsequent arguments are converted for output.
-
→ ...
- Zero or more parameters to be formatted as specified by the
formatP
string.
Returns
Returns the number of characters written out (not including the null terminator used to end output strings).
Comments
This function internally calls StrVPrintF()
to do the formatting. See that function for details on which format specifications are supported. Returns a negative number if there is an error.
See Also
Sioputs Function
Purpose
Write a string to the output stream stdout
.
Declared In
StdIOPalm.h
Prototype
Int16 Sioputs ( const Char *strP )
Parameters
Returns
Returns a nonnegative value on success and the value EOF
on error.
See Also
Siosystem Function
Purpose
Execute another Stdio command.
Declared In
StdIOPalm.h
Prototype
Int16 Siosystem ( const Char *cmdStrP )
Parameters
Returns
Returns a value >= 0 on success or < 0 on failure.
Comments
This function first looks for a built-in command with the specified name. If none is found, it looks for a Stdio application database with the name "Cmd-cmdname" where cmdname is the first word in the command string cmdStrP
.
See Also
Siovfprintf Function
Purpose
Write formatted output to the stdout
output stream.
Declared In
StdIOPalm.h
Prototype
Int16 Siovfprintf ( FILE *fs, const Char *formatP, _Palm_va_list args )
Parameters
-
→
fs
- An output stream to which to write the formatted output. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented. -
→
formatP
- A pointer to a format string that controls how subsequent arguments are converted for output.
-
→
args
- A pointer to a list of zero or more parameters to be formatted as specified by the
formatP
string.
Returns
Returns the number of characters written out (not including the null terminator used to end output strings). Returns a negative number if there is an error.
Comments
This function internally calls StrVPrintF()
to do the formatting. See that function for details on which format specifications are supported.
See Also
sprintf Macro
Purpose
Calls StrPrintF()
to write formatted output to the stdout output stream.
Declared In
StdIOPalm.h
Prototype
#define sprintf ( formatP, ... )
Parameters
-
→
formatP
- A pointer to a format string that controls how subsequent arguments are converted for output.
-
→ ...
- Zero or more parameters to be formatted as specified by the
formatP
string.
Returns
Returns the number of characters written out (not including the null terminator used to end output strings).
Comments
See StrVPrintF()
for details on which format specifications are supported. Returns a negative number if there is an error.
system Macro
Purpose
Calls Siosystem()
to execute another Stdio command.
Declared In
StdIOPalm.h
Prototype
#define system ( cmdStrP )
Parameters
Returns
Returns a value >= 0 on success or < 0 on failure.
Comments
This function first looks for a built-in command with the specified name. If none is found, it looks for a Stdio application database with the name "Cmd-cmdname" where cmdname is the first word in the command string cmdStrP
.
See Also
vfprintf Macro
Purpose
Calls Siovfprintf()
to write formatted output to the stdout output stream.
Declared In
StdIOPalm.h
Prototype
#define vfprintf ( fs, formatP, args )
Parameters
-
→
fs
- An output stream to which to write the formatted output. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented. -
→
formatP
- A pointer to a format string that controls how subsequent arguments are converted for output.
-
→
args
- A pointer to a list of zero or more parameters to be formatted as specified by the
formatP
string.
Returns
Returns the number of characters written out (not including the null terminator used to end output strings). Returns a negative number if there is an error.
Comments
This function internally calls StrVPrintF()
to do the formatting. See that function for details on which format specifications are supported.
vsprintf Macro
Purpose
Calls StrVPrintF()
to write formatted output to the stdout output stream.
Declared In
StdIOPalm.h
Prototype
#define vsprintf (fs
,formatP
,args
)
Parameters
-
→
fs
- An output stream to which to write the formatted output. You can specify only the value
stdout
for this parameter; alternate streams are not currently implemented. -
→
formatP
- A pointer to a format string that controls how subsequent arguments are converted for output.
-
→
args
- A pointer to a list of zero or more parameters to be formatted as specified by the
y
string.
Returns
Returns the number of characters written out (not including the null terminator used to end output strings). Returns a negative number if there is an error.
Comments
See StrVPrintF()
for details on which format specifications are supported.
Standard IO Provider Functions
These functions are used by a standard IO provider application.
SioClearScreen Function
Purpose
Clears the entire standard IO output field.
Declared In
StdIOProvider.h
Prototype
void SioClearScreen ( void )
Parameters
Returns
SioExecCommand Function
Purpose
Declared In
StdIOProvider.h
Prototype
Int16 SioExecCommand ( const Char *cmd )
Parameters
Returns
Returns a value >= 0 on success or < 0 on failure.
Comments
This function first looks for a built-in command with the specified name. If none is found, it looks for a Stdio application database with the name "Cmd-cmdname" where cmdname is the first word in the command string cmd
.
If you pass the string "help" or "?" for the cmd
parameter, SioExecCommand
causes a help string to be printed for each built-in command. It actually executes each built-in command, passing the string "?" as argv[1]
. Each command should handle this argument by printing a help line.
The SioExecCommand
function is faster than calling system()
to execute a command. However, SioExecCommand
can be called only by the standard IO provider application, not the standard IO application.
SioFree Function
Purpose
Closes down the standard IO manager.
Declared In
StdIOProvider.h
Prototype
Err SioFree ( void )
Parameters
Returns
SioHandleEvent Function
Purpose
Handles an event in the form that contains the standard IO output field and scroll arrows if the event belongs to the text field or scroll arrows.
Declared In
StdIOProvider.h
Prototype
Boolean SioHandleEvent ( SysEventType *event )
Parameters
Returns
Returns true
if the event was handled and should not be processed by the application's own form event handler; returns false
otherwise.
Comments
This function must be called from the form event handler before it does its own processing with any of the objects unrelated to standard IO in the form.
SioInit Function
Purpose
Initializes the standard IO manager.
Declared In
StdIOProvider.h
Prototype
Err SioInit ( UInt16 formID, UInt16 fieldID, UInt16 scrollerID )
Parameters
-
→
formID
- The ID of the form that contains the input/output field.
-
→
fieldID
- The ID of the field to be used for input/output.
-
→
scrollerID
- The ID of the scroller associated with the input/output form.
Returns
Application-Defined Function
You must supply this function in your stdio application.
SioMain Function
Purpose
The main entry point for the stdio application.
Declared In
StdIOPalm.h
Prototype
Int16 SioMain ( UInt16 argc, const Char *argv[] )
Parameters
-
→
argc
- The number of parameters passed on the command line.
-
→
argv
- An array of character pointers, one for each parameter passed on the command line.
Returns
The return value from this routine is passed back to the system call that invoked it. Return 0 for no error.