ML Reference
|
Defines a C API to the file system for WIN32 and Unix systems. More...
#include "mlUtilsSystem.h"
#include "mlSystemWarningsDisable.h"
#include <fcntl.h>
#include <sys/stat.h>
#include "mlSystemWarningsRestore.h"
Go to the source code of this file.
Defines | |
#define | ML_O_APPEND _O_APPEND |
Include file control stuff. | |
#define | ML_O_BINARY _O_BINARY |
Mode to open file in binary mode; note that inary and text mode are not distinguished on Unix systems. | |
#define | ML_O_CREAT _O_CREAT |
Mode to create a new file. | |
#define | ML_O_RANDOM _O_RANDOM |
Mode to open/create a file optimized for random access. | |
#define | ML_O_RDONLY _O_RDONLY |
Mode to open a file only for reading. | |
#define | ML_O_RDWR _O_RDWR |
Mode to open a file for reading and writing. | |
#define | ML_O_TEXT _O_TEXT |
Mode to open file in text mode; note that inary and text mode are not distinguished on Unix systems. | |
#define | ML_O_TRUNC _O_TRUNC |
Mode to open a file throwing away its contents. | |
#define | ML_O_WRONLY _O_WRONLY |
Mode to open a file only for writing. | |
#define | ML_O_LARGEFILE 0 |
Mode to open a file with large file support; this exists only on Unix systems. | |
#define | ML_S_IREAD _S_IREAD |
pMode (permission flag) used for read only file opening. | |
#define | ML_S_IWRITE _S_IWRITE |
pMode (permission flag) used for write only file opening. | |
Functions | |
ML_UTILS_EXPORT void | MLTranslateErrorCode (MLErrorCode *err) |
Error code translation from global fileIO error code given by errno to ML error code *err if err is passed as non NULL; if err is passed as NULL then the call is ignored. | |
File access functions working with valid UTF-8 Unicode file names | |
#define | MLGetNonExistingRandomFileNameWithPostFix_Is_Available |
ML_UTILS_EXPORT FILE * | MLfopen (const char *fileName, const char *mode) ML_RETURN_VALUE_SHOULD_BE_USED |
Thread-safety: These functions are reentrant. | |
ML_UTILS_EXPORT MLErrorCode | MLfclose (FILE *file) |
Closes an open file given by descriptor file and returns 0 on success and non zero values on failure. | |
ML_UTILS_EXPORT MLErrorCode | MLremove (const char *fileName) |
Deletes file with name fileName . | |
ML_UTILS_EXPORT MLErrorCode | MLrename (const char *oldName, const char *newName) |
Renames a file with name oldName to newName . | |
ML_UTILS_EXPORT int | MLopen (const char *fileName, int openFlags, int pMode) ML_RETURN_VALUE_SHOULD_BE_USED |
Opens the file with name fileName with the given openFlags , returns a file descriptor or -1 on error. | |
ML_UTILS_EXPORT MLErrorCode | MLclose (int fileDescriptor) |
Closes an open file given by a the file descriptor fileDescriptor and returns ML_RESULT_OK on success and on failure an MLErrorCode describing the problem. | |
ML_UTILS_EXPORT int | MLFileExists (const char *fileName) |
Returns 1 if the given with name fileName exists, 0 otherwise or if fileName is NULL. | |
ML_UTILS_EXPORT char * | MLGetTempPath () ML_RETURN_VALUE_SHOULD_BE_USED |
Returns the path to the temporary directory of the current user or NULL on failure. | |
ML_UTILS_EXPORT char * | MLGetNonExistingRandomFileName (const char *prefix) ML_RETURN_VALUE_SHOULD_BE_USED |
If prefix is NULL or empty then a file name is returned which does not exist in the temp file directory determined with MLGetTempPath(). | |
ML_UTILS_EXPORT char * | MLGetNonExistingRandomFileNameWithPostFix (const char *prefix, const char *postFix) ML_RETURN_VALUE_SHOULD_BE_USED |
Same as MLGetNonExistingRandomFileName() with the difference that the resulting unique file name also has a suffix given by postFix. | |
ML_UTILS_EXPORT int | MLFileIsReadable (const char *fileName) |
Returns 1 if the given fileName exists and is readable, 0 otherwise. | |
ML_UTILS_EXPORT int | MLFileIsWritable (const char *fileName) |
Returns 1 if the given file with name fileName exists and is writable, 0 otherwise. | |
ML_UTILS_EXPORT MLErrorCode | MLFileWriteStringData (const char *fileName, const char *str) ML_RETURN_VALUE_SHOULD_BE_USED |
Creates, opens, and overwrites the given file with name fileName with the given non NULL, null terminated data string str , and returns ML_RESULT_OK on success or an MLErrorCode describing the problem on failure. | |
ML_UTILS_EXPORT MLErrorCode | MLFileWriteBinaryData (const char *fileName, const MLuint8 *data, size_t numBytes) ML_RETURN_VALUE_SHOULD_BE_USED |
Creates, opens, and overwrites the given file with name fileName with the given data of a given numBytes , and returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem. | |
ML_UTILS_EXPORT MLErrorCode | MLFileWriteBinaryDataAt (int fileDescriptor, MLuint startPosition, const MLuint8 *data, size_t numBytes) ML_RETURN_VALUE_SHOULD_BE_USED |
Overwrites a section of the file given by file descriptor fileDescriptor which must have been opened with mode ML_O_RDWR or ML_O_WRONLY at position startPosition with the given data with numBytes . | |
ML_UTILS_EXPORT MLErrorCode | MLFileAppendStringData (const char *fileName, const char *strData) ML_RETURN_VALUE_SHOULD_BE_USED |
Appends the given null-terminated string strData to the file given by name fileName , creating a new file if it does not exist. | |
ML_UTILS_EXPORT MLErrorCode | MLFileAppendBinaryData (const char *fileName, const MLuint8 *data, size_t numBytes) ML_RETURN_VALUE_SHOULD_BE_USED |
Appends numBytes of data given by data to the file given by name fileName , creating a new file if it does not exist. | |
ML_UTILS_EXPORT MLErrorCode | MLFileAppendBinaryDataWithDescriptor (int fileDescriptor, const MLuint8 *data, size_t numBytes) ML_RETURN_VALUE_SHOULD_BE_USED |
Appends numBytes of data given by data to the file given by file descriptor fileDescriptor which must be valid and indicate a writable file. | |
ML_UTILS_EXPORT char * | MLFileReadAllAsString (const char *fileName) ML_RETURN_VALUE_SHOULD_BE_USED |
Reads the complete file with a fileName as a string, returns NULL on error. | |
ML_UTILS_EXPORT MLuint8 * | MLFileReadAllAsBinary (const char *fileName) ML_RETURN_VALUE_SHOULD_BE_USED |
Reads the complete file with a fileName as binary data, returns NULL on error. | |
ML_UTILS_EXPORT char * | MLFileReadChunkAsString (const char *fileName, MLuint startPosition, MLuint numBytes) ML_RETURN_VALUE_SHOULD_BE_USED |
Reads a string segment starting at startPosition from the file given by fileName as a string and returns NULL on error. | |
ML_UTILS_EXPORT MLuint8 * | MLFileReadChunkAsBinary (const char *fileName, MLuint startPosition, MLuint numBytes) ML_RETURN_VALUE_SHOULD_BE_USED |
Reads a data segment starting at startPosition from the file given by fileName and returns NULL on error. | |
ML_UTILS_EXPORT MLuint8 * | MLFileReadChunkAsBinaryFromDesc (int fileDescriptor, MLuint startPosition, MLuint numBytes, int useCurrentPosition) ML_RETURN_VALUE_SHOULD_BE_USED |
Reads a data segment starting at startPosition from the file given by fileDescriptor and returns NULL on error. | |
ML_UTILS_EXPORT char * | MLFileReadChunkAsStringFromDesc (int fileDescriptor, MLuint startPosition, MLuint numBytes) ML_RETURN_VALUE_SHOULD_BE_USED |
Reads a string segment starting at startingPosition from the file given by fileDescriptor as a string and returns NULL on error. | |
ML_UTILS_EXPORT MLint | MLFileGetSizeFromDescriptor (int fileDescriptor) |
Returns the size of the file given by the file descriptor fileDescriptor A negative value is returned on any error if fileDescriptor is invalid or on files larger than 2^63-1 bytes. | |
ML_UTILS_EXPORT MLint | MLFileGetSizeFromName (const char *fileName) |
Returns the size of the file given by the null-terminated file name fileName . | |
ML_UTILS_EXPORT MLint | MLFileSetBytePos (int fileDescriptor, MLuint position) ML_RETURN_VALUE_SHOULD_BE_USED |
Sets the pointer of a file given by descriptor fileDescriptor to a position and returns the positive position on success and -1 on failure. | |
ML_UTILS_EXPORT MLint | MLFileGetBytePos (int fileDescriptor) ML_RETURN_VALUE_SHOULD_BE_USED |
Returns current file position of the file given by descriptor fileDescriptor ; it returns the positive position (>= 0) on success and -1 on failure. | |
ML_UTILS_EXPORT MLErrorCode | MLCreateDirectory (const char *path) ML_RETURN_VALUE_SHOULD_BE_USED |
The directory path is created. |
Defines a C API to the file system for WIN32 and Unix systems.
All methods support UTF-8 unicode strings to access files that contain unicode chars in their absolute filename. Note that this file needs to be included explicitly, because it is no default include of mlUtils.h.
Diagnostic information is usually described specifically in each function documentation. Most functions report errors by an MLErrorCode return value describing any problem or returning ML_RESULT_OK on success. Functions having no such return value usually set the errno variable very similar to normal system functions. On success that variable is not defined and should not be evaluated then. Only on function failure denoted by the return value it describes the nature of any error. Functions returning an MLErrorCode usually do NOT set errno (unless documented differently). Typical errno values used/set by this library are:
Definition in file mlFileSystem.h.
#define ML_O_APPEND _O_APPEND |
Include file control stuff.
Define ML file IO modes to resolve platform dependencies; see standard C documentation for meaning. Mode to open file to append data.
Definition at line 53 of file mlFileSystem.h.
#define ML_O_BINARY _O_BINARY |
Mode to open file in binary mode; note that inary and text mode are not distinguished on Unix systems.
Definition at line 56 of file mlFileSystem.h.
#define ML_O_CREAT _O_CREAT |
Mode to create a new file.
Definition at line 59 of file mlFileSystem.h.
#define ML_O_LARGEFILE 0 |
Mode to open a file with large file support; this exists only on Unix systems.
Definition at line 80 of file mlFileSystem.h.
#define ML_O_RANDOM _O_RANDOM |
Mode to open/create a file optimized for random access.
Definition at line 62 of file mlFileSystem.h.
#define ML_O_RDONLY _O_RDONLY |
Mode to open a file only for reading.
Definition at line 65 of file mlFileSystem.h.
#define ML_O_RDWR _O_RDWR |
Mode to open a file for reading and writing.
Definition at line 68 of file mlFileSystem.h.
#define ML_O_TEXT _O_TEXT |
Mode to open file in text mode; note that inary and text mode are not distinguished on Unix systems.
Definition at line 71 of file mlFileSystem.h.
#define ML_O_TRUNC _O_TRUNC |
Mode to open a file throwing away its contents.
Definition at line 74 of file mlFileSystem.h.
#define ML_O_WRONLY _O_WRONLY |
Mode to open a file only for writing.
Definition at line 77 of file mlFileSystem.h.
#define ML_S_IREAD _S_IREAD |
pMode (permission flag) used for read only file opening.
Definition at line 83 of file mlFileSystem.h.
#define ML_S_IWRITE _S_IWRITE |
pMode (permission flag) used for write only file opening.
Definition at line 86 of file mlFileSystem.h.
#define MLGetNonExistingRandomFileNameWithPostFix_Is_Available |
Definition at line 231 of file mlFileSystem.h.
ML_UTILS_EXPORT MLErrorCode MLclose | ( | int | fileDescriptor | ) |
Closes an open file given by a the file descriptor fileDescriptor
and returns ML_RESULT_OK on success and on failure an MLErrorCode describing the problem.
ML_UTILS_EXPORT MLErrorCode MLCreateDirectory | ( | const char * | path | ) |
The directory path
is created.
path | valid and null-terminated UTF8 path of the directory. |
ML_UTILS_EXPORT MLErrorCode MLfclose | ( | FILE * | file | ) |
Closes an open file given by descriptor file
and returns 0 on success and non zero values on failure.
file | must be a valid pointer for an open file. |
ML_UTILS_EXPORT MLErrorCode MLFileAppendBinaryData | ( | const char * | fileName, |
const MLuint8 * | data, | ||
size_t | numBytes | ||
) |
Appends numBytes
of data given by data
to the file given by name fileName
, creating a new file if it does not exist.
It returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem. Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT MLErrorCode MLFileAppendBinaryDataWithDescriptor | ( | int | fileDescriptor, |
const MLuint8 * | data, | ||
size_t | numBytes | ||
) |
Appends numBytes
of data given by data
to the file given by file descriptor fileDescriptor
which must be valid and indicate a writable file.
It returns MLErrorCode on success or on failure an MLErrorCode describing the problem.
ML_UTILS_EXPORT MLErrorCode MLFileAppendStringData | ( | const char * | fileName, |
const char * | strData | ||
) |
Appends the given null-terminated string strData
to the file given by name fileName
, creating a new file if it does not exist.
It returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem. Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT int MLFileExists | ( | const char * | fileName | ) |
Returns 1 if the given with name fileName
exists, 0 otherwise or if fileName is NULL.
Sets errno if 0 is returned, use MLTranslateErrorCode to get an appropriate MLErrorCode for it. Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT MLint MLFileGetBytePos | ( | int | fileDescriptor | ) |
Returns current file position of the file given by descriptor fileDescriptor
; it returns the positive position (>= 0) on success and -1 on failure.
File sizes > 2^63-1 are handled as error. If < 0 is returned then errno describes the error.
ML_UTILS_EXPORT MLint MLFileGetSizeFromDescriptor | ( | int | fileDescriptor | ) |
Returns the size of the file given by the file descriptor fileDescriptor
A negative value is returned on any error if fileDescriptor
is invalid or on files larger than 2^63-1 bytes.
If < 0 is returned then errno describes the error.
ML_UTILS_EXPORT MLint MLFileGetSizeFromName | ( | const char * | fileName | ) |
Returns the size of the file given by the null-terminated file name fileName
.
A negative value is returned on any error if fileName
is NULL or on files larger than 2^63-1 bytes. Supports UTF-8 encoded unicode file names. If < 0 is returned then errno describes the error.
ML_UTILS_EXPORT int MLFileIsReadable | ( | const char * | fileName | ) |
Returns 1 if the given fileName
exists and is readable, 0 otherwise.
Sets errno if 0 is returned, use MLTranslateErrorCode to get an appropriate MLErrorCode for it. Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT int MLFileIsWritable | ( | const char * | fileName | ) |
Returns 1 if the given file with name fileName
exists and is writable, 0 otherwise.
Sets errno if 0 is returned, use MLTranslateErrorCode to get an appropriate MLErrorCode for it. Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT MLuint8* MLFileReadAllAsBinary | ( | const char * | fileName | ) |
Reads the complete file with a fileName
as binary data, returns NULL on error.
The returned data chunk needs to be destroyed by calling MLFree() or Memory::freeMemory(). Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT char* MLFileReadAllAsString | ( | const char * | fileName | ) |
Reads the complete file with a fileName
as a string, returns NULL on error.
The returned string will be null-terminated. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT MLuint8* MLFileReadChunkAsBinary | ( | const char * | fileName, |
MLuint | startPosition, | ||
MLuint | numBytes | ||
) |
Reads a data segment starting at startPosition
from the file given by fileName
and returns NULL on error.
If the file ends before numBytes
can be read, the returned data chunk will not be shorter but only partially filled with data. If numBytes
is 0, a valid memory allocation of 0 bytes takes place which also needs to be freed. Note that this function supports only files up to 2^63 bytes, because internally a sign flag is lost. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). Supports UTF-8 encoded unicode file names. If NULL is returned then errno describes the error.
ML_UTILS_EXPORT MLuint8* MLFileReadChunkAsBinaryFromDesc | ( | int | fileDescriptor, |
MLuint | startPosition, | ||
MLuint | numBytes, | ||
int | useCurrentPosition | ||
) |
Reads a data segment starting at startPosition
from the file given by fileDescriptor
and returns NULL on error.
If the file ends before numBytes
can be read, the returned data chunk will not be shorter but only partially filled with data. If numBytes
is 0, a valid memory allocation of 0 bytes takes place which also needs to be freed. Note that this function supports only files up to 2^63 bytes, because internally a sign flag is lost. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). In case of (file IO) errors the file is not closed. If NULL is returned then errno describes the error. If useCurrentPosition
is 1, the current file position is taken and used to overwrite startPosition
. If useCurrentPosition
is 0, the startPosition
is used normally. Other useCurrentPosition
values are handled as error.
ML_UTILS_EXPORT char* MLFileReadChunkAsString | ( | const char * | fileName, |
MLuint | startPosition, | ||
MLuint | numBytes | ||
) |
Reads a string segment starting at startPosition
from the file given by fileName
as a string and returns NULL on error.
The returned string will be null-terminated and one byte larger than numBytes
for the num-terminating character. If the file ends before numBytes
can be read, the string will be shorter and also be null-terminated. If numBytes
is 0, a valid memory allocation of 0 bytes takes place which also needs to be freed. Note that this function supports only files up to 2^63 bytes, because internally a sign flag is lost. On 32 bit system numBytes must not exceed 2^31 or NULL is returned as error. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT char* MLFileReadChunkAsStringFromDesc | ( | int | fileDescriptor, |
MLuint | startPosition, | ||
MLuint | numBytes | ||
) |
Reads a string segment starting at startingPosition
from the file given by fileDescriptor
as a string and returns NULL on error.
The returned string will be null-terminated and one byte larger than numBytes
for the num-terminating character. If the file ends before numBytes
can be read, the string will be shorter and also be null-terminated. If numBytes
is 0, a valid memory allocation of 0 bytes takes place which also needs to be freed. Note that this function supports only files up to 2^63 bytes, because internally a sign flag is lost. On 32 bit system numBytes must not exceed 2^31 or NULL is returned as error. The returned string needs to be destroyed by calling MLFree() or Memory::freeMemory(). In case of (file IO) errors the file is not closed. If NULL is returned then errno describes the error.
Sets the pointer of a file given by descriptor fileDescriptor
to a position
and returns the positive position on success and -1 on failure.
The position is valid only up to 2^63-1 because internally the sign flag is used. If < 0 is returned then errno describes the error.
ML_UTILS_EXPORT MLErrorCode MLFileWriteBinaryData | ( | const char * | fileName, |
const MLuint8 * | data, | ||
size_t | numBytes | ||
) |
Creates, opens, and overwrites the given file with name fileName
with the given data
of a given numBytes
, and returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem.
The file is closed after write operation. Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT MLErrorCode MLFileWriteBinaryDataAt | ( | int | fileDescriptor, |
MLuint | startPosition, | ||
const MLuint8 * | data, | ||
size_t | numBytes | ||
) |
Overwrites a section of the file given by file descriptor fileDescriptor
which must have been opened with mode ML_O_RDWR or ML_O_WRONLY at position startPosition
with the given data
with numBytes
.
It returns ML_RESULT_OK on success or on failure an MLErrorCode describing the problem. The file is NOT closed after writing.
ML_UTILS_EXPORT MLErrorCode MLFileWriteStringData | ( | const char * | fileName, |
const char * | str | ||
) |
Creates, opens, and overwrites the given file with name fileName
with the given non NULL, null terminated data string str
, and returns ML_RESULT_OK on success or an MLErrorCode describing the problem on failure.
The file will be closed after write operation. Supports UTF-8 encoded unicode file names.
ML_UTILS_EXPORT char* MLGetNonExistingRandomFileName | ( | const char * | prefix | ) |
If prefix is NULL or empty then a file name is returned which does not exist in the temp file directory determined with MLGetTempPath().
Otherwise prefix is used as path to the directory in which the filename shall be generated. If prefix is no path then the file name is prefixed with prefix and located in the current directory. The file name is suffixed with a random number such that a file name results which is unique in the directory. Note: The file name generation with this function easily can lead to a racing condition where other processes or threads can create identical file names in parallel. It is left to the caller to solve this problem. The returned value must be freed with MLFree() or Memory::free(). Supports UTF-8 encoded unicode prefix strings. If NULL is returned then errno describes the error.
ML_UTILS_EXPORT char* MLGetNonExistingRandomFileNameWithPostFix | ( | const char * | prefix, |
const char * | postFix | ||
) |
Same as MLGetNonExistingRandomFileName() with the difference that the resulting unique file name also has a suffix given by postFix.
If postFix is NULL or empty then this routine behaves identically to MLGetNonExistingRandomFileName().
ML_UTILS_EXPORT char* MLGetTempPath | ( | ) |
Returns the path to the temporary directory of the current user or NULL on failure.
The returned value must be freed with MLFree() or Memory::free().
ML_UTILS_EXPORT int MLopen | ( | const char * | fileName, |
int | openFlags, | ||
int | pMode | ||
) |
Opens the file with name fileName
with the given openFlags
, returns a file descriptor or -1 on error.
This method is equivalent to the stdio open implementation, see the open documentation for available open flags. In contrast to the original open method, this method accepts an UTF-8 encoded string and uses the unicode WIN32 API on Windows. On Unix systems, this method maps to open directly. pMode
specifies the access permissions of the opened file, see ML_S_IREAD and ML_S_IWRITE. If < 0 is returned then errno describes the error.
ML_UTILS_EXPORT MLErrorCode MLremove | ( | const char * | fileName | ) |
Deletes file with name fileName
.
fileName | valid and null-terminated UTF8 name of the existing file. |
ML_UTILS_EXPORT MLErrorCode MLrename | ( | const char * | oldName, |
const char * | newName | ||
) |
Renames a file with name oldName
to newName
.
oldName | valid and null-terminated UTF8 old name of the existing file. |
newName | valid and null-terminated UTF8 new file name. |
ML_UTILS_EXPORT void MLTranslateErrorCode | ( | MLErrorCode * | err | ) |
Error code translation from global fileIO error code given by errno to ML error code *err
if err is passed as non NULL; if err is passed as NULL then the call is ignored.
This method can be used to translate the current errno state to an appropriate ML error code for those functions which do not return an explicit ML error code. If errno cannot be converted appropriately or no adequate MLErrorCode exists then ML_FILE_IO_ERROR is returned.