Cross-platform C SDK logo

Cross-platform C SDK

Files and directories

❮ Back
Next ❯
This page has been automatically translated using the Google Translate API services. We are working on improving texts. Thank you for your understanding and patience.

Access to the local file system of the computer.


Functions

uint32_tbfile_dir_work (...)
bool_tbfile_dir_set_work (...)
uint32_tbfile_dir_home (...)
uint32_tbfile_dir_data (...)
uint32_tbfile_dir_exec (...)
bool_tbfile_dir_create (...)
Dir*bfile_dir_open (...)
voidbfile_dir_close (...)
bool_tbfile_dir_get (...)
bool_tbfile_dir_delete (...)
File*bfile_create (...)
File*bfile_open (...)
voidbfile_close (...)
bool_tbfile_lstat (...)
bool_tbfile_fstat (...)
bool_tbfile_read (...)
bool_tbfile_write (...)
bool_tbfile_delete (...)

The file system is the hierarchical structure composed of directories and files that allows to organize the persistent data of the computer (Figure 1). It is something that computer users are very familiar with, especially after the irruption of the graphic systems that introduced the desktop simile, folder and document. It starts in a directory called root (/ in Unix or C:\ in Windows) and, from here, they hang all the sub-directories and files forming a tree that grows in depth.

Scheme of a typical file system.
Figure 1: Typical structure of a file system.

At the programming level, the file system is managed through system calls that allow you to create directories, browse their contents, open files, delete them, obtain attributes, etc. A process can read or write data to a file after opening an I/O channel (Streams) which provides a flow of binary data from or to the process itself (Figure 2).

Scheme of I/O stream from the process to the file.
Figure 2: After opening a file, the process has an I/O channel to read or write data.

1. Filename and pathname

These two concepts are recurrent and widely used by API functions that manipulate files. When we navigate through the contents of a directory bfile_dir_get, we obtain a sequence of filenames that is the "flat" name of the element (file or subdirectory) without including its path within the file system (without characters '/' or '\'). On the other hand the pathname is a sequence of one or several filenames separated by '/', '\', which indicates the way forward to locate a certain element. This path can be absolute when it starts with the root directory (C:\Users\john\docs\images\party.png) or relative (docs\images\party.png) when it indicates the partial route from the process current working directory. This working directory by default can be changed with bfile_dir_set_work.


2. Home and AppData

These are two typical directories used by applications to store files relative to a particular user. On the one hand, home indicates the personal directory of the user currently registered in the system, typically C:\Users\john (Windows), /home/john (Linux) or /Users/john (macOS) and we can get it with bfile_dir_home. On the other hand appdata bfile_dir_data is a directory reserved for saving temporary or configuration data of applications. Typical locations can be C:\Users\john\AppData\Roaming (Windows), /home/john/.config (Linux) or /User/john/Library (macOS). The usual thing will be to create a sub-folder with the name of the application /User/john/Library/TheApp.


bfile_dir_work ()

Gets the current working directory of the process. It is the directory from which the relative pathnames will be interpreted.

uint32_t
bfile_dir_work(char_t *pathname,
               const uint32_t size);
pathname

Buffer where the directory will be written.

size

Size in bytes of the buffer pathname.

Return

The number of bytes written in pathname, including the null character '\0'.

Remarks

Filename and pathname


bfile_dir_set_work ()

Change the current working directory of the application. The relative pathnames will be interpreted from here.

bool_t
bfile_dir_set_work(const char_t *pathname,
                   ferror_t *error);
pathname

The name of the directory.

error

Error code if the function fails. Can be NULL.

Return

TRUE if the working directory has changed, FALSE if there have been any errors.

Remarks

Filename and pathname


bfile_dir_home ()

Get the home directory of the current user.

uint32_t
bfile_dir_home(char_t *pathname,
               const uint32_t size);
pathname

Buffer where the directory will be written.

size

Size in bytes of the buffer pathname.

Return

The number of bytes written in pathname, including the null character '\0'.

Remarks

Filename and pathname


bfile_dir_data ()

Gets the AppData directory where application configuration data can be saved.

uint32_t
bfile_dir_data(char_t *pathname,
               const uint32_t size);
pathname

Buffer where the directory will be written.

size

Size in bytes of the buffer pathname.

Return

The number of bytes written in pathname, including the null character '\0'.

Remarks

Home and AppData


bfile_dir_exec ()

Gets the absolute pathname of the current executable.

uint32_t
bfile_dir_exec(char_t *pathname,
               const uint32_t size);
1
2
3
char_t path[512];
bfile_dir_exec(path, 512);
path = "C:\Program Files\TheApp\theapp.exe"
pathname

Buffer where the directory will be written.

size

Size in bytes of the buffer pathname.

Return

The number of bytes written in pathname, including the null character '\0'.


bfile_dir_create ()

Create a new directory. It will fail if any intermediate directory of pathname does not exist.

bool_t
bfile_dir_create(const char_t *pathname,
                 ferror_t *error);
pathname

Name of the directory to be created, ending in a null character '\0'.

error

Error code if the function fails. Can be NULL.

Return

TRUE if the directory has been created, FALSE if there have been any errors.

Remarks

hfile_dir_create create all intermediate directories at once.


bfile_dir_open ()

Open a directory to browse its contents. Then you have to use bfile_dir_get to iterate. The filename is not ordered under any criteria. At the end, you should call bfile_dir_close.

Dir*
bfile_dir_open(const char_t *pathname,
               ferror_t *error);
pathname

Name of the directory, ending in a null character '\0'.

error

Error code if the function fails. Can be NULL.

Return

The directory handler or NULL if there has been an error.


bfile_dir_close ()

Close a previously open directory with bfile_dir_open.

void
bfile_dir_close(Dir **dir);
dir

The directory handler. It will be set to NULL after the closing.


bfile_dir_get ()

Gets the attributes of the current file when we go through a directory. Previously we have to open the directory with bfile_dir_open.

bool_t
bfile_dir_get(Dir *dir,
              char_t *filename,
              const uint32_t size,
              file_type_t *type,
              uint64_t *fsize,
              Date *updated,
              ferror_t *error);
dir

Open directory handler.

filename

Here will write the name of the file or sub-directory, ending in a null character '\0' and without including any path. Can be NULL.

size

Size in bytes of the name buffer.

type

Get the file type. Can be NULL.

fsize

Gets the file size in bytes. Can be NULL.

updated

Gets the date of the last update of the file. Can be NULL.

error

Error code if the function fails. Can be NULL.

Return

TRUE if the file attributes have been read correctly. When there are no more files to go, it returns FALSE with error=ekFNOFILES.

Remarks

This function will advance to the next file within the open directory after obtaining the current item's data. If there is not enough space in name, will return FALSE with error=ekFBIGNAME and will not advance to the next file. Use hfile_dir_loop to browse the contents of a directory more comfortably.


bfile_dir_delete ()

Delete a directory. It will fail if the directory is not completely empty. Use hfile_dir_destroy to completely and recursively erase a directory that may have content.

bool_t
bfile_dir_delete(const char_t *pathname,
                 ferror_t *error);
pathname

Name of the directory, ending in a null character '\0'.

error

Error code if the function fails. Can be NULL.

Return

TRUEif the directory has been deleted, FALSE otherwise.


bfile_create ()

Create a new file. If previously it already exists its content will be erased. The new file will be opened for writing.

File*
bfile_create(const char_t *pathname,
             ferror_t *error);
pathname

File name including its absolute or relative path.

error

Error code if the function fails. Can be NULL.

Return

The file handler or NULL if there has been an error.


bfile_open ()

Open an existing file. Do not create it, if file does not exist this function will fail.

File*
bfile_open(const char_t *pathname,
           const file_mode_t mode,
           ferror_t *error);
pathname

File name including its absolute or relative path.

mode

Opening mode.

error

Error code if the function fails. Can be NULL.

Return

The file handler or NULL if there has been an error.


bfile_close ()

Close a file previously opened with bfile_create or bfile_open.

void
bfile_close(File **file);
file

File handler. It will be set to NULL after closing.


bfile_lstat ()

Get the attributes of a file through its pathname.

bool_t
bfile_lstat(const char_t *pathname,
            file_type_t *type,
            uint64_t *fsize,
            Date *updated,
            ferror_t *error);
pathname

File name including its absolute or relative path.

type

Get the file type. Can be NULL.

fsize

Gets the file size in bytes. Can be NULL.

updated

Gets the date of the last update of the file. Can be NULL.

error

Error code if the function fails. Can be NULL.

Return

TRUEif it worked correctly, or FALSE otherwise.


bfile_fstat ()

Get the attributes of a file through its handler.

bool_t
bfile_fstat(File *file,
            file_type_t *type,
            uint64_t *fsize,
            Date *updated,
            ferror_t *error);
file

File manager.

type

Get the file type. Can be NULL.

fsize

Gets the file size in bytes. Can be NULL.

updated

Gets the date of the last update of the file. Can be NULL.

error

Error code if the function fails. Can be NULL.

Return

TRUEif it worked correctly, or FALSE otherwise.


bfile_read ()

Read data from an open file.

bool_t
bfile_read(File *file,
           byte_t *data,
           const uint32_t size,
           uint32_t *rsize,
           ferror_t *error);
file

File handler.

data

Buffer where the read data will be written.

size

The number of maximum bytes to read.

rsize

Receive the number of bytes actually read. Can be NULL.

error

Error code if the function fails. Can be NULL.

Return

TRUE if the data has been read correctly. If there is no more data (end of the file) it returns FALSE with rsize = 0 and error=ekFOK.

Remarks

File stream implements high-level functions for reading/writing files.


bfile_write ()

Write data in an open file.

bool_t
bfile_write(File *file,
            const byte_t *data,
            const uint32_t size,
            uint32_t *wsize,
            ferror_t *error);
file

File handler.

data

Buffer that contains the data to write.

size

The number of bytes to write.

wsize

It receives the number of bytes actually written. Can be NULL.

error

Error code if the function fails. Can be NULL.

Return

TRUE if the data has been written, or FALSE if there have been any errors.

Remarks

File stream implements high-level functions for reading/writing files.


bfile_delete ()

Delete a file from the file system.

bool_t
bfile_delete(const char_t *pathname,
             ferror_t *error);
pathname

File name including its absolute or relative path.

error

Error code if the function fails. Can be NULL.

Return

TRUE if the file has been deleted, or FALSE if any error has occurred.

❮ Back
Next ❯