< Home < Developers < Development Support < Documentation

## 47 Standard IO

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 47 Standard IO Standard IO Functions fgetc fgets fprintf fputc fputs getchar gets printf putc putchar puts SioAddCommand Siofgetc Siofgets Siofprintf Siofputc Siofputs Siogets Sioprintf Sioputs Siosystem Siovfprintf sprintf system vfprintf vsprintf Standard IO Provider Functions SioClearScreen SioExecCommand SioFree SioHandleEvent SioInit Application-Defined Function SioMain |  |  |  | This chapter provides reference material for the standard IO API: Standard IO Functions Standard IO Provider Functions Application-Defined Function 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 The macros and functions in this section enable standard IO. ## fgetc #### Purpose Macro that calls Siofgetc to return the next character from the input stream. #### Prototype 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.
#### Result The next character from the input stream. The return value EOF indicates an error occurred. ## fgets #### Purpose Macro that calls Siofgets to return a string from the input stream. #### Prototype 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.
#### Result 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 #### Purpose Macro that calls Siofprintf to write formatted output to an output stream. #### Prototype 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.
#### Result 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 #### Purpose Macro that calls Siofputc to write a character to the output stream. #### Prototype 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.
#### Result The character that was written. If an error occurs, the value EOF is returned. ## fputs #### Purpose Macro that calls Siofputs to write a string to the output stream. #### Prototype 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.
#### Result Returns 0 on success and the value EOF on error. ## getchar #### Purpose Macro that calls Siofgetc to read the next character from the stdin input stream. #### Prototype getchar () #### Result The next character from the input stream. The return value EOF indicates an error occurred. ## gets #### Purpose Macro that calls Siogets to read a string from the stdin input stream. #### Prototype gets (strP) #### Parameters #####
<- strP | A pointer to the returned string.
#### Result 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 #### Purpose Macro that calls Sioprintf to write formatted output to the stdout output stream. #### Prototype 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.
#### Result 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 #### Purpose Macro that calls Siofputc to write a character to the output stream. #### Prototype 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.
#### Result The character that was written. If an error occurs, the value EOF is returned. ## putchar #### Purpose Macro that calls Siofputc to write a character to the stdout output stream. #### Prototype putchar (c) #### Parameters #####
-> c | A character to write to the stdout output stream.
#### Result The character that was written. If an error occurs, the value EOF is returned. ## puts #### Purpose Macro that calls Sioputs to write a string to the output stream stdout. #### Prototype puts (strP) #### Parameters #####
-> strP | A pointer to the string to write to stdout.
#### Result Returns a nonnegative value on success and the value EOF on error. ## SioAddCommand #### Purpose Adds a built-in command that is supplied by the standard IO provider application. #### 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).
#### Result Returns nothing. #### 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 Return the next character from the input stream. #### 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.
#### Result The next character from the input stream. The return value EOF indicates an error occurred. #### See Also fgetc ## Siofgets #### Purpose Return a string from the input stream. #### 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.
#### Result 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 fgets ## Siofprintf #### Purpose Write formatted output to an output stream. #### 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.
#### Result 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 fprintf ## Siofputc #### Purpose Write a character to the output stream. #### 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.
#### Result The character that was written. If an error occurs, the value EOF is returned. #### See Also fputc ## Siofputs #### Purpose Write a string to the output stream. #### 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.
#### Result Returns 0 on success and the value EOF on error. #### See Also fputs ## Siogets #### Purpose Read a string from the stdin input stream. #### Prototype Char *Siogets (Char *strP) #### Parameters #####
<- strP | A pointer to the returned string.
#### Result 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 gets ## Sioprintf #### Purpose Write formatted output to the stdout output stream. #### 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.
#### Result 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 printf ## Sioputs #### Purpose Write a string to the output stream stdout. #### Prototype Int16 Sioputs (const Char *strP) #### Parameters #####
-> strP | A pointer to the string to write to stdout.
#### Result Returns a nonnegative value on success and the value EOF on error. #### See Also puts ## Siosystem #### Purpose Execute another Stdio command. #### Prototype Int16 Siosystem (const Char *cmdStrP) #### Parameters #####
-> cmdStrP | A pointer to a string containing the command line to execute.
#### Result 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 SioExecCommand, system ## Siovfprintf #### Purpose Write formatted output to the stdout output stream. #### 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.
#### Result 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 vfprintf ## sprintf #### Purpose Macro that calls StrPrintF to write formatted output to the stdout output stream. #### Prototype 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.
#### Result 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 #### Purpose Macro that calls Siosystem to execute another Stdio command. #### Prototype system (cmdStrP) #### Parameters #####
-> cmdStrP | A pointer to a string containing the command line to execute.
#### Result 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 SioExecCommand ## vfprintf #### Purpose Macro that calls Siovfprintf to write formatted output to the stdout output stream. #### Prototype 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.
#### Result 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 #### Purpose Macro that calls StrVPrintF to write formatted output to the stdout output stream. #### Prototype 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.
#### Result 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 #### Purpose Clears the entire standard IO output field. #### Prototype void SioClearScreen (void) #### Parameters #####
None.
#### Result Returns nothing. ## SioExecCommand #### Purpose Executes a command line. #### Prototype Int16 SioExecCommand (const Char *cmd) #### Parameters #####
-> cmd | A pointer to a string containing the command line to execute.
#### Result 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 #### Purpose Closes down the standard IO manager. #### Prototype Err SioFree (void) #### Parameters #####
None.
#### Result Returns 0 on success. ## SioHandleEvent #### 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. #### Prototype Boolean SioHandleEvent (SysEventType *event) #### Parameters #####
-> event | Pointer to an EventType structure.
#### Result 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 #### Purpose Initializes the standard IO manager. #### 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.
#### Result Returns 0 on success. ## Application-Defined Function You must supply this function in your stdio application. ## SioMain #### Purpose The main entry point for the stdio application. #### 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.
#### Result The return value from this routine is passed back to the system call that invoked it. Return 0 for no error. |