Standard IO
 

 < 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

-> fsAn 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

<- strPA pointer to the returned string.
-> maxCharsThe number of characters to read from the input stream, plus one for the null terminator.
-> fsAn 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

-> fsAn 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.
-> formatPA 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

-> cA character to write to the output stream.
-> fsAn 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

-> strPA pointer to the string to write.
-> fsAn 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

<- strPA 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

-> formatPA 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

-> cA character to write to the output stream.
-> fsAn 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

-> cA 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

-> strPA 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

-> cmdStrPointer to a string that is the command name.
-> cmdProcPPointer 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

-> fsAn 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

<- strPA pointer to the returned string.
-> maxCharsThe number of characters to read from the input stream, plus one for the null terminator.
-> fsAn 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

-> fsAn 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.
-> formatPA 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

-> cA character to write to the output stream.
-> fsAn 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

-> strPA pointer to the string to write.
-> fsAn 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

<- strPA 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

-> formatPA 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

-> strPA 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

-> cmdStrPA 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

-> fsAn 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.
-> formatPA pointer to a format string that controls how subsequent arguments are converted for output.
-> argsA 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

-> formatPA 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

-> cmdStrPA 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

-> fsAn 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.
-> formatPA pointer to a format string that controls how subsequent arguments are converted for output.
-> argsA 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

-> fsAn 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.
-> formatPA pointer to a format string that controls how subsequent arguments are converted for output.
-> argsA 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

-> cmdA 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

-> eventPointer 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

-> formIDThe ID of the form that contains the input/output field.
-> fieldIDThe ID of the field to be used for input/output.
-> scrollerIDThe 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

-> argcThe number of parameters passed on the command line.
-> argvAn 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.