Data Structures | |
| struct | l_file_t |
| File representation. More... | |
Enumerations | |
| enum | libl_errcodes { L_OK = 0, L_ERR_MEM = 1, L_ERR_FILE_NOT_FOUND = 2, L_ERR_CREATION_FAILED = 3 } |
| Possible return codes. More... | |
Functions | |
| l_file_p | lopen (const char *name, char *ok) |
| Opens an existing file. | |
| l_file_p | lcreate (const char *name, unsigned short size, char *ok) |
| Creates a new file and pre-allocates size bytes for it. | |
| void | lclose (l_file_p file) |
| Closes a file. | |
| char | lpreserve (l_file_p file, unsigned short n) |
| Preserves n additional bytes for the file. | |
| unsigned short | lread (void *buffer, unsigned short n, l_file_p file) |
| Reads n bytes from file into buffer. | |
| char | lgetc (l_file_p file) |
| Reads a character from file. | |
| char * | lgets (char *s, unsigned short n, l_file_p file) |
| Reads a string from file. | |
| unsigned short | lwrite (void *buffer, unsigned short n, l_file_p file) |
| Writes n bytes from buffer to file. | |
| char | lputc (char c, l_file_p file) |
| Writes a character to file. | |
| char | lputs (const char *s, l_file_p file) |
| Writes a string to file. | |
| unsigned short | ltell (l_file_p file) |
| Returns the position of the data pointer in the file. | |
| void | lrewind (l_file_p file) |
| Sets the data pointer to the first byte. | |
| void | lseek (l_file_p file, long n) |
| Moves the file pointer n bytes. | |
| enum libl_errcodes |
| l_file_p lopen | ( | const char * | name, | |
| char * | ok | |||
| ) |
Opens an existing file.
lopen is used to open a file that already exists on the calculator. Note that 'name' must not be a SYMSTR, it is interpreted as a normal character string.
In case of an error, the function simply returns NULL. The reason for the error will be stored in the variable referenced by 'ok'.
The following piece of code tries to open the file "sample":
l_file_p f; char ok; if ((f = lopen("sample", &ok)) == NULL) { printf("ERROR: Unable to open 'sample': "); switch (ok) { case L_ERR_MEM: printf("Out of memory"); break; case L_ERR_FILE_NOT_FOUND: printf("File not found"); break; default: break; } putc('\n'); }
| name | The name of the file | |
| ok | One of the error codes will be stored here |
NULL in case of an error | l_file_p lcreate | ( | const char * | name, | |
| unsigned short | size, | |||
| char * | ok | |||
| ) |
Creates a new file and pre-allocates size bytes for it.
Use lcreate to create a new file with size bytes of pre-allocated space. Like lopen, lcreate takes a plain C string.
In case of an error, the function simply returns NULL. The reason for the error will be stored in the variable referenced by 'ok'.
The following piece of code tries to create the file "sample" with 200 bytes of pre-allocated space:
l_file_p f; char ok; if ((f = lcreate("sample", 200, &ok)) == NULL) { printf("ERROR: Unable to create the file 'sample': "); switch (ok) { case L_ERR_MEM: printf("Out of memory"); break; case L_ERR_FILE_NOT_FOUND: printf("File not found"); break; case L_ERR_CREATION_FAILED: printf("Adding the file failed"); break; default: break; } putc('\n'); }
| name | The name of the file | |
| size | The number of bytes to be pre-allocated | |
| ok | One of the error codes will be stored here |
NULL in case of an error | void lclose | ( | l_file_p | file | ) |
Closes a file.
Closes the file pointed to by file and re-allocates its space to the number of bytes (file->size) written to the file.
| file | The file to be closed |
| char lpreserve | ( | l_file_p | file, | |
| unsigned short | n | |||
| ) |
Preserves n additional bytes for the file.
With lpreserve, you can manually preserve space in the file for data. Internally, it simply uses HeapRealloc. Note that if you write a block of data at once, preallocating might not be needed. Maybe I should mention that if you create a file with 100 pre-allocated bytes and call lpreserve with 200 on it, the resulting number of pre- allocated bytes is 300, not 200.
If you use libl functions to write data to a file, you do not need to explicitely call this function, since those functions preserve the required memory themselves. It might be useful for gaining some speed and preserve space for a couple of operations, though.
You can get information about the number of currently pre-allocated bytes via the file structure.
| file | The file for which space should be preserved | |
| n | The number of bytes to be preserver |
| unsigned short lread | ( | void * | buffer, | |
| unsigned short | n, | |||
| l_file_p | file | |||
| ) |
Reads n bytes from file into buffer.
lread basically works like fread. It reads n bytes from file, starting from the current file pointer position (which can be retrieved via ltell) and stores them into buffer. Please note that the function does not know about the size of a block (like fread). Like fread, the file pointer is moved forward by the number of read bytes.
Internally, memcpy is used to copy the data from the file to the buffer.
| buffer | A pointer to where the data can be stored | |
| n | The number of bytes to read | |
| file | An opened file from which data should be read |
| char lgetc | ( | l_file_p | file | ) |
Reads a character from file.
Gets the next character from a file and moves the file pointer
| file | The file that should be read from |
| char* lgets | ( | char * | s, | |
| unsigned short | n, | |||
| l_file_p | file | |||
| ) |
Reads a string from file.
lgets works like lgetc, but it keeps reading characters until either a NULL character is read or n characters have be read, so it is suitable to read a string from a file (which is NULL - terminated)
| s | A pointer to where the string can be stored | |
| n | Maximum number of characters to be read | |
| file | The file that should be read from |
NULL in case of an Error | unsigned short lwrite | ( | void * | buffer, | |
| unsigned short | n, | |||
| l_file_p | file | |||
| ) |
Writes n bytes from buffer to file.
lwrite works like fwrite: Data is written to a file and the file pointer is moved forward. lwrite also checks for pre-allocated space and enlarges it if neccessarry. Note that this function does not know about the block size of the data; it uses memcpy to copy the data
| buffer | A pointer to be read from | |
| n | The number of bytes to be written | |
| file | The file to be written to |
| char lputc | ( | char | c, | |
| l_file_p | file | |||
| ) |
Writes a character to file.
This function is provided for convenience if you want to write a single character to a file. It uses lwrite to actually write the character.
| c | The character to be written | |
| file | The file to be written to |
EOF in case of an error | char lputs | ( | const char * | s, | |
| l_file_p | file | |||
| ) |
Writes a string to file.
This function is provided for convenience if you want to write a NULL - terminated string to a file. It uses lwrite to actually write strlen(s) bytes of the s.
| s | The string to be written | |
| file | The file to be written to |
EOF in case of an error | unsigned short ltell | ( | l_file_p | file | ) | [inline] |
Returns the position of the data pointer in the file.
Like ftell, this function returns the current position of the file data pointer. It uses data_ptr and base_ptr of file to get the correct position, i.e:
return (file->data_ptr - 2) - file->base_ptr;
| file | The file for which the position is needed |
| void lrewind | ( | l_file_p | file | ) | [inline] |
Sets the data pointer to the first byte.
Works like rewind, i.e. resets the file data pointer to the beginning of accessible file data.
| file | The file that is about to be rewinded |
| void lseek | ( | l_file_p | file, | |
| long | n | |||
| ) | [inline] |
Moves the file pointer n bytes.
Works like fseek, except there are no constants like SEEK_END that can be specified. It moves the file data pointer by n bytes, if possible. A negative n results in a seek towards the beginning.
| file | The file to be seeked | |
| n | The number of bytes to be seeked |
1.5.1