Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

51    Standard IO

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

The macros and functions in this section enable standard IO.

fgetc Macro ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

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 ^TOP^

Purpose

Calls Siogets() to read a string from the stdin input stream.

Declared In

StdIOPalm.h

Prototype

#define gets (
   strP
)

Parameters

strP
A pointer to the returned string.

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 ^TOP^

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 ^TOP^

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 ^TOP^

Purpose

Calls Siofputc() to write a character to the stdout output stream.

Declared In

StdIOPalm.h

Prototype

#define putchar (
   c
)

Parameters

c
A character to write to the stdout output stream.

Returns

The character that was written. If an error occurs, the value EOF is returned.

puts Macro ^TOP^

Purpose

Calls Sioputs() to write a string to the output stream stdout.

Declared In

StdIOPalm.h

Prototype

#define puts (
   strP
)

Parameters

strP
A pointer to the string to write to stdout.

Returns

Returns a nonnegative value on success and the value EOF on error.

SioAddCommand Function ^TOP^

Purpose

Adds a built-in command that is supplied by the standard IO provider application.

Declared In

StdIOPalm.h

Prototype

void SioAddCommand (
   constChar*cmdStr,
   SioMainProcPtrcmdProcP
)

Parameters

cmdStr
Pointer to a string that is the command name.
cmdProcP
Pointer to the command entry point function (the SioMain() function).

Returns

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 Function ^TOP^

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

fgetc()

Siofgets Function ^TOP^

Purpose

Return a string from the input stream.

Declared In

StdIOPalm.h

Prototype

Char *Siofgets (
   Char*strP,
   UInt16maxChars,
   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

fgets()

Siofprintf Function ^TOP^

Purpose

Write formatted output to an output stream.

Declared In

StdIOPalm.h

Prototype

Int16 Siofprintf (
   FILE*fs,
   constChar*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

fprintf()

Siofputc Function ^TOP^

Purpose

Write a character to the output stream.

Declared In

StdIOPalm.h

Prototype

Int16 Siofputc (
   Int16c,
   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

fputc()

Siofputs Function ^TOP^

Purpose

Write a string to the output stream.

Declared In

StdIOPalm.h

Prototype

Int16 Siofputs (
   constChar*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

fputs()

Siogets Function ^TOP^

Purpose

Read a string from the stdin input stream.

Declared In

StdIOPalm.h

Prototype

Char *Siogets (
   Char*strP
)

Parameters

strP
A pointer to the returned string.

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

gets()

Sioprintf Function ^TOP^

Purpose

Write formatted output to the stdout output stream.

Declared In

StdIOPalm.h

Prototype

Int16 Sioprintf (
   constChar*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

printf()

Sioputs Function ^TOP^

Purpose

Write a string to the output stream stdout.

Declared In

StdIOPalm.h

Prototype

Int16 Sioputs (
   constChar*strP
)

Parameters

strP
A pointer to the string to write to stdout.

Returns

Returns a nonnegative value on success and the value EOF on error.

See Also

puts()

Siosystem Function ^TOP^

Purpose

Execute another Stdio command.

Declared In

StdIOPalm.h

Prototype

Int16 Siosystem (
   constChar*cmdStrP
)

Parameters

cmdStrP
A pointer to a string containing the command line to execute.

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

SioExecCommand(), system()

Siovfprintf Function ^TOP^

Purpose

Write formatted output to the stdout output stream.

Declared In

StdIOPalm.h

Prototype

Int16 Siovfprintf (
   FILE*fs,
   constChar*formatP,
   _Palm_va_listargs
)

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

vfprintf()

sprintf Macro ^TOP^

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 ^TOP^

Purpose

Calls Siosystem() to execute another Stdio command.

Declared In

StdIOPalm.h

Prototype

#define system (
   cmdStrP
)

Parameters

cmdStrP
A pointer to a string containing the command line to execute.

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

SioExecCommand()

vfprintf Macro ^TOP^

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 ^TOP^

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 ^TOP^

These functions are used by a standard IO provider application.

SioClearScreen Function ^TOP^

Purpose

Clears the entire standard IO output field.

Declared In

StdIOProvider.h

Prototype

void SioClearScreen (
   void
)

Parameters

None.

Returns

Returns nothing.

SioExecCommand Function ^TOP^

Purpose

Executes a command line.

Declared In

StdIOProvider.h

Prototype

Int16 SioExecCommand (
   constChar*cmd
)

Parameters

cmd
A pointer to a string containing the command line to execute.

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 ^TOP^

Purpose

Closes down the standard IO manager.

Declared In

StdIOProvider.h

Prototype

Err SioFree (
   void
)

Parameters

None.

Returns

Returns 0 on success.

SioHandleEvent Function ^TOP^

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

event
Pointer to an EventType structure.

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 ^TOP^

Purpose

Initializes the standard IO manager.

Declared In

StdIOProvider.h

Prototype

Err SioInit (
   UInt16formID,
   UInt16fieldID,
   UInt16scrollerID
)

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

Returns 0 on success.

Application-Defined Function ^TOP^

You must supply this function in your stdio application.

SioMain Function ^TOP^

Purpose

The main entry point for the stdio application.

Declared In

StdIOPalm.h

Prototype

Int16 SioMain (
   UInt16argc,
   constChar*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.