The <stdio.h> Header File

ANSI-compatible file and TTY input/output routines

Functions

cbprintf
Callback printing function.
cbscanf
Callback parsing function.
clearerr
Resets error indication.
clrscr
Clears the screen and resets the print position.
fclose
Closes a stream.
feof
Tests a stream for an end-of-file indicator.
ferror
Tests a stream for a read or write error.
fflush
Flushes a stream.
fgetc
Function version of fgetc.
fgetchar
Function version of getchar.
fgetpos
Gets the current file pointer position.
fgets
Gets a string from a stream.
fopen
Opens a stream.
fprintf
Sends formatted output to a stream.
fputc
Function version of fputc.
fputchar
Function version of putchar.
fputs
Outputs a string to a stream.
fread
Reads data from a stream.
freopen
Associates a new file with an open stream.
fscanf
File parsing function.
fseek
Repositions the file pointer of a stream.
fsetbufsize
Sets the buffer size of a file.
fsetpos
Positions the file pointer of a stream.
ftell
Returns the current file pointer.
fwrite
Writes data to a stream.
getc
Gets a character from a stream.
getchar
Gets a character from the keyboard (with echoing to the screen).
gets
Gets a string from the keyboard.
getsn
Gets a string from the keyboard avoiding buffer overflows.
printf_xy
Sends formatted output to the fixed place on the screen.
printf
Sends formatted output to the screen.
putc
Writes a character to a stream.
putchar
Outputs a character to the screen in TTY mode.
puts
Outputs a string to the screen in TTY mode.
remove
Macro that removes a file.
rename
Renames a file.
rewind
Repositions file pointer to stream's beginning.
scanf
Console input parsing function.
sprintf
Sends formatted output to a string.
sscanf
String parsing function.
strerror
Gives an error message string.
strputchar
Default vcbprintf callback function used in sprintf.
tmpnam
Produces a unique random file name.
ungetc
Pushes a character back into input stream.
unlink
Deletes a file.
vcbprintf
Virtual callback printing function.
vcbscanf
Virtual callback parsing function.
vfprintf
Sends formatted output to a stream using argument list.
vfscanf
File parsing function using argument list.
vprintf
Sends formatted output to the screen using argument list.
vscanf
Console input parsing function using argument list.
vsprintf
Sends formatted output to a string using argument list.
vsscanf
String parsing function using argument list.

Constants

EOF
Indicates that the end of a file has been reached.
NULL
A null-pointer value.
TMP_MAX
Contains the maximum number of temporary file names.

Predefined Types

FILE
A structure describing an opened file.
FileFlags
An enumeration describing internal flags for file handling.
fpos_t
A type describing the current position in a file.
SeekModes
An enumeration for describing possible modes used in fseek.
size_t
A type to define sizes of strings and memory blocks.
va_list
A void pointer which can be interpreted as an argument list.
vcbprintf_Callback_t
Describes a callback function for vcbprintf.
vcbscanf_get_Callback_t
Describes the first callback function for vcbscanf.
vcbscanf_unget_Callback_t
Describes the second callback function for vcbscanf.

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.


cbprintf

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.


cbscanf

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.


clearerr

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.


clrscr

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.


fclose

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.


feof

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.


ferror

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.


fflush

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


fgetc

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.


fgetchar

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.


fgetpos

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.


fgets

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.


fopen

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:

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


fprintf

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:

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.


fputc

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.


fputchar

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.


fputs

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.


fread

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.


freopen

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.


fscanf

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


fseek

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

whenceFile location
SEEK_SETFile beginning
SEEK_CURCurrent file pointer position
SEEK_ENDEnd-of-file

fseek discards any character pushed back using ungetc. fseek returns 0 if the pointer is successfully moved. It returns a nonzero value on failure.


fsetbufsize

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.


fsetpos

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.


ftell

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.


fwrite

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.


getc

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


getchar

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


gets

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


getsn

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


printf_xy

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:

printf_xy is a GNU C macro which calls sprintf and DrawStr.


printf

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:

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

FlagsMeaning
noneRight align (pad spaces or zeros to left)
-Left align (pad spaces to right)
+Always force sign (include prefix '+' before positive values)
zDon't postfix padding (this option is non-ANSI, i.e. TI specific)
spaceInsert 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)


WidthMeaning
numPrint 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)


PrecisionMeaning
noneDefault precision
numnum is number of chars, decimal places, or number of significant digits (num<=16) to display depending on type (see below)
-1Default = 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
hForce short integer
lForce long integer


TypeMeaning
d, iSigned decimal integer
uUnsigned decimal integer
xLowercase hexadecimal integer
XUppercase hexadecimal integer
eFloating point, format [-]d.dddde[sign]ddd (exponential format)
ELike 'e' but with uppercase letter for the exponent
fFloating point, format [-]dddd.dddd
gFloating point: most compact float format available ('e' or 'f'); this is the most common option, used for most dialog floats
GLike 'g' but with uppercase letter for the exponent
rFloating point, engineering form (this option is non-ANSI, i.e. TI specific)
RLike 'r' but with uppercase letter for the exponent
yFloating point, mode specified float format (this option is non-ANSI, i.e. TI specific)
YLike 'y' but with uppercase letter for the exponent
cCharacter
sString
pPointer; principally the same as 'x' - do not use without 'l' modifier
%None; the character '%' is printed instead

Here is a short demonstration of usage:

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.


putc

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


putchar

#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:

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.


puts

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.


remove

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


rename

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


rewind

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.


scanf

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.


sprintf

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:

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.


sscanf

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:

Formats accepted:

Types accepted:


strputchar

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;

tmpnam

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.


ungetc

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.


unlink

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


vcbprintf

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


vcbscanf

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.


vfprintf

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.


vfscanf

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.


vprintf

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.


vscanf

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.


vsprintf

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


vsscanf

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.


EOF

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


TMP_MAX

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


FILE

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 */
unsigned short buffincrement; /* Number of bytes allocated at once */
} FILE;

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.


FileFlags

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


fpos_t

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.


SeekModes

enum SeekModes {SEEK_SET, SEEK_CUR, SEEK_END};

An enumeration for describing possible modes used in fseek.


vcbprintf_Callback_t

typedef CALLBACK void (*vcbprintf_Callback_t) (char c, void **param);

Describes a callback function for vcbprintf.


vcbscanf_get_Callback_t

typedef CALLBACK short (*vcbscanf_get_Callback_t) (void *param);

Describes the first callback function for vcbscanf.


vcbscanf_unget_Callback_t

typedef CALLBACK short (*vcbscanf_unget_Callback_t) (void *param);

Describes the second callback function for vcbscanf.


Return to the main index