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 (e.g. 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

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

int putchar (int c);

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.

int fputchar (int 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.

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.

void printf (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 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 (e.g. 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, e.g. TI specific)
space	Insert space before positive values
#	(prefix hex values (>0) with '0x') [does not appear to work] force '.' in float output (and prevent trunctation of trailing zeros)
^	TI-Float format: special character for the exponent, no '+' prefix in the exponent, 0. instead of 0 (this option is non-ANSI, e.g. TI specific)
\|	Centre the output in the field (this option is non-ANSI, e.g. 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, e.g. 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, e.g. TI specific)
R	Like 'r' but with uppercase letter for the exponent
y	Floating point, mode specified float format (this option is non-ANSI, e.g. TI specific)
Y	Like 'y' but with uppercase letter for the exponent
c	Character
s	String
p	Pointer; principally the same as 'x'
%	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.

int 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 format;
outputs the formatted data to the string pointed 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.

void printf_xy (int x, int y, 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 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 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.

int 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 by format, and outputs the formatted data to the string pointed 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.

int getchar (void);

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 (e.g. 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.

int fgetchar(void);

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).

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 (e.g. 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. 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", "r");
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", "rb");
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 by filename may also contain a path (e.g. 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, e.g. 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.

int fclose (FILE *stream);

Closes a stream.

fclose closes the stream associated to the structure pointed by stream. In this implementation, fclose unlocks the file (which is locked during it is opened), and frees the file descriptor structure pointed by stream. fflush 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 a lvalue, e.g, 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.

int getc (FILE *stream);

Gets a character from a stream.

getc gets the next character on the given input stream (associated with the structure pointed 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.

int 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.

int putc (int 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.

int fputc (int 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, int n, FILE *stream);

Gets a string from a stream.

fgets reads characters from stream associated to the structure pointed 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 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.

int 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 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 int fread (void ptr, unsigned int size, unsigned int 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 by stream into a block pointed to 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.

unsigned int fwrite (const void ptr, unsigned int size, unsigned int 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 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.

int 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 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.

int 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 by format, and outputs the formatted data to the stream associated with the structure pointed 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.

int 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 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.

int 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 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 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.

int ungetc (int c, FILE *stream);

Pushes a character back into input stream.

ungetc pushes the character c back onto the stream associated with the structure pointed 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 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.

int fseek (FILE *stream, long offset, int 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.

int 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 by stream in the location pointed 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.

int 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 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.

int fflush (FILE *stream);

Flushes a stream.

fflush is proposed to writes the output for stream to the associated file if the given stream has buffered output. As TI filing 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).

int 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).

int remove (const char *filename);

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.

int 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 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).

char *strerror (int err_no);

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.

void vcbprintf (void callback (char c, void param), void param, char *format, va_list arglist);

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 the 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);

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).

void strputchr (char c, char **ptr);

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

*((*ptr)++) = ch;

Constants and predefined types

enum FileFlags

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};

enum SeekModes

SeekModes is enumerated type for describing possible modes used in fseek function. It is defined as

enum SeekModes {SEEK_SET, SEEK_CUR, SEEK_END};

const NULL

NULL is a null-pointer value, defined as (void *) 0.

const EOF

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.

type fpos_t

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.

type size_t

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;

type va_list

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;

type FILE

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 the file pointer (absolute address)
void *base;	// Pointer to the base of the file
unsigned int handle;	// File handle
int flags;	// Flags (see FileFlags)
int unget;	// One-byte buffer for ungetc (b15=1 if there is a byte in it)
int alloc;	// Number of currently allocated bytes for the file variable
} FILE;