ANSI-compatible file and TTY input/output routines
Note: This implementation of stdio.h is 90% compatible with the ANSI standard. I tried to make all functions to be as close to ANSI as possible, without introducing a too large overload in the generated code. The main difference is the fact that there are no terminal-associated file streams like stdin and stdout which may be redirected. However, functions from this header file are mostly not TIOS functions - they are completely written by us, so they are not embedded in the TIOS. That's why their use may cause your program to be larger than if you don't use functions from this header file. The typical increase in size is 300-2000 bytes, depending on which functions and how many different functions from this header file are used in the program. Functions from the scanf family are the worst offenders, using any of them takes about 1500 bytes. So, although functions from this header file are much more "standard" than TIOS-specific functions, it is better to avoid functions like fopen etc. Instead, use "non-standard" functions from the vat.h header file. Also avoid using scanf family functions if you don't really have to. Prefer getsn for input, and atoi family functions for parsing. Of course, functions from this header file may be very useful for porting a program from a "standard" computer to the TI. But I will repeat again: it is better to avoid them.
| void cbprintf (vcbprintf_Callback_t callback, void **param, const char *format, ...); |
Callback printing function.
cbprintf is an alternate entry point to the vcbprintf function.
The difference is that the argument is passed directly through the stack instead of through an
argument list pointer.
It is implemented here as an assembly wrapper which calls vcbprintf.
| short cbscanf(vcbscanf_get_Callback_t getfun, vcbscanf_unget_Callback_t ungetfun, void *param, const char *format, ...); |
Callback parsing function.
cbscanf is an alternate entry point to the vcbscanf function. The difference is that the argument is passed directly through the stack instead of through an argument list pointer.
| void clearerr (FILE *stream); |
Resets error indication.
clearerr resets the error and end-of-file indicators of the stream associated to the structure pointed to by stream to 0. Once the error indicator is set, stream operations continue to return error status until a call is made to clearerr or rewind.
| void clrscr (void); |
Clears the screen and resets the print position.
Function clrscr is very similar to stantard TIOS function ClrScr (defined in graph.h header file). The difference is in fact that clrscr moves the current print/plot position to (0, 0), but with ClrScr the current print/plot position remains intact. More precise, clrscr calls ClrScr then MoveTo passing two zeros as arguments. Always use clrscr instead of ClrScr if you want to use TTY printing functions like puts, printf etc.
| short fclose (FILE *stream); |
Closes a stream.
fclose closes the stream associated to the structure pointed to by stream. In this implementation, fclose unlocks the file (which is locked during it is opened), and frees the file descriptor structure pointed to by stream. fclose returns 0 on success. It returns EOF if any errors were detected.
| short feof (FILE *stream); |
Tests a stream for an end-of-file indicator.
feof is a macro that tests the stream associated to the structure pointed to by stream for an end-of-file indicator. Once the indicator is set, read operations on the file return the indicator until fseek, fsetpos or rewind is called, or until the stream is closed. feof returns nonzero if an end-of-file indicator was detected on the last (usually input) operation on the given stream. It returns 0 if end-of-file has not been reached.
| short ferror (FILE *stream); |
Tests a stream for a read or write error.
ferror is a macro that tests the stream associated to the structure pointed to by stream for a read or write error. It the stream's error indicator has been set, it remains set (and all file I/O operations will return error) until clearerr or rewind is called, or until the stream is closed. ferror returns nonzero if an error was detected on the named stream.
| short fflush (FILE *stream); |
Flushes a stream.
fflush is supposed to flush the output buffer for stream to the associated file if the given stream has buffered output. As the TI file system is not buffered (of course), fflush has no effect, except for undoing the effect of the ungetc function. fflush returns 0 on success (which is always the case on the TI).
| short fgetc (FILE *stream); |
Function version of fgetc.
fgetc is usually equal to getc, except fgetc is implemented as a function, but getc is implemented as a macro.
| short fgetchar (void); |
Function version of getchar.
fgetchar is equal to getchar, except fgetchar is implemented as a function, but getchar is implemented as a macro.
| short fgetpos (FILE *stream, fpos_t *pos); |
Gets the current file pointer position.
fgetpos stores the position of the file pointer associated with the stream associated with
the structure pointed to by stream in the location pointed to by pos
The exact value is irrelevant. On success, fgetpos returns 0. On failure, it returns a nonzero
value.
Note: fgetpos is implemented here as a macro which calls ftell.
| char *fgets (char *s, short n, FILE *stream); |
Gets a string from a stream.
fgets reads characters from stream associated to the structure pointed to by stream
into the string s. It does this by calling fgetc repeatedly.
The function stops reading when it reads either
n - 1 characters or a '\r' (0x0D) character,
whichever comes first. fgets retains the newline character at the end of s,
eventually translated to '\n' character if the stream is opened in "text" mode (see
fopen). A null byte is appended to s to mark the end of the
string. On success, fgets returns the string pointed to by s.
It returns NULL in a case of error.
Note: fgets is used mainly with files opened in "text" mode. As an example, this command may be
useful for reading a text line from a TEXT variable.
| FILE *fopen (const char *filename, const char *mode); |
Opens a stream.
fopen opens the file named by filename (this is a normal C string, which should
be in lowercase) and associates a stream with it. fopen returns a pointer to be used to identify the
stream in subsequent operations. The mode string used in calls to fopen is one of
the following values:
| Mode | Description |
| r | Open for reading only. |
| w | Create for writing. If a file by that name already exists, it will be overwritten. |
| a | Append; open for writing at end of file, or create for writing if the file does not exist. |
| r+ | Open an existing file for update (reading and writing). |
| w+ | Create a new file for update (reading and writing). If a file by that name already exists, it will be overwritten. |
| a+ | Open for append; open for update at the end of the file, or create if the file does not exist. |
FILE *f = fopen ("example", "w");
fputs ("First line\n", f);
fputs ("Second line\n", f);
fputs ("Third line\n", f);
fclose (f);
After this, you will have a TEXT variable called "example" which can be opened in text editor.
You can read the content of a TEXT variable similarly.
When a file is opened in "binary" mode, nothing is assumed about the structure of the file.
It can be a variable of any type. The user is responsible to create appropriate variable
structure. There will no be any translation of characters, and after opening the file pointer
will point to the first byte of the variable (after two "length" bytes), regardless of what
the variable is supposed to be. For example, the string variable has the following structure:
one zero byte, the content of the string, another zero byte, and finally, the string tag
(STR_TAG or 0x2D byte). Here is an example of creating a file which
represents a string variable:
FILE *f = fopen ("example", "wb");
fputc (0, f);
fputs ("This is a string", f);
fputc (0, f);
fputc (STR_TAG, f);
fclose (f);
When a file is opened for update (in both text or binary mode), both input and output can be done on the
resulting stream. However, ANSI proposes that output cannot be followed directly by input without
an intervening fseek or rewind, and that input
cannot be directly followed by output without an intervening fseek,
rewind, or an input that encounters end-of-file. I don't see any reason
to implement such limitation here.
The filename pointed to by filename may also contain a path (i.e. a folder name may be
given in front of the file name). If name of a folder which does not exist is given, and if
fopen needs to create a new file, a dialog will appear which asks the user whether a new folder
will be created. If the answer is "NO", fopen fails, returning NULL.
If no folder name is given, the current folder is assumed.
Note: All functions which accept a parameter which is a pointer to a FILE
structure assumes that the pointer is valid, i.e. created using fopen command. As I have no
any efficient method to check whether the pointer is valid or not, no checking is implemented.
So, if you pass an invalid pointer to any file handling function, the results are
unpredictable.
| short fprintf (FILE *stream, const char *format, ...); |
Sends formatted output to a stream.
fprintf sends formatted output to a string. In fact, it does the following:
accepts a series of arguments;
applies to each argument a format specifier contained in the format string pointed to by format (see printf for details on format specifiers);
outputs the formatted data to the stream associated with the structure pointed to by stream
There must be the same number of format specifiers as arguments. fprintf returns the number of bytes output. In the event of error, it returns EOF.
| short fputc (short c, FILE *stream); |
Function version of fputc.
fputc is usually equal to putc, except fputc is implemented as a function, but putc is implemented as a macro.
| short fputchar (short c); |
Function version of putchar.
fputchar is usually equal to putchar, except fputchar is implemented as a function, but putchar is implemented as a macro.
| short fputs (const char *s, FILE *stream); |
Outputs a string to a stream.
fputs copies the null-terminated string s to the output stream associated to the structure pointed to by stream. It does this by calling putc repeatedly. It does not append a newline character, and the terminating null character is not copied. On successful completion, fputs returns the last character written. Otherwise, it returns a value of EOF.
| unsigned short fread (void *ptr, unsigned short size, unsigned short n, FILE *stream); |
Reads data from a stream.
fread reads n items of data, each of length size bytes, from the input
stream associated with the structure pointed to by stream into a block pointed to
by ptr. The total number of bytes read is n x size. fread
fread returns the number of items (not bytes) actually read. If the operation was sucessful,
the returned result should be equal to n. In a case of error, returned result will
be smaller (possibly zero).
Note: fread is proposed to be used in "binary" mode (see fopen).
Although this is not strictly necessary, it is is highly recommended opening stream
in "binary" mode if you want to use this function. Anyway,
there will not be any character translations during reading, even if the file is opened in
"text" mode. This function was buggy in releases of TIGCCLIB prior to 2.2; this is now fixed.
| FILE *freopen (const char *filename, const char *mode, FILE *stream); |
Associates a new file with an open stream.
freopen substitutes the named file in place of the open stream. It closes stream, regardless of whether the open succeeds. In this implementation, freopen is implemented as macro which first calls fclose passing stream to it, then calls fopen passing filename and mode to it. Such implementation is not absolutely correct, because the address of the file descriptor structure may be changed after closing and reopening again (if a garbage collect occurs). This is not a problem in programs which uses freopen as in
f=freopen (name, mode, f);
but it might cause problems in programs which uses freopen as in
freopen (name, mode, f);
To solve this problem, freopen macro will always re-assign the variable f to
a (eventually) new value, so both above examples will be correct (the only small
problem is in fact that f must ultimately be an lvalue, i.e, a variable or
something similar).
On successful completion, freopen returns the argument stream (possibly
changed). In the event of error, it returns NULL.
Note: This function is usually used for redirecting terminal streams like
stdout and stdin. This is not possible here,
because terminal-associated streams are not implemented.
| short fscanf(FILE *file, const char *format, ...); |
File parsing function.
Works like sscanf, but reads the input from the file file
rather than from a buffer of type char *.
| short fseek (FILE *stream, long offset, short whence); |
Repositions the file pointer of a stream.
fseek sets the file pointer associated with stream to a new position that is
offset bytes from the file location given by whence.
For text mode streams (see fopen), offset should be 0 or a value returned
by ftell. whence must be one of the following values
(defined in enum SeekModes):
| whence | File location |
| SEEK_SET | File beginning |
| SEEK_CUR | Current file pointer position |
| SEEK_END | End-of-file |
| void fsetbufsize (unsigned short newsize, FILE *f); |
Sets the buffer size of a file.
fsetbufsize sets the buffer size of an open file. The buffer size determines how much memory is reallocated to the file every time a write needs more memory from the heap. The default size (128 bytes) is set when the file is opened and should be sufficient for most uses. Setting a larger value will make writes faster at the cost of possibly running out of memory prematurely. If newsize is zero or f is NULL, no changes will be made.
| short fsetpos (FILE *stream, const fpos_t *pos); |
Positions the file pointer of a stream.
fsetpos sets the file pointer associated with stream to a new position
(given in the variable pointed to by pos). The new position is the value
obtained by a previous call to fgetpos on that stream.
It also clears the end-of-file indicator on the file that stream points to
and undoes any effects of ungetc on that file.
On success, fsetpos returns 0. On failure, it returns a nonzero value.
Note: fgetpos is implemented here as a macro which calls fseek.
| long ftell (const FILE *stream); |
Returns the current file pointer.
ftell returns the current file pointer for the stream associated with the structure pointed to by stream. The offset is measured in bytes from the beginning of the file. The value returned by ftell can be used in a subsequent call to fseek. ftell returns the current file pointer position on success. It returns EOF on error.
| unsigned short fwrite (const void *ptr, unsigned short size, unsigned short n, FILE *stream); |
Writes data to a stream.
fwrite writes n items of data, each of length size bytes, to the output
file associated with the structure pointed to by stream. The data written begins at ptr.
The total number of bytes written is n x size. ptr in the declarations
is a pointer to any object. fwrite returns the number of items (not bytes) actually written.
If the operation was sucessful,
the returned result should be equal to n. In a case of error, returned result will
be smaller (possibly zero).
Note: fwrite is proposed to be used in "binary" mode (see fopen).
Although this is not strictly necessary, it is is highly recommended opening stream
in "binary" mode if you want to use this function. Anyway,
there will not be any character translations during writing, even if the file is opened in
"text" mode. This function was buggy in releases of TIGCCLIB prior to 2.2; this is now fixed.
| #define getc fgetc |
Gets a character from a stream.
getc gets the next character on the given input stream (associated with the structure
pointed to by stream), and increments the stream's file pointer to point to the
next character. If the file is opened in "text" mode (see fopen),
a character after '\r' will be swallowed during reading (to skip over the "command byte" at
the begining of the each line in a TEXT variable).
On success, getc returns the character read, after converting it to an integer
without sign extension. On error (usually end-of-file), it returns EOF.
| #define getchar fgetchar |
Gets a character from the keyboard (with echoing to the screen).
fgetchar returns the character read from the keyboard. It is similar to
ngetchx except getchar shows a cursor (a simple
underscore), echoes the character read on the screen and supports the CHAR
menu. '\r' character (i.e. ENTER key) will be echoed as a "new line".
Note: In ANSI C, getchar(c) is equal to getc(c, stdin), so it can be redirected
using freopen. This is not possible here, because stdin
is not implemented as a file stream.
| char *gets (char *string); |
Gets a string from the keyboard.
gets collects a string of characters terminated by a new line from the keyboard (by repeated calling to getchar) and puts it into string. The new line is replaced by a null character ('\0') in string. gets returns when it encounters a new line (i.e. when the ENTER key is pressed); everything up to the new line is copied into string. gets returns the string argument string (ANSI proposes returning of NULL in a case of error, but this never occurs on the TI). For editing, the backspace key is supported. Here is an example of usage:
char buffer[50];
int a, b;
clrscr ();
puts ("A = ");
a = atoi (gets (buffer));
puts ("B = ");
b = atoi (gets (buffer));
printf ("%d + %d = %d", a, b, a+b);
atoi is an ANSI C standard function from stdlib.h
header file.
Important: gets does not check buffer bounds, so using
getsn or a custom input routine is recommended instead.
See also: getsn, How can I get input from the keyboard?, textedit.h
| char *getsn (char *string, unsigned long maxlen); |
Gets a string from the keyboard avoiding buffer overflows.
getsn works like gets, but with a maximum length specified.
The maximum length (maxlen) is the total size of the buffer. In other words, the
null-terminator is included in the maximum length. When the buffer is full (i.e. when the
string length is maxlen - 1), getsn will not accept any more characters.
Only backspace or ENTER are allowed in that situation.
Here is an example of usage:
char buffer[50];
int a, b;
clrscr ();
puts ("A = ");
a = atoi (getsn (buffer, 50));
puts ("B = ");
b = atoi (getsn (buffer, 50));
printf ("%d + %d = %d", a, b, a+b);
atoi is an ANSI C standard function from stdlib.h
header file.
Note: getsn is not an ANSI C standard function, but the equivalent of
fgets (buffer, maxlen, stdin) in ANSI C. It is needed because terminal streams are not
implemented in TIGCCLIB.
See also: gets, fgets, How can I get input from the keyboard?, textedit.h
| void printf_xy (short x, short y, const char *format, ...); |
Sends formatted output to the fixed place on the screen.
printf_xy is similar to the standard ANSI C printf function, except:
this function displays formatted output to the screen at the strictly specified position, more precise, starting from the point (x, y);
text printed with printf_xy will not wrap at the right end of the screen (if the text is longer, the result is unpredictable);
characters '\n' will not be translated to "new line";
this function will never cause screen scrolling;
current print/plot position remains intact after executing this function.
printf_xy is a GNU C macro which calls sprintf and DrawStr.
| void printf (const char *format, ...); |
Sends formatted output to the screen.
printf is nearly full implementation of standard ANSI C printf function, which sends the formatted output to the screen in terminal (TTY) mode. In fact, it does the following:
accepts a series of arguments;
applies to each a format specifier contained in the format string pointed to by format;
outputs the formatted data to the screen.
The printed text will wrap on the right end of the screen. Characters '\n' will be translated
to "next line" (and this is the only control code which has a special implementation). The
screen will scroll upwards when necessary (i.e. after printing a text in the last screen line).
Note that all TI fonts are supported. Of course, printf will update current "print position" to a new
one after the text is printed.
printf applies the first format specifier to the first argument after format,
the second to the second, and so on. The format string, controls how printf will convert
and format its arguments. There must be enough arguments for the format; if there
are not, the results will be unpredictable and likely disastrous. Excess arguments
(more than required by the format) are merely ignored. The format string is a
character string that contains two types of objects: plain characters and
conversion specifications. Plain characters are simply copied verbatim to the
output string. Conversion specifications fetch arguments from the argument list
and apply formatting to them. printf format specifiers have the following form:
% [flags] [width] [.prec] [{h|l}] type
Here is a complete table of supported formatting options (see any book about C
language for more info):
| Flags | Meaning |
| none | Right align (pad spaces or zeros to left) |
| - | Left align (pad spaces to right) |
| + | Always force sign (include prefix '+' before positive values) |
| z | Don't postfix padding (this option is non-ANSI, i.e. TI specific) |
| space | Insert space before positive values |
| # | Prefix octal values with 0 and hex values (>0) with '0x') Force '.' in float output (and prevent trunctation of trailing zeros) |
| ^ | TI-Float format: special character for the exponent and for the minus sign, no '+' prefix in the exponent, 0. instead of 0, no leading zeros if the magnitude is smaller than 1 (this option is non-ANSI, i.e. TI specific) |
| | | Center the output in the field (this option is non-ANSI, i.e. TI specific) |
| Width | Meaning |
| num | Print at least num characters - padded the rest with blanks |
| 0num | (Zero prefixed) Same as above but padded with '0' |
| * | The width is specified in the arguments list (before value being formatted) |
| Precision | Meaning |
| none | Default precision |
| num | num is number of chars, decimal places, or number of significant digits (num<=16) to display depending on type (see below) |
| -1 | Default = 6 digits (this option is non-ANSI, i.e. TI specific) |
| * | The precision is specified in the argument list (before value being formatted) |
| Size {h|l} | Meaning |
| h | Force short integer |
| l | Force long integer |
| Type | Meaning |
| d, i | Signed decimal integer |
| u | Unsigned decimal integer |
| x | Lowercase hexadecimal integer |
| X | Uppercase hexadecimal integer |
| e | Floating point, format [-]d.dddde[sign]ddd (exponential format) |
| E | Like 'e' but with uppercase letter for the exponent |
| f | Floating point, format [-]dddd.dddd |
| g | Floating point: most compact float format available ('e' or 'f'); this is the most common option, used for most dialog floats |
| G | Like 'g' but with uppercase letter for the exponent |
| r | Floating point, engineering form (this option is non-ANSI, i.e. TI specific) |
| R | Like 'r' but with uppercase letter for the exponent |
| y | Floating point, mode specified float format (this option is non-ANSI, i.e. TI specific) |
| Y | Like 'y' but with uppercase letter for the exponent |
| c | Character |
| s | String |
| p | Pointer; principally the same as 'x' - do not use without 'l' modifier |
| % | None; the character '%' is printed instead |
int i, j;
for (j = F_4x6; j <= F_8x10; j++)
{
clrscr ();
FontSetSys (j);
for (i = 1; i <= 1000; i++)
printf ("%d ", i);
ngetchx ();
}
Note: In ANSI C, printf is an int function, and it returns the number of printed characters. Due to some practical reasons, this implementation of printf is a void function. This difference is usually not important.
| #define putc fputc |
Writes a character to a stream.
putc writes the character c to the stream given by stream. It will update the stream's file pointer, and expands the size of associated variable if necessary. If the file is opened in "text" mode (see fopen), all '\n' characters will be translated to '\r' 0x20 sequence during writting (to satisfy the format of the text in TEXT variables). On success, putc returns the character c. On error, it returns EOF.
| #define putchar fputchar |
Outputs a character to the screen in TTY mode.
Outputs a character c to the screen in TTY mode. This means the following:
The current print position will be moved in the text line after printing the last character in the screen line;
after printing the last character in the last screen line, the screen will scroll upwards;
characters '\n' will be translated to "next line" (and this is the only control code which has a special implementation);
the current print position will be updated after the character is printed.
All TI fonts are supported.
putchar returns the character c (ANSI C proposes returning EOF in
a case of error, but printing on TIOS cannot fail).
Note: In ANSI C, putchar(c) is equal as putc(c, stdout), so it can be redirected
using freopen. This is not possible here, because stdout
is not implemented as a file stream.
| void puts (const char *s); |
Outputs a string to the screen in TTY mode.
puts outputs the null-terminated string s to the screen by repeated calling to
putchar until the end of the string is reached.
Note: There are two minor differences between this implementation of puts and ANSI definition.
First, ANSI puts is an int function which returns an undefined nonnegative value, except in
a case of error (which never occurs on TI). For some practical reasons, puts is here a void
function. Second, ANSI puts automatically appends a "new line" character after the last printed
character. This implementation of puts does not append a newline automatically. My opinion is
that such implementation is more flexible, and it is not problem to append a newline ('\n')
explicitely if necessary.
| #define remove unlink |
Macro that removes a file.
remove deletes the file specified by filename. It is a macro that simply translates its call to a call to unlink (name known from UNIX). So, both remove and unlink are equal. Although ANSI C proposes rename, unlink is more common in UNIX programs.
| short rename (const char *oldname, const char *newname); |
Renames a file.
rename changes the name of a file from oldname to newname
(both filenames are normal C strings, which should be in lowercase).
Filenames may also contain folder names. Folder names in oldname and
newname need not be the same, so rename can be used to move a file from
one folder to another. On successfully renaming the file, rename returns 0. In
the event of error, EOF is returned.
Note: Function SymMove from vat.h
header file is very similar like rename, except the parameters and returned result
are somewhat different. As rename is not a TIOS entry and SymMove
is, the usage of SymMove is recommended instead of rename
(although SymMove is not ANSI standard).
| void rewind (FILE *stream); |
Repositions file pointer to stream's beginning.
rewind (stream) is equivalent to
fseek (stream, 0, SEEK_SET)
except that rewind clears the end-of-file and error indicators, while fseek only clears the end-of-file indicator.
| short scanf (const char *format, ...); |
Console input parsing function.
Works like sscanf, but reads the input from the keyboard using
getsn rather than from a buffer of type char *. [ENTER]
is interpreted as EOF.
The input is echoed on the screen. No newline will be output at the end of the
input, no matter whether it resulted from the user pressing [ENTER] or from a
format matching error.
The amount of possible user input is limited by available memory. scanf may also return 0 if there
was no memory left at all to allocate the temporary buffer.
| short snprintf (char *buffer, unsigned long maxlen, const char *format, ...); |
Sends formatted output, up to a given length, to a string.
snprintf sends formatted output to a string. In fact, it does the following:
accepts a series of arguments;
applies to each a format specifier contained in the format string pointed to by format;
outputs the formatted data (up to maxlen characters, including the terminating null byte) to the string pointed to by buffer;
snprintf applies the first format specifier to the first argument, the second
to the second, and so on. The format string, controls how snprintf will convert
and format its arguments. See printf for more info about
format specifiers.
snprintf returns the number of bytes output, not including the terminating null
byte in the count.
| short sprintf (char *buffer, const char *format, ...); |
Sends formatted output to a string.
sprintf sends formatted output to a string. In fact, it does the following:
accepts a series of arguments;
applies to each a format specifier contained in the format string pointed to by format;
outputs the formatted data to the string pointed to by buffer;
sprintf applies the first format specifier to the first argument, the second
to the second, and so on. The format string, controls how sprintf will convert
and format its arguments. See printf for more info about
format specifiers.
sprintf returns the number of bytes output, not including the terminating null
byte in the count.
| short sscanf (const char *buffer, const char *format, ...); |
String parsing function.
sscanf scans the string buffer for the formats in the format
string format and assigns the input to pointers passed as varargs.
Returns:
the number of pointers filled in (the number of matches done) if it is non-0
0 if no pointers were filled in because of a format matching error
EOF (-1) if the input ended before any pointers were filled in
Formats accepted:
any non-whitespace character other than '%': matches a literal character, assigns nothing
whitespace characters: match any whitespace characters, even if they are a different kind of whitespace, assign nothing
'%%': matches a literal '%', assigns nothing
Any formats of the type '%' + flags + width + type (or '%' + width + flags +
type, the order isn't actually checked, you can even put the flags in the
middle of the width):
Flags accepted:
'*': skip the matched data (don't assign it to a pointer, and don't count it)
'h': if an integer type follows, it will be a short integer, otherwise the flag is ignored. (This is the default if neither 'h' nor 'l' are specified.)
'l': if an integer type follows, it will be a long integer, otherwise the flag is ignored
Warning: "%h" or "%l" alone is not accepted. Always write "%li", "%ld", ... explicitely.
Width: Maximum number of bytes to read in for data matching. The maximum is 65535. Any larger number will be truncated modulo 65536. If the width is 0 or omitted, the default width for the format is used.
Types accepted:
'u': matches an unsigned decimal integer
default width: 65536
required pointer: 'unsigned short *' for '%hu', 'unsigned long *' for '%lu'
automatically skips leading whitespace
'd': matches a signed decimal integer (both [-] and [(-)] are accepted)
default width: 65536
required pointer: 'short *' for '%hd', 'long *' for '%ld'
automatically skips leading whitespace
'o': matches an unsigned octal integer
default width: 65536
required pointer: 'unsigned short *' for '%ho', 'unsigned long *' for '%lo'
automatically skips leading whitespace
'x' or 'X': matches an unsigned hexadecimal integer (0-9 and both a-f and A-F
are accepted)
default width: 65536
required pointer: 'unsigned short *' for '%hx', '%hX', 'unsigned long *' for '%lx', '%lX'
automatically skips leading whitespace
'p': same as '%lx' (even if '%hp' or just '%p' is specified)
'i': matches an integer in C syntax: may contain a negative sign ([-] or [(-)]),
is hexadecimal if started with 0x, octal if started with 0, and
decimal otherwise
default width: 65536
required pointer: 'short *' or 'unsigned short *' for '%hi', 'long *' or 'unsigned long *' for '%li'
automatically skips leading whitespace
'f', 'g', 'e' or 'E': matches a floating-point number. (This number will be
parsed by push_parse_text (through atof), so it has to
use the calculator '-' and 'E'.)
default and maximum width: 29. This limitation is
because we need to allocate a buffer for atof on the
stack, and we didn't want to waste too much stack space.
required pointer: 'float *'
automatically skips leading whitespace
's': matches a non-whitespace string, and null-terminates it when copying
it to the buffer (so make sure you have a buffer of size width + 1)
default width: 65536
required pointer: 'char *'
automatically skips leading whitespace
'c': matches a fixed number of characters (the given width). Does NOT
null-terminate the string when copying it to the buffer.
default width: 1 (NOT the maximum width like for the other formats)
required pointer: 'char *'
does NOT skip leading whitespace (put a space before '%c' if you want
to skip it)
'[': matches a regexp-style set of characters:
']' terminates the set unless it immediately follows the leading '[' or the leading '[^'
if '^' is the first character, matches the characters which are NOT in the set
'-' specifies a range of characters (as in '0-9') unless it immediately precedes the terminating ']'
any other characters (including ']' right at the beginning or '-' right at the end): match the corresponding literal characters
copies characters until either the input ends, or the specified width
is reached, or a character which is not in the specified set (when using
'^': which is in the specified set) is encountered
null-terminates the copied string (so make sure you have a buffer of size
width + 1)
default width: 65536
required pointer: 'char *'
does not skip leading whitespace (put a space before '%[' if you want
to skip it)
'n': does not read anything from the input, but assigns the number of
characters already read in to the given pointer
default width: N/A (the width is ignored, and no characters are read in)
required pointer: 'short *'
does not skip any whitespace in the input
| void strputchar (char c, void **ptr); |
Default vcbprintf callback function used in sprintf.
strputchar is callback function (passed to vcbprintf which is used internally for implementation of sprintf (in TIOS) and vsprintf functions. It does nothing more than
*((*(char**)ptr)++) = ch;
| char *tmpnam (char *s); |
Produces a unique random file name.
tmpnam returns a random file name of 8 characters which does not exist on
the calculator. If s is NULL,
tmpnam returns a pointer to a static buffer, otherwise it fills s and
returns a pointer to it. When passing NULL
to tmpnam, it is best to treat the pointer returned as if it were pointing to
constant data. It is assumed that the buffer pointed to by s is at
least 9 bytes long.
tmpnam is capable of returning TMP_MAX or
25^8 combinations. When nearing
TMP_MAX, performance decreases significantly,
and eventually, the function will run into an infinite loop. These factors,
however, should not pose any problems for the currently supported calculator
platforms. You will run into the maximum number of handles a lot sooner.
Note: tmpnam does not actually create any files. If you call it twice
without creating a file whose name equals the first result, it may,
in theory, return the same name again.
| short ungetc (short c, FILE *stream); |
Pushes a character back into input stream.
ungetc pushes the character c back onto the stream associated with the structure
pointed to by stream. This character will be returned on the next call to
getc (or related functions like fread) for that stream.
A second call to ungetc without a call to getc will force the previous
character to be forgotten. A call to fflush, fseek,
fsetpos, or rewind erases all memory of any
pushed-back characters. ungetc returns the character pushed back. ANSI C proposes that it
need to return EOF if the operation fails, but in this implementation it
cannot fail. It is implemented as a very simple macro.
Note: ungetc is used in some programs to push back a character to the stream associated with
the keyboard using ungetc(c, stdin). This is not possible on TI, because
terminal-associated streams are not supported. Use pushkey instead
to achieve the same effect.
| short unlink (const char *filename); |
Deletes a file.
unlink deletes the file specified by filename (it is a normal C string,
which should be in lowercase). If your file is open, be sure to close it before
removing it. The string pointed to by filename may include a folder name
too. On successful completion, unlink returns 0. On error, it returns EOF.
Note: Function SymDel from vat.h
header file is very similar like unlink (or remove), except the
parameter and returned result are somewhat different. As unlink is not a TIOS entry and
SymDel is, the usage of SymDel is
recommended instead of unlink (although SymDel is not ANSI
standard).
| void vcbprintf (vcbprintf_Callback_t callback, void **param, const char *format, va_list arglist); |
Virtual callback printing function.
vcbprintf is an auxiliary function which is the heart of all v...printf functions. arglist is a pointer to the list of arguments (see stdarg.h for more info about argument lists), and format is the format string, as usually. vcbprintf applies to each argument a format specifier contained in the format string. After this, the formatted data is sent character by character to the callback function callback passing the actual characters as the parameter c to it. Also, the parameter param of vcbprint is passed as the second parameter to the callback function. This allows for much more flexibility, because a callback function usually needs more info than a simple character to be processed. The callback function for example can push characters to a stream, so in this case param would probably be a pointer to the stream structure. More precisely,
vfprintf (stream, format, arglist);
is exactly the same as
vcbprintf ((vcbprintf_callback_t)fputc, (void**)stream, format, arglist);
See also TE_pasteText for an ununsual but powerful
example of usage of vcbprintf.
param is declared as a "double pointer" because it is often used as a pointer to a
pointer variable (in vsprintf for example), so the callback function
is able to change the content of the actual pointer variable (see strputchar).
| short vcbscanf (vcbscanf_get_Callback_t getfun, vcbscanf_unget_Callback_t ungetfun, void *param, const char *format, va_list arglist); |
Virtual callback parsing function.
vcbscanf is an auxiliary function which is the heart of all scanf family functions. arglist is a pointer to the list of arguments (see stdarg.h for more info about argument lists), and format is the format string, as usually (see sscanf). vcbscanf gets its characters using the getfun callback. If it reads a character it can't handle, it ungets it using the ungetfun callback. Also, the parameter param of vcbscanf is passed as the second parameter to the callback function. This allows for much more flexibility, because a callback function usually needs more info than a simple character to be processed. The callback function for example can get characters from to a stream, so in this case param would probably be a pointer to the stream structure. The formatted data is parsed according to the format string, as described for sscanf.
| short vfprintf (FILE *stream, const char *format, va_list arglist); |
Sends formatted output to a stream using argument list.
The vfprintf functions is known as an alternate entry point for the fprintf functions.
It behaves exactly like fprintf, but it accepts a pointer to a
list of arguments instead of an argument list (see stdarg.h
header file for more info about argument lists).
See printf for details on format specifiers.
vfprintf accepts arglist which is a pointer to a series of arguments, applies to each
argument a format specifier contained in the format string pointed to by
format, and outputs the formatted data to the stream associated with the structure
pointed to by stream. There must be the same number of format specifiers as arguments.
vfprintf returns the number of bytes output. In the event of error, vfprintf
returns EOF.
| short vfscanf (FILE *file, const char *format, va_list arglist); |
File parsing function using argument list.
The vfscanf function is known as an alternate entry point for the fscanf function. It behaves exactly like fscanf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See sscanf for details on format specifiers.
| void vprintf (const char *format, va_list arglist); |
Sends formatted output to the screen using argument list.
The vprintf functions is known as an alternate entry point for the
printf function. It behaves exactly like printf,
but it accepts a pointer to a list of arguments instead of an argument
list (see stdarg.h header file for more info about argument lists).
See printf for details on format specifiers.
vprintf accepts arglist, which is a pointer to a series of arguments, applies to
each a format specifier contained in the format string pointed to by format, and
outputs the formatted data to the screen. There must be the same number of format
specifiers as arguments.
Note: In ANSI C, function vprintf is an int function, and it returns the number of printed
characters. Due to some practical reasons, this implementation of vprintf is a void function.
This difference is usually not important.
| short vscanf (const char *format, va_list arglist); |
Console input parsing function using argument list.
The vfscanf function is known as an alternate entry point for the fscanf function. It behaves exactly like scanf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See sscanf for details on format specifiers.
| short vsnprintf (char *buffer, unsigned long maxlen, const char *format, va_list arglist); |
Sends formatted output, up to a given length, to a string, using argument list.
The vsprintf function is known as an alternate entry point for the
snprintf function. It behaves exactly like snprintf,
but it accepts a pointer to a list of arguments instead of an argument
list (see stdarg.h header file for more info about argument lists).
See printf for details on format specifiers.
vsprintf accepts arglist, which is a pointer to a series of arguments, applies to
each a format specifier contained in the format string pointed to by format, and
outputs the formatted data (up to maxlen characters) to the string pointed to by buffer.
There must be the same number of format specifiers as arguments.
See also: vsprintf
| short vsprintf (char *buffer, const char *format, va_list arglist); |
Sends formatted output to a string using argument list.
The vsprintf function is known as an alternate entry point for the
sprintf function. It behaves exactly like sprintf,
but it accepts a pointer to a list of arguments instead of an argument
list (see stdarg.h header file for more info about argument lists).
See printf for details on format specifiers.
vsprintf accepts arglist, which is a pointer to a series of arguments, applies to
each a format specifier contained in the format string pointed to by format, and
outputs the formatted data to the string pointed to by buffer. There must be the same
number of format specifiers as arguments.
Note: In ANSI C, function vsprintf is an int function, and it returns the number of characters
stored in buffer. Due to some practical reasons, this implementation of vsprintf is
a void function. This difference is usually not important.
See also: vsnprintf
| short vsscanf (const char *buffer, const char *format, va_list arglist); |
String parsing function using argument list.
The vsscanf function is known as an alternate entry point for the sscanf function. It behaves exactly like sscanf, but it accepts a pointer to a list of arguments instead of an argument list (see stdarg.h header file for more info about argument lists). See sscanf for details on format specifiers.
| #define EOF (-1) |
Indicates that the end of a file has been reached.
EOF is a constant which is usually returned as the result of file handling functions if an end-of-file is reached, or in a case of an error. The ANSI standard does not propose exact value of this constant, but it proposes that it must be negative.
| #define TMP_MAX 152587890625 |
Contains the maximum number of temporary file names.
TMP_MAX describes the maximum number of temporary file names the
tmpnam function can return. This limit equals
25^8, i.e. the number of possibilities if you have 25 possible
values for all 8 characters. You can never run into this limit; see
tmpnam for more info.
typedef struct {
|
A structure describing an opened file.
FILE is the main file control structure for streams. The exact structure of it is very platform-dependent, so ANSI C proposes that the exact structure of this structured type should not be known, and well-written programs do not need to access the internal fields of this structure.
| enum FileFlags {_F_READ = 0x0001, _F_WRIT = 0x0002, _F_RDWR = 0x0003, _F_ERR = 0x0010, _F_EOF = 0x0020, _F_BIN = 0x0040}; |
An enumeration describing internal flags for file handling.
These flags describes whether the file is opened in read or write mode, whether an end-of-file or a serious error occured, and whether the file is open in binary or text mode.
See also: FILE
| typedef unsigned long fpos_t; |
A type describing the current position in a file.
fpos_t is a scalar type used for saving the current file position using fgetpos and restoring it back using fsetpos.
| enum SeekModes {SEEK_SET, SEEK_CUR, SEEK_END}; |
An enumeration for describing possible modes used in fseek.
| typedef CALLBACK void (*vcbprintf_Callback_t) (char c, void **param); |
Describes a callback function for vcbprintf.
| typedef CALLBACK short (*vcbscanf_get_Callback_t) (void *param); |
Describes the first callback function for vcbscanf.
| typedef CALLBACK short (*vcbscanf_unget_Callback_t) (void *param); |
Describes the second callback function for vcbscanf.