ML Reference
MeVis/Foundation/Sources/MLUtilities/mlFileSystem.h File 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 MLuint8MLFileReadAllAsBinary (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 MLuint8MLFileReadChunkAsBinary (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 MLuint8MLFileReadChunkAsBinaryFromDesc (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.

Detailed Description

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:

  • 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.
Author:
Wolf Spindler, Florian Link
Date:
09/2004

Definition in file mlFileSystem.h.


Define Documentation

#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.


Function Documentation

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.

Parameters:
pathvalid and null-terminated UTF8 path of the directory.
Returns:
ML_RESULT_OK on success and on failure an MLErrorCode describing the problem
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:
filemust be a valid pointer for an open file.
Returns:
ML_RESULT_OK on success and on failure an MLErrorCode describing the problem
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.

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.

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.

Parameters:
fileNamevalid and null-terminated UTF8 name of the existing file.
Returns:
ML_RESULT_OK on success and on failure an MLErrorCode describing the problem
ML_UTILS_EXPORT MLErrorCode MLrename ( const char *  oldName,
const char *  newName 
)

Renames a file with name oldName to newName.

Parameters:
oldNamevalid and null-terminated UTF8 old name of the existing file.
newNamevalid and null-terminated UTF8 new file name.
Returns:
ML_RESULT_OK on success and on failure an MLErrorCode describing the problem
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.