20 KiB
MZ_OS
These functions provide support for handling common file system operations.
- Path
- Directory
- File
- Operating System
- mz_os_unicode_string_create
- mz_os_unicode_string_delete
- mz_os_utf8_string_create
- mz_os_utf8_string_delete
- mz_os_rand
- mz_os_rename
- mz_os_unlink
- mz_os_file_exists
- mz_os_get_file_size
- mz_os_get_file_date
- mz_os_set_file_date
- mz_os_get_file_attribs
- mz_os_set_file_attribs
- mz_os_make_dir
- mz_os_open_dir
- mz_os_read_dir
- mz_os_close_dir
- mz_os_is_dir
- mz_os_is_symlink
- mz_os_make_symlink
- mz_os_read_symlink
- mz_os_ms_time
Path
The mz_path family of functions are helper functions used when constructing file system paths.
mz_path_combine
Combines two paths.
Arguments
| Type | Name | Description |
|---|---|---|
| char * | path | Base path |
| const char * | join | Path to append |
| int32_t | max_path | Maximum path buffer size |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
char path[120];
strncat(path, "c:\\windows\\", sizeof(path));
mz_path_combine(path, "temp", sizeof(path));
printf("Combined path: %s\n", path);
mz_path_append_slash
Appends a path slash on to the end of the path. To get the path slash character for the compiler platform use MZ_PATH_SLASH_PLATFORM preprocessor define.
Arguments
| Type | Name | Description |
|---|---|---|
| char * | path | Path |
| int32_t | max_path | Maximum bytes to store path |
| char | slash | Path slash character |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
char path[120];
strncat(path, "c:\\windows", sizeof(path));
mz_path_append_slash(path, sizeof(path), MZ_PATH_SLASH_PLATFORM);
printf("Path with end slash: %s\n", path);
mz_path_remove_slash
Removes a path slash from the end of the path.
Arguments
| Type | Name | Description |
|---|---|---|
| char * | path | Path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
char path[120];
strncat(path, "c:\\windows\\", sizeof(path));
mz_path_remove_slash(path);
printf("Path with no slash: %s\n", path);
mz_path_has_slash
Returns whether or not the path ends with slash.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if has slash. |
Example
const char *path = "c:\\windows\\";
if (mz_path_has_slash(path) == MZ_OK)
printf("Path ends with a slash\n");
else
printf("Path does not end with a slash\n");
mz_path_convert_slashes
Converts the slashes in a path. This can be used to convert all unix path slashes to windows path slashes or conver all windows path slashes to unix path slashes. If there are mixed slashes in the path, it can unify them to all one format.
Arguments
| Type | Name | Description |
|---|---|---|
| char * | path | Path |
| char | slash | Path slash character |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if has slash. |
Example
char path[120];
strncat(path, "c:\\windows\\", sizeof(path));
if (mz_path_convert_slashes(path, MZ_PATH_SLASH_UNIX) == MZ_OK)
printf("Path converted to unix slashes: %s\n", path);
mz_path_compare_wc
Compares two paths with a wildcard.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Path |
| const char * | wildcard | Wildcard pattern |
| uint8_t | ignore_case | Ignore case during comparison if 1. |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if matched, MZ_EXIST_ERROR if not matched. |
Example
const char *path = "test.txt";
if (mz_path_compare_wc(path, "*.txt", 0) == MZ_OK)
printf("%s is a text file\n", path);
else
printf("%s is not a text file\n", path);
mz_path_resolve
Resolves a path. Path parts that only contain dots will be resolved. If a path part contains a single dot, it will be remoed. If a path part contains two dots, it will remove the last path part. This function can be used to prevent the zipslip vulnerability and ensure that files are not written outside of their intended target.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Path |
| char * | target | Resolved path character array |
| int32_t | max_target | Maximum size of resolved path array |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\windows\\..\\";
char target[120];
mz_path_resolve(path, target, sizeof(target));
printf("Resolved path: %s\n", target);
mz_path_remove_filename
Removes the filename from a path.
Arguments
| Type | Name | Description |
|---|---|---|
| char * | path | Path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
char path[120];
strncpy(path, "c:\\windows\\test.txt", sizeof(path));
printf("Path: %s\n", path);
mz_path_remove_filename(path);
printf("Path with no filename: %s\n", path);
mz_path_remove_extension
Remove the extension from a path.
Arguments
| Type | Name | Description |
|---|---|---|
| char * | path | Path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
char path[120];
strncpy(path, "c:\\windows\\test.txt", sizeof(path));
printf("Path: %s\n", path);
mz_path_remove_extension(path);
printf("Path with no file extension: %s\n", path);
mz_path_get_filename
Get the filename from a path.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Path |
| const char ** | filename | Pointer to filename string |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\windows\\test.txt";
const char *filename = NULL;
printf("Path: %s\n", path);
if (mz_path_get_filename(path, &filename) == MZ_OK)
printf("Filename: %s\n", filename);
else
printf("Path has no filename\n");
Directory
mz_dir_make
Creates a directory recursively.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\temp\\x\\y\\z\\";
if (mz_dir_make(path) == MZ_OK)
printf("Dir was created: %s\n", path);
else
printf("Dir was not created: %s\n", path);
File
mz_file_get_crc
Gets the crc32 hash of a file. This function helps provide functional backwards compatibility.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Path to calculate CRC value for |
| uint32_t * | result_crc | Pointer to store the calculated CRC value |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\temp\\test.txt";
uint32_t crc = 0;
if (mz_file_get_crc(path, &crc) == MZ_OK)
printf("File %s CRC: %08x\n", path, crc);
else
printf("Failed to calculate CRC: %s\n", path);
Operating System
The mz_os family of functions wrap all platform specific code necessary to zip and unzip files.
mz_os_unicode_string_create
Create unicode string from a string with another encoding.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | string | String to convert |
| int32_t | encoding | String encoding (See MZ_ENCODING) |
Return
| Type | Description |
|---|---|
| wchar_t * | Returns pointer to unicode string if successful, otherwise NULL. |
Example
char *test = "test";
wchar_t *test_unicode = mz_os_unicode_string_create(test, MZ_ENCODING_UTF8);
if (test_unicode) {
printf("Unicode test string created\n");
mz_os_unicode_string_delete(&test_unicode);
}
mz_os_unicode_string_delete
Delete a unicode string that was created with mz_os_unicode_string_create.
Arguments
| Type | Name | Description |
|---|---|---|
| wchar_t ** | string | Pointer to unicode string |
Example
char *test = "test";
wchar_t *test_unicode = mz_os_unicode_string_create(test, MZ_ENCODING_UTF8);
if (test_unicode) {
printf("Unicode test string created\n");
mz_os_unicode_string_delete(&test_unicode);
}
mz_os_utf8_string_create
Create a utf8 string from a string with another encoding.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | string | String to convert |
| int32_t | encoding | String encoding (See MZ_ENCODING) |
Return
| Type | Description |
|---|---|
| char * | Returns pointer to UTF-8 encoded string if successful, otherwise NULL. |
Example
char *test = "test";
char *test_utf8 = mz_os_utf8_string_create(test, MZ_ENCODING_CODEPAGE_437);
if (test_utf8) {
printf("UTF-8 test string created\n");
mz_os_utf8_string_delete(&test_utf8);
}
mz_os_utf8_string_delete
Delete a utf8 string that was created with mz_os_utf8_string_create.
Arguments
| Type | Name | Description |
|---|---|---|
| char ** | string | Pointer to utf8 encoded string |
Example
char *test = "test";
char *test_utf8 = mz_os_utf8_string_create(test, MZ_ENCODING_CODEPAGE_437);
if (test_utf8) {
printf("UTF-8 test string created\n");
mz_os_utf8_string_delete(&test_utf8);
}
mz_os_rand
Random number generator (not cryptographically secure). For a cryptographically secure random number generator use mz_crypt_rand.
Arguments
| Type | Name | Description |
|---|---|---|
| uint8_t * | buf | Buffer to fill with random data |
| int32_t | size | Maximum size of buffer array |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
uint8_t buf[120];
if (mz_os_rand(buf, sizeof(buf)) == MZ_OK)
printf("%d bytes of random data generated\n", sizeof(buf));
mz_os_rename
Rename a file.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | source_path | Original path |
| const char * | target_path | New path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
if (mz_os_rename("c:\\test1.txt", "c:\\test2.txt") == MZ_OK)
printf("File was renamed successfully\n");
mz_os_unlink
Delete an existing file.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
if (mz_os_unlink("c:\\test2.txt") == MZ_OK)
printf("File was deleted successfully\n");
mz_os_file_exists
Check to see if a file exists.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\test2.txt";
if (mz_os_file_exists(path) == MZ_OK)
printf("File %s exists\n", path);
else
printf("File %s does not exist\n", path);
mz_os_get_file_size
Gets the length of a file.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File path |
Return
| Type | Description |
|---|---|
| int64_t | Size of file, does not check for existence of file. |
Example
const char *path = "c:\\test3.txt";
if (mz_os_file_exists(path) == MZ_OK) {
int64_t file_size = mz_os_get_file_size(path);
printf("File %s size %lld\n", path, file_size);
} else {
printf("File %s does not exist\n", path);
}
mz_os_get_file_date
Gets a file's modified, access, and creation dates if supported. Creation date is not supported on Linux based systems and zero is returned for creation_date on those systems.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File path |
| time_t * | modified_date | Pointer to store file's modified unix timestamp |
| time_t * | accessed_date | Pointer to store file's accessed unix timestamp |
| time_t * | creation_date | Pointer to store file's creation unix timestamp |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\test4.txt";
time_t modified_date, accessed_date, creation_date;
if (mz_os_get_file_date(path, &modified_date, &accessed_date, &creation_date) == MZ_OK)
printf("File %s modified %lld accessed %lld creation %lld\n", path, modified_date, accessed_date, creation_date);
mz_os_set_file_date
Sets a file's modified, access, and creation dates if supported. Creation date is not supported on Linux based systems.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File path |
| time_t | modified_date | File's modified unix timestamp |
| time_t | accessed_date | File's accessed unix timestamp |
| time_t | creation_date | File's creation unix timestamp |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *src_path = "c:\\test4.txt";
const char *target_path = "c:\\test5.txt";
time_t modified_date, accessed_date, creation_date;
if (mz_os_get_file_date(src_path, &modified_date, &accessed_date, &creation_date) == MZ_OK) {
printf("Source file %s modified %lld accessed %lld creation %lld\n", path, modified_date, accessed_date, creation_date);
if (mz_os_set_file_date(target_path, modified_date, accessed_date, creation_date) == MZ_OK) {
printf("Target file dates changed successfully\n");
}
}
mz_os_get_file_attribs
Gets a file's attributes.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File path |
| uint32_t * | attributes | Pointer to store file attributes value |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\test6.txt";
uint32_t attributes = 0;
if (mz_os_get_file_attribs(path, &attributes) == MZ_OK)
printf("File %s attributes %08x\n", attributes);
mz_os_set_file_attribs
Sets a file's attributes.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File path |
| uint32_t | attributes | File attributes value |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\test6.txt";
uint32_t attributes = 0;
if (mz_os_get_file_attribs(path, &attributes) == MZ_OK) {
printf("File %s attributes %08x\n", attributes);
attributes |= FILE_ATTRIBUTE_READONLY;
if (mz_os_set_file_attribs(path, attributes) == MZ_OK) {
printf("File changed to readonly\n");
}
}
mz_os_make_dir
Creates a directory. To recursively create a directory use mz_dir_make.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Directory path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
if (mz_os_make_dir("c:\\testdir\\") == MZ_OK)
printf("Test directory created\n");
mz_os_open_dir
Opens a directory for listing.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Directory path |
Return
| Type | Description |
|---|---|
| DIR * | Directory enumeration handle, returns NULL if error. |
Example
const char *search_dir = "c:\\test1\\";
DIR *dir = mz_open_dir(search_dir);
if (dir) {
printf("Dir %s was opened\n", search_dir);
mz_os_close_dir(dir);
}
mz_os_read_dir
Reads a directory listing entry.
Arguments
| Type | Name | Description |
|---|---|---|
| DIR * | dir | Directory enumeration handle |
Return
| Type | Description |
|---|---|
| struct dirent * | Pointer to directory entry information structure. To get the name of the directory use the d_name structure field. |
Example
const char *search_dir = "c:\\test2\\";
DIR *dir = mz_open_dir(search_dir);
if (dir) {
struct dirent *entry = NULL;
printf("Dir %s was opened\n", search_dir);
while ((entry = mz_os_read_dir(dir))) {
printf("Dir entry: %s was opened\n", entry->d_name);
}
mz_os_close_dir(dir);
}
mz_os_close_dir
Closes a directory that has been opened for listing.
Arguments
| Type | Name | Description |
|---|---|---|
| DIR * | dir | Directory enumeration handle |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *search_dir = "c:\\test3\\";
DIR *dir = mz_open_dir(search_dir);
if (dir) {
struct dirent *entry = NULL;
printf("Dir %s was opened\n", search_dir);
while ((entry = mz_os_read_dir(dir))) {
printf("Dir entry: %s was opened\n", entry->d_name);
}
mz_os_close_dir(dir);
}
mz_os_is_dir
Checks to see if path is a directory.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File system path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if it is a directory. |
Example
const char *path = "c:\\test7.txt";
if (mz_os_is_dir(path) == MZ_OK)
printf("Path %s is a directory\n", path);
else
printf("Path %s is not a directory\n", path);
mz_os_is_symlink
Checks to see if path is a symbolic link.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | File system path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if it is a symbolic link. |
Example
const char *path = "c:\\test7.txt";
if (mz_os_is_symlink(path) == MZ_OK)
printf("Path %s is a symbolic link\n", path);
else
printf("Path %s is not a symbolic link\n", path);
mz_os_make_symlink
Creates a symbolic link pointing to a target.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Link path |
| const char * | target_path | Actual path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\test7.txt";
const char *target_path = "c:\\test8.txt";
if (mz_os_make_symlink(path, target_path) == MZ_OK)
printf("Symbolic link created at %s pointing to %s\n", path, target_path);
mz_os_read_symlink
Gets the target path for a symbolic link.
Arguments
| Type | Name | Description |
|---|---|---|
| const char * | path | Link path |
| char * | target_path | Actual path |
| int32_t | max_path | Maximum bytes to store actual path |
Return
| Type | Description |
|---|---|
| int32_t | MZ_ERROR code, MZ_OK if successful |
Example
const char *path = "c:\\test7.txt";
const char *target_path = "c:\\test8.txt";
if (mz_os_make_symlink(path, target_path) == MZ_OK) {
char actual_path[120];
printf("Symbolic link created at %s pointing to %s\n", path, target_path);
if (mz_os_read_symlink(path, actual_path, sizeof(actual_path)) == MZ_OK) {
if (strcmp(target_path, actual_path) == 0) {
printf("Confirmed symbolic link created\n");
}
}
}
mz_os_ms_time
Gets the time in milliseconds.
Return
| Type | Description |
|---|---|
| uint64_t | Current time in milliseconds |
Example
uint64_t current_time = mz_os_ms_time();
printf("Current time in %lldms\n", current_time);