#include "mlUtilsSystem.h"
#include <cstdio>
#include <ThirdPartyWarningsDisable.h>
#include <fcntl.h>
#include <sys/stat.h>
#include <ThirdPartyWarningsRestore.h>
#include <string>
#include <filesystem>

Macros
#define	ML_O_APPEND _O_APPEND
	Defines an API to the file system for WIN32 and Unix systems.

#define	ML_O_BINARY _O_BINARY
	Mode to open file in binary mode; note that binary 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 binary 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_IWRITE _S_IWRITE
	Platform independent file open pMode flag setting the write bit on file creation.

#define	ML_S_IREAD _S_IREAD
	Platform independent file open pMode flag setting the read bit on file creation.

#define	ML_S_IEXEC _S_IEXEC
	Platform independent file open pMode flag setting the execution bit on file creation.

#define	ML_S_IWUSR ML_S_IWRITE
	Platform independent file open pMode flag setting write permissions on file creation for the file owner; implemented as ML_S_IWRITE on windows platforms.

#define	ML_S_IRUSR ML_S_IREAD
	Platform independent file open pMode flag setting read permissions on file creation for the file owner; implemented as ML_S_IREAD on windows platforms.

#define	ML_S_IXUSR ML_S_IEXEC
	Platform independent file open pMode flag setting execute permissions on file creation for the file owner; implemented as ML_S_IEXEC on windows platforms.

#define	ML_S_IWGRP ML_S_IWRITE
	Platform independent file open pMode flag setting write permissions on file creation for group users; implemented as ML_S_IWRITE on windows platforms.

#define	ML_S_IRGRP ML_S_IREAD
	Platform independent file open pMode flag setting read permissions on file creation for group users; implemented as ML_S_IREAD on windows platforms.

#define	ML_S_IXGRP ML_S_IEXEC
	Platform independent file open pMode flag setting execute permissions on file creation for group users; implemented as ML_S_IEXEC on windows platforms.

#define	ML_S_IWOTH ML_S_IWRITE
	Platform independent file open pMode flag setting write permissions on file creation for other users; implemented as ML_S_IWRITE on windows platforms.

#define	ML_S_IROTH ML_S_IREAD
	Platform independent file open pMode flag setting read permissions on file creation for other users; implemented as ML_S_IREAD on windows platforms.

#define	ML_S_IXOTH ML_S_IEXEC
	Platform independent file open pMode flag setting execute permissions on file creation for other users; implemented as ML_S_IEXEC on windows platforms.

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
Thread-safety: These functions are reentrant.
#define	MLGetNonExistingRandomFileNameWithPostFix_Is_Available

ML_UTILS_EXPORT FILE *	MLfopen (const char fileName, const char mode)
	Opens the file with name `fileName` with the access permissions given by `mode`, and returns a FILE pointer or NULL on failure.

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)
	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 ()
	Returns the path to the temporary directory of the current user or NULL on failure.

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().

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.

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)
	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)
	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)
	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)
	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)
	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)
	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)
	Reads the complete file with a `fileName` as a string, returns NULL on error.

ML_UTILS_EXPORT MLuint8 *	MLFileReadAllAsBinary (const char *fileName)
	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)
	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)
	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)
	Reads a data segment starting at `startPosition` from the file given by `fileDescriptor` and returns NULL on error.

ML_UTILS_EXPORT MLuint	MLFileReadChunkAsBinaryFromDescToBuffer (int fileDescriptor, MLuint8 *buffer, MLuint startPosition, MLuint numBytes)
	Reads a data segment starting at `startPosition` from the file given by `fileDescriptor` and returns the number of read bytes.

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.

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	MLFileGetSizeFromFilePointer (FILE *file)
	Returns the size of the file given by the FILE pointer file A negative value is returned on any error, if file 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)
	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)
	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)
	The directory `path` is created.

ML_UTILS_EXPORT std::filesystem::path	MLGetFileSystemPath (const std::string &filename)
	Returns a file path object for the given `filename` that can be used as input for a file stream.

Macro Definition Documentation

◆ ML_O_APPEND

#define ML_O_APPEND _O_APPEND

Defines an 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.

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:

EINVAL for invalid function parameters, file descriptors or file names or out of range situations.
ENOEXEC reports a crash and/or uncontrolled program behavior. It may come along with fatal error messages posted to the ML handler or even with a program abort dependent on the configuration of ML error handler.
ENOMEM for allocation failures. Other errno values may be set by used system functions. File name lengths will be limited to at most 2^32-1 on windows 64 systems. 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 57 of file mlFileSystem.h.

◆ ML_O_BINARY

#define ML_O_BINARY _O_BINARY

Mode to open file in binary mode; note that binary and text mode are not distinguished on Unix systems.

Definition at line 60 of file mlFileSystem.h.

◆ ML_O_CREAT

#define ML_O_CREAT _O_CREAT

Mode to create a new file.

Definition at line 63 of file mlFileSystem.h.

◆ ML_O_LARGEFILE

#define ML_O_LARGEFILE 0

Mode to open a file with large file support; this exists only on Unix systems.

Definition at line 84 of file mlFileSystem.h.

◆ ML_O_RANDOM

#define ML_O_RANDOM _O_RANDOM

Mode to open/create a file optimized for random access.

Definition at line 66 of file mlFileSystem.h.

◆ ML_O_RDONLY

#define ML_O_RDONLY _O_RDONLY

Mode to open a file only for reading.

Definition at line 69 of file mlFileSystem.h.

◆ ML_O_RDWR

#define ML_O_RDWR _O_RDWR

Mode to open a file for reading and writing.

Definition at line 72 of file mlFileSystem.h.

◆ ML_O_TEXT

#define ML_O_TEXT _O_TEXT

Mode to open file in text mode; note that binary and text mode are not distinguished on Unix systems.

Definition at line 75 of file mlFileSystem.h.

◆ ML_O_TRUNC

#define ML_O_TRUNC _O_TRUNC

Mode to open a file throwing away its contents.

Definition at line 78 of file mlFileSystem.h.

◆ ML_O_WRONLY

#define ML_O_WRONLY _O_WRONLY

Mode to open a file only for writing.

Definition at line 81 of file mlFileSystem.h.

◆ ML_S_IEXEC

#define ML_S_IEXEC _S_IEXEC

Platform independent file open pMode flag setting the execution bit on file creation.

Definition at line 93 of file mlFileSystem.h.

◆ ML_S_IREAD

#define ML_S_IREAD _S_IREAD

Platform independent file open pMode flag setting the read bit on file creation.

Definition at line 90 of file mlFileSystem.h.

◆ ML_S_IRGRP

#define ML_S_IRGRP ML_S_IREAD

Platform independent file open pMode flag setting read permissions on file creation for group users; implemented as ML_S_IREAD on windows platforms.

Definition at line 113 of file mlFileSystem.h.

◆ ML_S_IROTH

#define ML_S_IROTH ML_S_IREAD

Platform independent file open pMode flag setting read permissions on file creation for other users; implemented as ML_S_IREAD on windows platforms.

Definition at line 125 of file mlFileSystem.h.

◆ ML_S_IRUSR

#define ML_S_IRUSR ML_S_IREAD

Platform independent file open pMode flag setting read permissions on file creation for the file owner; implemented as ML_S_IREAD on windows platforms.

Definition at line 101 of file mlFileSystem.h.

◆ ML_S_IWGRP

#define ML_S_IWGRP ML_S_IWRITE

Platform independent file open pMode flag setting write permissions on file creation for group users; implemented as ML_S_IWRITE on windows platforms.

Definition at line 109 of file mlFileSystem.h.

◆ ML_S_IWOTH

#define ML_S_IWOTH ML_S_IWRITE

Platform independent file open pMode flag setting write permissions on file creation for other users; implemented as ML_S_IWRITE on windows platforms.

Definition at line 121 of file mlFileSystem.h.

◆ ML_S_IWRITE

#define ML_S_IWRITE _S_IWRITE

Platform independent file open pMode flag setting the write bit on file creation.

Definition at line 87 of file mlFileSystem.h.

◆ ML_S_IWUSR

#define ML_S_IWUSR ML_S_IWRITE

Platform independent file open pMode flag setting write permissions on file creation for the file owner; implemented as ML_S_IWRITE on windows platforms.

Definition at line 97 of file mlFileSystem.h.

◆ ML_S_IXGRP

#define ML_S_IXGRP ML_S_IEXEC

Platform independent file open pMode flag setting execute permissions on file creation for group users; implemented as ML_S_IEXEC on windows platforms.

Definition at line 117 of file mlFileSystem.h.

◆ ML_S_IXOTH

#define ML_S_IXOTH ML_S_IEXEC

Platform independent file open pMode flag setting execute permissions on file creation for other users; implemented as ML_S_IEXEC on windows platforms.

Definition at line 129 of file mlFileSystem.h.

◆ ML_S_IXUSR

#define ML_S_IXUSR ML_S_IEXEC

Platform independent file open pMode flag setting execute permissions on file creation for the file owner; implemented as ML_S_IEXEC on windows platforms.

Definition at line 105 of file mlFileSystem.h.

◆ MLGetNonExistingRandomFileNameWithPostFix_Is_Available

#define MLGetNonExistingRandomFileNameWithPostFix_Is_Available

Definition at line 313 of file mlFileSystem.h.

Function Documentation

◆ MLclose()

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.

◆ MLCreateDirectory()

ML_UTILS_EXPORT MLErrorCode MLCreateDirectory ( const char * path )

The directory path is created.

Parameters

path	valid and null-terminated UTF8 path of the directory.

Returns: ML_RESULT_OK on success and on failure an MLErrorCode describing the problem

◆ MLfclose()

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.

Parameters

file	must be a valid pointer for an open file.

Returns: ML_RESULT_OK on success and on failure an MLErrorCode describing the problem

◆ MLFileAppendBinaryData()

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.

◆ MLFileAppendBinaryDataWithDescriptor()

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.

◆ MLFileAppendStringData()

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.

◆ MLFileExists()

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.

Referenced by ml::DICOMCachedIOFileHandleBase< CT >::fileExists().

◆ MLFileGetBytePos()

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.

◆ MLFileGetSizeFromDescriptor()

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.

◆ MLFileGetSizeFromFilePointer()

ML_UTILS_EXPORT MLint MLFileGetSizeFromFilePointer ( FILE * file )

Returns the size of the file given by the FILE pointer file A negative value is returned on any error, if file is invalid or on files larger than 2^63-1 bytes.

If < 0 is returned then errno describes the error.

◆ MLFileGetSizeFromName()

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.

◆ MLFileIsReadable()

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.

◆ MLFileIsWritable()

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.

◆ MLFileReadAllAsBinary()

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.

◆ MLFileReadAllAsString()

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.

◆ MLFileReadChunkAsBinary()

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.

◆ MLFileReadChunkAsBinaryFromDesc()

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.

◆ MLFileReadChunkAsBinaryFromDescToBuffer()

ML_UTILS_EXPORT MLuint MLFileReadChunkAsBinaryFromDescToBuffer	(	int	fileDescriptor,
		MLuint8 *	buffer,
		MLuint	startPosition,
		MLuint	numBytes )

Reads a data segment starting at startPosition from the file given by fileDescriptor and returns the number of read bytes.

The data is read into the buffer, so the buffer needs to be large enough to hold at least numBytes.

◆ MLFileReadChunkAsString()

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.

◆ MLFileReadChunkAsStringFromDesc()

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.

◆ MLFileSetBytePos()

ML_UTILS_EXPORT MLint MLFileSetBytePos	(	int	fileDescriptor,
		MLuint	position )

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.

◆ MLFileWriteBinaryData()

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.

◆ MLFileWriteBinaryDataAt()

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.

◆ MLFileWriteStringData()

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.

◆ MLfopen()

ML_UTILS_EXPORT FILE * MLfopen	(	const char *	fileName,
		const char *	mode )

Opens the file with name fileName with the access permissions given by mode, and returns a FILE pointer or NULL on failure.

This method is equivalent to the stdio fopen implementation, see the fopen documentation for available mode flags ("r","w","a",...). In contrast to the original fopen method, this method accepts an UTF-8 encoded string and uses the unicode WIN32 API on Windows. On Unix systems, this method maps to fopen directly. If NULL is returned then errno describes the error.

◆ MLGetFileSystemPath()

ML_UTILS_EXPORT std::filesystem::path MLGetFileSystemPath ( const std::string & filename )

Returns a file path object for the given filename that can be used as input for a file stream.

Assumes that filename is provided in UTF8 encoding.

◆ MLGetNonExistingRandomFileName()

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.

◆ MLGetNonExistingRandomFileNameWithPostFix()

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().

◆ MLGetTempPath()

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().

◆ MLopen()

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.

◆ MLremove()

ML_UTILS_EXPORT MLErrorCode MLremove ( const char * fileName )

Deletes file with name fileName.

Parameters

fileName valid and null-terminated UTF8 name of the existing file.

Returns: ML_RESULT_OK on success and on failure an MLErrorCode describing the problem

◆ MLrename()

ML_UTILS_EXPORT MLErrorCode MLrename	(	const char *	oldName,
		const char *	newName )

Renames a file with name oldName to newName.

Parameters

oldName	valid and null-terminated UTF8 old name of the existing file.
newName	valid and null-terminated UTF8 new file name.

Returns: ML_RESULT_OK on success and on failure an MLErrorCode describing the problem

◆ MLTranslateErrorCode()

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.

Macros

Functions

File access functions working with valid UTF-8 Unicode file names

Macro Definition Documentation

◆ ML_O_APPEND

◆ ML_O_BINARY

◆ ML_O_CREAT

◆ ML_O_LARGEFILE

◆ ML_O_RANDOM

◆ ML_O_RDONLY

◆ ML_O_RDWR

◆ ML_O_TEXT

◆ ML_O_TRUNC

◆ ML_O_WRONLY

◆ ML_S_IEXEC

◆ ML_S_IREAD

◆ ML_S_IRGRP

◆ ML_S_IROTH

◆ ML_S_IRUSR

◆ ML_S_IWGRP

◆ ML_S_IWOTH

◆ ML_S_IWRITE

◆ ML_S_IWUSR

◆ ML_S_IXGRP

◆ ML_S_IXOTH

◆ ML_S_IXUSR

◆ MLGetNonExistingRandomFileNameWithPostFix_Is_Available

Function Documentation

◆ MLclose()

◆ MLCreateDirectory()

◆ MLfclose()

◆ MLFileAppendBinaryData()

◆ MLFileAppendBinaryDataWithDescriptor()

◆ MLFileAppendStringData()

◆ MLFileExists()

◆ MLFileGetBytePos()

◆ MLFileGetSizeFromDescriptor()

◆ MLFileGetSizeFromFilePointer()

◆ MLFileGetSizeFromName()

◆ MLFileIsReadable()

◆ MLFileIsWritable()

◆ MLFileReadAllAsBinary()

◆ MLFileReadAllAsString()

◆ MLFileReadChunkAsBinary()

◆ MLFileReadChunkAsBinaryFromDesc()

◆ MLFileReadChunkAsBinaryFromDescToBuffer()

◆ MLFileReadChunkAsString()

◆ MLFileReadChunkAsStringFromDesc()

◆ MLFileSetBytePos()

◆ MLFileWriteBinaryData()

◆ MLFileWriteBinaryDataAt()

◆ MLFileWriteStringData()

◆ MLfopen()

◆ MLGetFileSystemPath()

◆ MLGetNonExistingRandomFileName()

◆ MLGetNonExistingRandomFileNameWithPostFix()

◆ MLGetTempPath()

◆ MLopen()

◆ MLremove()

◆ MLrename()

◆ MLTranslateErrorCode()