File API

[Shaltif]

[FILE API]
The file API allows a programmer to read, write and append files (both in text and binary mode) on a computer's storage drive.

[FUNCTION SUMMARY]
creation functions

SILL_ERROR error = sill_file_open(SILL_RESOURCE *result, SILL_CHAR *filename, SILL_UINT mode);
SILL_ERROR error = sill_file_close(SILL_RESOURCE file);
SILL_ERROR error = sill_file_eof(SILL_UINT *result, SILL_RESOURCE file);
SILL_UINT exists = sill_file_exists(SILL_RESOURCE file);

manipulation functions

SILL_ERROR error = sill_file_delete(SILL_CHAR *filename);
SILL_ERROR error = sill_file_rename(SILL_CHAR *filename, SILL_CHAR *newname);
SILL_ERROR error = sill_file_copy(SILL_CHAR *src_filename, SILL_CHAR *dst_filename);

string functions

SILL_ERROR error = sill_file_string_write(SILL_RESOURCE file, SILL_CHAR *string);
SILL_ERROR error = sill_file_string_writeln(SILL_RESOURCE file);
SILL_ERROR error = sill_file_string_read(SILL_CHAR *string, SILL_UINT size, SILL_RESOURCE file);

binary functions

SILL_ERROR error = sill_file_bin_write(SILL_RESOURCE file, SILL_CHAR byte);
SILL_ERROR error = sill_file_bin_write_buffer(SILL_RESOURCE file, SILL_CHAR *bytes, SILL_UINT size);
SILL_ERROR error = sill_file_bin_read(SILL_CHAR *byte, SILL_RESOURCE file);
SILL_ERROR error = sill_file_bin_read_buffer(SILL_CHAR *bytes, SILL_UINT size, SILL_RESOURCE file);
SILL_ERROR error = sill_file_bin_set_size(SILL_RESOURCE file, SILL_UINT size);
SILL_ERROR error = sill_file_bin_get_size(SILL_UINT *size, SILL_RESOURCE file);
SILL_ERROR error = sill_file_bin_set_position(SILL_RESOURCE file, SILL_UINT position, SILL_UINT from);
SILL_ERROR error = sill_file_bin_get_position(SILL_UINT *size, SILL_RESOURCE file);

filename functions

SILL_ERROR error = sill_filename_name(SILL_CHAR *name, SILL_UINT size, SILL_CHAR *filename);
SILL_ERROR error = sill_filename_dir(SILL_CHAR *directory, SILL_UINT size, SILL_CHAR *filename);
SILL_ERROR error = sill_filename_drive(SILL_CHAR *drive, SILL_UINT size, SILL_CHAR *filename);
SILL_ERROR error = sill_filename_ext(SILL_CHAR *extension, SILL_UINT size, SILL_CHAR *filename);
SILL_UINT exists = sill_filename_exists(SILL_CHAR *filename);

[Shaltif]

[CREATION FUNCTIONS]

sill_file_open

SILL_ERROR error = sill_file_open(SILL_RESOURCE *result, SILL_CHAR *filename, SILL_UINT mode);
[out] result - A file resource handle which is used for reading/writing.
[in] filename - A complete path and filename to a file on the computer's file system.
[in] mode - Additional flag settings on how to open the given file.
[return] error - Error result.

Opens a file for use in the file API.  Files can be opened for reading, writing or appending (or a combination of) in either text or binary mode.  A list of supported modes can be found here.  Multiple modes can be or'd together (for example, you can open a file for reading and writing by doing:  SILL_FILE_READ|SILL_FILE_WRITE ).  The SILL_FILE_BINARY mode will automatically open the file for both reading and writing if no other flags are specified with it.

Example:

Code:

SILL_RESOURCE file;

sill_file_open(&file,"c:\my_file.dat",SILL_FILE_READ|SILL_FILE_BINARY);

/* opens my_file.dat for only reading in binary mode */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_PARAMETER - An invalid mode was specified.
SILL_ERROR_FILE - The given filename can't be opened or found.
SILL_ERROR_MEMORY - Unable to allocate required memory for the file resource.

sill_file_close

SILL_ERROR error = sill_file_close(SILL_RESOURCE file);
[in] file - A file resource handle to close.
[return] error - Error result.

Closes and destroys a file resource handle that was previously opened.

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource handle was invalid.

sill_file_eof

SILL_ERROR error = sill_file_eof(SILL_UINT *result, SILL_RESOURCE file);
[out] result - Whether the file reached the end (1) or not (0).
[in] file - A file resource handle which is used for reading/writing.
[return] error - Error result.

Checks whether the file has reached the end (1) or not (0).

Example:

Code:

SILL_RESOURCE file;

sill_file_open(&file,"c:\my_file.dat",SILL_FILE_READ|SILL_FILE_BINARY);

SILL_UINT eof = 0;

while (!eof) {
   /*read from file code goes here*/
   sill_file_eof(&eof,file);
}

sill_file_close(file);

/* opens my_file.dat for only reading, closing once we reach the end */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource handle doesn't exist or is invalid.

sill_file_exists

SILL_UINT exists = sill_file_exists(SILL_RESOURCE file);
[in] file - A file resource handle to check.
[return] exists - Whether the resource handle exists (1) or not (0).

Returns whether the specified file resource currently exists (1) or not (0).  This should not be confused with sill_filename_exists(), as only that function checks if a file actually exists on the storage device.

[Shaltif]

[MANIPULATION FUNCTIONS]

sill_file_delete

SILL_ERROR error = sill_file_delete(SILL_CHAR *filename);
[in] filename - file to delete from the storage device.
[return] error - Error result.

Deletes the physical file from the storage device.

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_FILE - The given filename can't be found or doesn't exist.

sill_file_rename

SILL_ERROR error = sill_file_rename(SILL_CHAR *filename, SILL_CHAR *newname);
[in] filename - File to rename.
[in] newname - The new filename to use.
[return] error - Error result.

Renames a physical file on the storage device to the specified newname.  If the directory is different then the original (as in, instead of changing the actual file name, you change the directory it is contained in) the file will be moved to the new destination folder.

Example:

Code:

sill_file_rename("c:\my_folder\old_name.txt","c:\my_folder\new_name.txt");
/* renames the file from old_name.txt to new_name.txt in the same folder */

sill_file_rename("c:\my_folder\new_name.txt","c:\new_folder\new_name.txt");
/* moves the file new_name.txt file from my_folder to new_folder */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_FILE - The given filename can't be found or doesn't exist.

sill_file_copy

SILL_ERROR error = sill_file_copy(SILL_CHAR *src_filename, SILL_CHAR *dst_filename);
[in] src_filename - File to copy.
[in] dst_filename - New file location.
[return] error - Error result.

Copies the specified src_filename to the dst_filename.  If the file of the same name already exists in the given folder, it will be overwritten.  This function can be used to rename the copy of the file.

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_FILE - The given src_filename can't be found or doesn't exist.

[Shaltif]

[STRING FUNCTIONS]

sill_file_string_write

SILL_ERROR error = sill_file_string_write(SILL_RESOURCE file, SILL_CHAR *string);
[in] file - A file resource handle to write a string to.
[in] string - A NULL terminated string to write to file.
[return] error - Error result.

Writes the specified string to the file at the current write position, overwriting any previously written text at that position and moves the write position to the end of the written string in the file.  The null terminator in string is not written.

Example:

Code:

SILL_RESOURCE file;

sill_file_open(&file,"c:\my_file.dat",SILL_FILE_WRITE);

sill_file_string_write(file,"Hello World");
sill_file_string_write(file,"!  How are you?");

sill_file_close(file);

/* the following is written:

Hello World!  How are you?

*/

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - A general write error occurred while trying to write to the file.

sill_file_string_writeln

SILL_ERROR error = sill_file_string_writeln(SILL_RESOURCE file);
[in] file - A file resource handle to write a newline to.
[return] error - Error result.

Writes a newline (similar to pressing 'enter') character (which character depending on OS) at the current write position, overwriting any previously written text at that position and moves the write position to the end of the newly written newline character.

Example:

Code:

SILL_RESOURCE file;

sill_file_open(&file,"c:\my_file.dat",SILL_FILE_WRITE);

sill_file_string_write(file,"Hello World");
sill_file_string_writeln(file);
sill_file_string_write(file,"!  How are you?");

sill_file_close(file);

/* the following is written:

Hello World
!  How are you?

*/

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - A general write error occurred while trying to write to the file.

sill_file_string_read

SILL_ERROR error = sill_file_string_read(SILL_CHAR *string, SILL_UINT size, SILL_RESOURCE file);
[out] string - A NULL terminated string pulled from the file.
[in] size - The max size the string buffer can contain (in characters).
[in] file - A file resource handle to write a string to.
[return] error - Error result.

Reads a line of text from the specified file at the current read position in that file up to the next newline character found in the file.  The read position is then moved to the newly found newline character with the resulting string copied to the string parameter.  If the size of the line is larger then the max size of the string buffer, only the first part of the line (up to size characters) will be copied.

Example:

Code:

SILL_RESOURCE file;

sill_file_open(&file,"c:\my_file.dat",SILL_FILE_READ);

SILL_CHAR my_string[100];

sill_file_string_read(my_string,100,file);

sill_file_close(file);

/* reads the first line of the file, up to 99 characters (1 being reserved for null terminator) is copied over */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - A general write error occurred while trying to read from the file.

[Shaltif]

[BINARY FUNCTIONS]

sill_file_bin_write

SILL_ERROR error = sill_file_bin_write(SILL_RESOURCE file, SILL_CHAR byte);
[in] file - A file resource handle to write a byte to.
[in] byte - A value between 0 to 255 (inclusive).
[return] error - Error result.

Writes a single byte of data to the given file at the current write position.  The write position is advanced one byte in the file.  A numeric value between 0 to 255 (inclusive) or single character is allowable.  The file must be opened with the binary mode in order to use this function.

Example:

Code:

SILL_RESOURCE file;
sill_file_open(&file,"c:\my_file.dat",SILL_FILE_WRITE|SILL_FILE_BINARY);

sill_file_bin_write(file,70); // writes a single byte, capital 'F', to the file

sill_file_bin_close(file);

/* opens my_file.dat, clearing it and writes 'F' to file */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - The file resource was not opened with the binary mode.

sill_file_bin_write_buffer

SILL_ERROR error = sill_file_bin_write_buffer(SILL_RESOURCE file, SILL_CHAR *bytes, SILL_UINT size);
[in] file - A file resource handle to write a byte to.
[in] bytes - An array of values between 0 to 255 (inclusive).
[in] size - The amount of values stored on the bytes array.
[return] error - Error result.

Writes an array of character bytes, up to size, to the given file at the current write position.  The write position is advanced by size bytes in the file.  A numeric value between 0 to 255 (inclusive) or single character is allowable for each array slot.  The file must be opened with the binary mode in order to use this function.

This does not treat the buffer as a string, so null terminators (character 0) will be treated as normal characters and be written to file if they lie inside the size number of bytes to write.  Make sure the bytes array contains enough data specified by the size parameter, otherwise random memory will be written to the file.

Example:

Code:

SILL_RESOURCE file;
sill_file_open(&file,"c:\my_file.dat",SILL_FILE_WRITE|SILL_FILE_BINARY);

SILL_CHAR buffer[100];
sill_string_copy(buffer,"Hello World");

buffer[12] = '!';
buffer[13] = '?'; //placing characters past the normal null terminator.

sill_file_string_write(file,buffer);
sill_file_string_writeln(file);
sill_file_bin_write_buffer(file,buffer,14);

sill_file_bin_close(file);

/* opens my_file.dat, clearing it
Then we make a buffer that looks like this:  Hello World0!? (The '0' is where the null terminator lies)

Our file, when written, will look like this:

Hello World
Hello World0!?

This is because string_write() automatically stops at the null terminator.
The bin_write_buffer() writes exactly 14 characters, as specified by the size parameter.*/

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - The file resource was not opened with the binary mode.

sill_file_bin_read

SILL_ERROR error = sill_file_bin_read(SILL_CHAR *byte, SILL_RESOURCE file);
[out] byte - A value between 0 to 255 (inclusive).
[in] file - A file resource handle to read a byte from.
[return] error - Error result.

Reads a single byte of data from the file at the current read position.  The read position is advanced by one byte in the file.  The resulting byte can be any value between 0 to 255 (inclusive), or a value a single character can contain.  The file must be opened with the binary mode in order to use this function.

Example:

Code:

SILL_RESOURCE file;
SILL_CHAR byte;
sill_file_open(&file,"c:\my_file.dat",SILL_FILE_READ|SILL_FILE_BINARY);

sill_file_bin_read(&byte,file);

sill_file_bin_close(file);

/* reads a single byte from our file */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - The file resource was not opened with the binary mode.

sill_file_bin_read_buffer

SILL_ERROR error = sill_file_bin_read_buffer(SILL_CHAR *bytes, SILL_UINT size, SILL_RESOURCE file);
[out] bytes - An array of values between 0 to 255 (inclusive).
[in] file - A file resource handle to read bytes from.
[in] size - The number of bytes to read from the file.
[return] error - Error result.

Reads an array of bytes from the file at the current read position.  The read position is advanced by size bytes in the file.  The resulting array of bytes can be any value between 0 to 255 (inclusive), or a value a single character can contain.  The file must be opened with the binary mode in order to use this function.

If the number of bytes to be read is greater then the number of bytes left in the file, the bytes array will be partially filled with the remaining bytes in the file.

Example:

Code:

SILL_RESOURCE file;
SILL_CHAR byte[10];
sill_file_open(&file,"c:\my_file.dat",SILL_FILE_READ|SILL_FILE_BINARY);

sill_file_bin_read_buffer(&byte,file,10);

sill_file_bin_close(file);

/* reads 10 bytes from the file */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - The file resource was not opened with the binary mode.

sill_file_bin_set_size

SILL_ERROR error = sill_file_bin_set_size(SILL_RESOURCE file, SILL_UINT size);
[in] file - A file resource handle to set the size of.
[in] size - The length (in bytes) to set the file.
[return] error - Error result.

Changes the size of a file to the given size (in bytes).  This is accomplished by seeking to the end of the file and appending null bytes to the end until the size of the file matches the size parameter.  Currently, this function only works in increasing the size of the file.  If the file size is larger then the specified size, the function will do nothing.

Example:

Code:

SILL_RESOURCE file;
sill_file_open(&file,"c:\my_file.dat",SILL_FILE_WRITE|SILL_FILE_BINARY);

sill_file_bin_set_size(file,1024);

sill_file_bin_close(file);

/* sets the size of the file to 1 kilobyte in size */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - The file resource was not opened with the binary mode.

sill_file_bin_get_size

SILL_ERROR error = sill_file_bin_get_size(SILL_UINT *size, SILL_RESOURCE file);
[out] size - The length (in bytes) of the file.
[in] file - A file resource handle to get the size of.
[return] error - Error result.

Gets the length of the file, in bytes.

Example:

Code:

SILL_RESOURCE file;
SILL_UINT size;
sill_file_open(&file,"c:\my_file.dat",SILL_FILE_READ|SILL_FILE_BINARY);

sill_file_bin_get_size(&size,file);

sill_file_bin_close(file);

/* gets the size of the file */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - The file resource was not opened with the binary mode.

sill_file_bin_set_position

SILL_ERROR error = sill_file_bin_set_position(SILL_RESOURCE file, SILL_UINT position, SILL_UINT from);
[in] file - A file resource handle to set the position of.
[in] position - The position (in bytes) to set the file read/write pointer.
[in] from - A flag which determines where the position value is relative to.
[return] error - Error result.

Moves the read/write position to the given position.  The from parameter designates where in the file the position value is relative to (such as the beginning, current position or end), with a list of usable constants available here.

Example:

Code:

SILL_RESOURCE file;
sill_file_open(&file,"c:\my_file.dat",SILL_FILE_BINARY);

sill_file_bin_set_position(file,512,SILL_FILE_POS_END);

sill_file_bin_close(file);

/* moves the read/write position to half a kilobyte in from the end of the file */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_PARAMETER - The from parameter was given an invalid constant.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - The file resource was not opened with the binary mode.

sill_file_bin_get_position

SILL_ERROR error = sill_file_bin_get_position(SILL_UINT *position, SILL_RESOURCE file);
[out] position - The current read/write position in the file.
[in] file - A file resource handle to get the position of.
[return] error - Error result.

Gets the current read/write position of the file, in bytes.  This is always relative to the beginning of the file.

Example:

Code:

SILL_RESOURCE file;
SILL_UINT position;
sill_file_open(&file,"c:\my_file.dat",SILL_FILE_BINARY);

sill_file_bin_get_position(&position,file);

sill_file_bin_close(file);

/* gets the read/write position of the file */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_RESOURCE - The specified file resource doesn't exist.
SILL_ERROR_GENERAL - The file resource was not opened with the binary mode.

[Shaltif]

[FILENAME FUNCTIONS]
These functions do not alter any files.  They are used to alter the filename string, such as pulling only the extension or directory of a file, etc.

sill_filename_name

SILL_ERROR error = sill_filename_name(SILL_CHAR *name, SILL_UINT size, SILL_CHAR *filename);
[out] name - The resulting file's name without the directory.
[in] size - The max amount of characters the name parameter can store.
[in] filename - The filename we want to get the name of.
[return] error - Error result.

Splits a directory+filename combo into just the filename component (including the ending extension).

Example:

Code:

SILL_CHAR name[100];

sill_filename_name(name,100,"c:\my_folder\my_sub_folder\my_file.txt");

/* name will now contain only the "my_file.txt" part of the filename */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_PARAMETER - The specified filename was invalid.
SILL_ERROR_GENERAL - The name parameter isn't large enough to hold the filename part.
SILL_ERROR_MEMORY - Unable to allocate required memory.

sill_filename_dir

SILL_ERROR error = sill_filename_dir(SILL_CHAR *directory, SILL_UINT size, SILL_CHAR *filename);
[out] directory - The resulting file's directory.
[in] size - The max amount of characters the name parameter can store.
[in] filename - The filename we want to get the directory of.
[return] error - Error result.

Splits a directory+filename combo into just the directory component (including the final backslash).

Example:

Code:

SILL_CHAR dir[100];

sill_filename_dir(dir,100,"c:\my_folder\my_sub_folder\my_file.txt");

/* dir will now contain only the "c:\my_folder\my_sub_folder\" part of the filename */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_PARAMETER - The specified filename was invalid.
SILL_ERROR_GENERAL - The directory parameter isn't large enough to hold the filename part.
SILL_ERROR_MEMORY - Unable to allocate required memory.

sill_filename_drive

SILL_ERROR error = sill_filename_drive(SILL_CHAR *drive, SILL_UINT size, SILL_CHAR *filename);
[out] drive - The resulting file's drive.
[in] size - The max amount of characters the name parameter can store.
[in] filename - The filename we want to get the drive of.
[return] error - Error result.

Splits a directory+filename combo into just the drive component (not including the colon).

Example:

Code:

SILL_CHAR drive[2];

sill_filename_drive(drive,2,"c:\my_folder\my_sub_folder\my_file.txt");

/* drive will now contain only the "c" part of the filename */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_PARAMETER - The specified filename was invalid.
SILL_ERROR_GENERAL - The drive parameter isn't large enough to hold the filename part.
SILL_ERROR_MEMORY - Unable to allocate required memory.

sill_filename_ext

SILL_ERROR error = sill_filename_ext(SILL_CHAR *extension, SILL_UINT size, SILL_CHAR *filename);
[out] extension - The resulting file's extension.
[in] size - The max amount of characters the name parameter can store.
[in] filename - The filename we want to get the extension of.
[return] error - Error result.

Splits a directory+filename combo into just the extension component (including the leading period).

Example:

Code:

SILL_CHAR ext[5];

sill_filename_ext(ext,5,"c:\my_folder\my_sub_folder\my_file.txt");

/* ext will now contain only the ".txt" part of the filename */

Error Returns:
SILL_ERROR_NONE - No Error.
SILL_ERROR_PARAMETER - The specified filename was invalid.
SILL_ERROR_GENERAL - The extension parameter isn't large enough to hold the filename part.
SILL_ERROR_MEMORY - Unable to allocate required memory.

sill_filename_exists

SILL_UINT exists = sill_filename_exists(SILL_CHAR *filename);
[in] filename - A filename (and path) we want to check if found on the storage device.
[return] exists - Whether the specified filename exists (1) or not (0).

Returns whether the specified filename actually points to an existing file on a storage device (1) or not (0).

Example:

Code:

SILL_UINT exists;

exists = sill_filename_exists("c:\my_folder\my_sub_folder\my_file.txt");

/* exists now contains the result */