The <stdio.h> header file
This header file contains the following functions:
clearerr clrscr fclose feof
ferror fflush fgetc fgetchar
fgetpos fgets fopen fprintf
fputc fputchar fputs fread
freopen fseek fsetpos ftell
fwrite getc getchar gets
printf printf_xy putc putchar
puts remove rename rewind
sprintf strerror strputchar ungetc
unlink vcbprintf vfprintf vprintf
vsprintf
and the following constants and predefined types:
EOF FILE FileFlags fpos_t
NULL SeekModes size_t va_list
NOTE: This implementation of stdio.h is 90% compatible with ANSI standard.
I tried to make all functions to be as close to ANSI as possible, without introducing too big
overload of the generated code. The main differences are in the fact that sscanf function (and functions
derived from it) is not yet implemented (if anybody knows a good and compact implementation for
it, please mail to me), and there is no terminal-associated file streams
like stdin and stdout which may be redirected (by the way,
I don't see big needness for them). However, functions from this header file are mostly not
TIOS functions - they are completely written by me, so they are not
embedded in the TIOS. That's why usage of them may cause that your program will be larger than
if you don't use functions from this header file (typical increase of the size is
300-2000 bytes, depending of which functions and how many
different functions from this header file are used in the program). Also, this header file is
not so good for "distributed" programs (i.e. programs which are spreaded in more modules which
are linked separately). If your program is spreaded in more than one object file, avoid usage
of the same function in more than one module (else it will be doubled in the final code). So,
although functions from this header file are much more "standard" than TIOS-specific functions,
it is better to avoid functions like fopen etc, especially in "multi-module"
programs. Instead, use "non-standard" functions from vat.h header file.
Of course, functions from this header file may be very useful for porting program from a
"standard" computer to the TI. But, I will repeat again: it is better to avoid them.
Functions
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 ClrScr
remains the current print/plot position 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.
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 can not 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.
Function version of putchar.
fputchar is usually equal to putchar, except fputchar is implemented as
a function, but putchar is implemented as a macro.
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.
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) |
| | Centre 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 |
o | Octal integer (this option is non-ANSI, i.e. TI specific) |
b | Binary integer (this option is non-ANSI, i.e. TI specific) |
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 (0xhhhhhhhh); principally the same as '#.8x' |
% | None: the character '%' is printed instead |
Here is a short demonstration of usage:
LCD_BUFFER buffer;
int i, j;
LCD_save (buffer);
for (j = F_4x6; j <= F_8x10; j++)
{
clrscr ();
FontSetSys (j);
for (i = 1; i <= 1000; i++) printf ("%d ", i);
ngetchx ();
}
LCD_restore (buffer);
NOTE: In ANSI C, function 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.
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.
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 vprintf (const char *format, va_list arglist);
Sends formatted output to the screen using argument list.
The vprintf functions is known as 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 vsprintf (char *buffer, const char *format, va_list arglist);
Sends formatted output to a string using argument list.
The vsprintf functions is known as alternate entry point for the
printf 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.
Gets a character from the keyboard (with echoing to the screen).
fgetchar returns the character read from the keyboard. It is similar like
ngetchx except getchar echoes the character read on
the screen. '\r' character (i.e. ENTER key) will be echoed as a "new line".
NOTE: In ANSI C, getchar(c)
is equal as getc(c, stdin)
, so it can be redirected
using freopen. This is not possible here, because stdin
is not implemented as a file stream.
Function version of fgetchar.
fgetc is usually equal to getchar, except fgetchar is implemented as
a function, but getchar is implemented as a macro. In this implementation,
there is no difference between these two variants (both of them are macros).
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). 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.
NOTE: Although gets may be used to enter a data in the user program, this is the worst way to
enter something from the keyboard: gets does not allow any editing facitilities (even backspace
key will not work). Such behaviour does not disagree with ANSI standard (editing is not proposed
in the standard). gets may be useful while the program is in a testing state. It is recommended
in any serious program to make a custom keyboard input routine. For example, I usually used the
following routine, which is good enough for many purposes:
void InputStr (char *buffer, short maxlen)
{
SCR_STATE ss;
short key, i = 0;
buffer[0] = 0;
SaveScrState (&ss);
do
{
MoveTo (ss.CurX, ss.CurY);
printf ("%s_ ", buffer);
// Two spaces are required if F_4x6 font is used
key = ngetchx ();
if (key >= ' ' && key <= '~' && i < maxlen) buffer[i++] = key;
if (key == KEY_BACKSPACE && i) i--;
buffer[i] = 0;
} while (key != KEY_ENTER);
}
See also Frequently Asked Questions list for a more advanced version
of this routine. Especially, if very good editing facitilities are required, the best idea
is to use routines from textedit.h header file.
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. |
On successful completion, fopen returns a pointer to the newly opened
stream. In the event of error, it returns NULL. Note that files on TI are
in fact TIOS variables, so their maximal size is limited (as the size of the variable is limited).
Maybe in the future I will try to implement files which are limited only by the amount of the
free memory.
To specify that a given file is being opened or created in text mode, append
a 't' to the mode string ("rt", "w+t", and so on). Similarly, to specify binary mode,
append a 'b' to the mode string ("wb", "a+b", and so on). What "text" or "binary" exactly
means will be explained a bit later. fopen also allows the t or b to be inserted between the
letter and the '+' character in the mode string. For example, "rt+" is equivalent to "r+t".
If a 't' or 'b' is not given in the mode string, 't' is assumed (this slightly differs from
the ANSI convention: in ANSI C the mode in this case is governed by the global variable
_fmode, which is not implemented here).
When a file is opened in "text" mode, it is assumed to be a TEXT variable. On creating, all
necessary headers and tags for the TEXT variable will be created. On opening for reading,
the file pointer will be set to the first character in the first text line (asuming that it
IS a text variable). So, files created in "text" mode can be readed in the TI text editor,
and you can read variables created in the text editor. All '\n' characters will be translated
to '\r' 0x20 sequence during writting (to satisfy the format of the text in TEXT variables),
and a character after '\r' will be swallowed during reading (to skip over the "command byte" at the
begining of the each line). Here is an example:
FILE *f;
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;
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 accepts 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 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.
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 getc (FILE *stream);
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.
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 putc (short c, FILE *stream);
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.
short fputc (short c, FILE *stream);
Function version of fputc.
fputc is usually equal to getc, except fputc is implemented as
a function, but putc is implemented as a macro.
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 getc 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.
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 command 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.
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: fread command 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.
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 vfprintf (FILE *stream, const char *format, va_list arglist);
Sends formatted output to a stream using argument list.
The vfprintf functions is known as 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 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.
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.
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.
long ftell (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.
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 |
fseek discards any character pushed back using ungetc.
fseek returns 0 if the pointer is successfully moved. It returns a nonzero
on failure.
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.
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.
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 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 TI file system is not buffered (of course), fflush has
no any effect, except undoing the effect of ungetc function. fflush
returns 0 on success (which is always the case on the TI).
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).
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.
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).
Gives an error message string.
strerror returns a pointer to string which contains text of the system error message
err_no. Note that this is not a TI-Basic error message, but a low level
error message. Here is a complete table of such messages:
0 | no error |
1 | no such file entry |
2 | I/O error |
3 | not a serial device |
4 | out of memory |
5 | permission denied |
6 | block device required |
7 | no such device |
8 | invalid argument |
9 | file table is full |
10 | device directory is full |
11 | no space left on device |
12 | no more allocation blocks |
13 | no more data blocks on device |
14 | file is open |
15 | no RAM space configured |
16 | no heap space configured |
17 | seek can't extend read only file |
18 | bad file descriptor - file not open |
19 | invalid signal number |
20 | argument out of range |
21 | result out of range |
Other values of err_no will generate "undefined errno value" message.
NOTE: Previous releases of TIGCCLIB prior to 2.0 reports wrongly that err_no
is a TI-Basic error code, which is not true. To get a pointer to TI-Basic error
message, use find_error_message function.
Virtual callback printing function.
vcbprintf is an auxilary function which is the heart of all v...printf functions.
arglist is the pointer to the list of arguments (see stdarg.h
header file for more info about argument lists), and format is the format string, as
usual. vcbprintf applies to each argument a format specifier contained in the format string.
After this, the formatted data is send character by character to the callback function
callback passing the actual characters as the parameter c to it. Also, parameter
param of vcbprint is passed as the second parameter to the callback function. This
allows much more flexibility, because callback function usually needs more info than a simple
character to be processed. 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 precise,
vfprintf (stream, format, arglist);
is exactly the same as
vcbprintf ((void(*)(char, void**))fputc, (void**)stream, format, arglist);
See also TE_pasteText for an ununsual but powerful
example of usage of vcbprintf.
param is declared as "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 strputchr).
Default vcbprintf callback function used in sprintf.
strputchr 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;
Constants and predefined types
FileFlags is enumerated type for describing various flags used internally for file handling
(see FILE). These flags describes whether the file is opened in read
or write mode, whether an end-of-file or serious error occured, and whether the file is open
in binary or text mode. FileFlags is defined as
enum FileFlags {_F_READ = 0x0001, _F_WRIT = 0x0002, _F_RDWR = 0x0003,
_F_ERR = 0x0010, _F_EOF = 0x0020, _F_BIN = 0x0040};
SeekModes is enumerated type for describing possible modes used in fseek
function. It is defined as
enum SeekModes {SEEK_SET, SEEK_CUR, SEEK_END};
NULL is a null-pointer value, defined as (void *) 0.
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. ANSI standard does not propose exact value
of this constant, but it proposes that it must be negative. It is defined here as
-1, like in many other implementations.
fpos_t is a scalar type used for saving current file position using fgetpos
and restoring it back using fsetpos. In this implementation, fpos_t is
an unsigned long integer.
size_t is a type proposed in ANSI C for defining size of strings and
memory blocks. It is defined here as
typedef unsigned long size_t;
va_list is the type of the void pointer passed to one of the functions that accepts a
pointer to a list of arguments. See stdarg.h header file
for more info. va_list is implemented here as:
typedef void *va_list;
FILE is the main file control structure for streams. Exact structure of it is very
platform-dependent, so ANSI C proposes that exact structure of this structured type should not
be known, and well-written programs need not to access to internal fields of this structure.
Anyway, it is implemented here as:
typedef struct
{
char *fpos; // Current position of file pointer (absolute address)
void *base; // Pointer to the base of the file
unsigned short handle; // File handle
short flags; // Flags (see FileFlags)
short unget; // 1-byte buffer for ungetc (b15=1 if non-empty)
unsigned long alloc; // Number of currently allocated bytes for the file
} FILE;