The qDecoder Project

qFile.c File Reference

File Handling API. More...


Defines

#define MAX_EXTENSION_LENGTH   (8)

Functions

bool qFileLock (int fd)
 Lock file.
bool qFileUnlock (int fd)
 Unlock file which is locked by qFileLock().
bool qFileExist (const char *filepath)
 Check file existence.
void * qFileLoad (const char *filepath, size_t *nbytes)
 Load file into memory.
void * qFileRead (FILE *fp, size_t *nbytes)
 Load file stream which has unknown size into memory.
ssize_t qFileSave (const char *filepath, const void *buf, size_t size, bool append)
 Save data into file.
char * qFileReadLine (FILE *fp)
 Read one line from file.
bool qFileMkdir (const char *dirpath, mode_t mode, bool recursive)
 Attempts to create a directory recursively.
bool qFileCheckPath (const char *path)
 Check path string contains invalid characters.
char * qFileGetName (const char *filepath)
 Get filename from filepath.
char * qFileGetDir (const char *filepath)
 Get directory suffix from filepath.
char * qFileGetExt (const char *filepath)
 Get extension from filepath.
off_t qFileGetSize (const char *filepath)
 Get file size.
char * qFileCorrectPath (char *path)
 Correct path string.
char * qFileGetAbsPath (char *buf, size_t bufsize, const char *path)
 Make full absolute system path string.

Detailed Description

File Handling API.

Function Documentation

bool qFileLock ( int  fd  ) 

Lock file.

Parameters:
fd file descriptor
Returns:
true if successful, otherwise returns false.
   // for file descriptor
   int fd = open(...);
   if(qFileLock(fd) == true) {
     (...atomic file access...)
     qFileUnlock(fd);
   }

   // for FILE stream object
   FILE *fp = fopen(...);
   int fd = fileno(fp);
   if(qFileLock(fd) == true) {
     (...atomic file access...)
     qFileUnlock(fd);
   }

bool qFileUnlock ( int  fd  ) 

Unlock file which is locked by qFileLock().

Parameters:
fd file descriptor
Returns:
true if successful, otherwise returns false.

bool qFileExist ( const char *  filepath  ) 

Check file existence.

Parameters:
filepath file or directory path
Returns:
true if exists, otherwise returns false.

void* qFileLoad ( const char *  filepath,
size_t *  nbytes 
)

Load file into memory.

Parameters:
filepath file path
nbytes has two purpost, one is to set how many bytes are readed. the other is actual the number loaded bytes will be stored. nbytes must be point 0 or NULL to read entire file.
Returns:
allocated memory pointer if successful, otherwise returns NULL.
   // loading text file
   char *text = (char *)qFileLoad("/tmp/text.txt", NULL);

   // loading binary file
   int binlen = 0;
   char *bin = (char *)qFileLoad("/tmp/binary.bin", &binlen);

   // loading partial
   int binlen = 10;
   char *bin = (char *)qFileLoad("/tmp/binary.bin", &binlen);

Note:
This method actually allocates memory more than 1 bytes than filesize then append NULL character at the end. For example, when the file size is 10 bytes long, 10+1 bytes will allocated and the last byte is always NULL character. So you can load text file and use without appending NULL character. By the way, *size still will be returned the actual file size of 10.

void* qFileRead ( FILE *  fp,
size_t *  nbytes 
)

Load file stream which has unknown size into memory.

Parameters:
fp FILE pointer
nbytes has two purpost, one is to set how many bytes are readed. the other is actual the number loaded bytes will be stored. nbytes must be point 0 or NULL to read end of stream.
Returns:
allocated memory pointer if successful, otherwise returns NULL.
Note:
This method append NULL character at the end of stream. but nbytes only counts actual readed bytes.

ssize_t qFileSave ( const char *  filepath,
const void *  buf,
size_t  size,
bool  append 
)

Save data into file.

Parameters:
filepath file path
buf data
size the number of bytes to save
append false for new(if exists truncate), true for appending
Returns:
the number of bytes written if successful, otherwise returns -1.
   // save text
   char *text = "hello";
   qFileSave("/tmp/text.txt", (void*)text, strlen(text), false);

   // save binary
   int integer1 = 75;
   qFileSave("/tmp/integer.bin, (void*)&integer, sizeof(int));

char* qFileReadLine ( FILE *  fp  ) 

Read one line from file.

Parameters:
fp FILE pointer
Returns:
allocated memory pointer if successful, otherwise returns NULL.
Note:
Basically it's same as fgets() but can read line without length limitation.

bool qFileMkdir ( const char *  dirpath,
mode_t  mode,
bool  recursive 
)

Attempts to create a directory recursively.

Parameters:
dirpath directory path
mode permissions to use
recursive whether or not to create parent directories automatically
Returns:
true if successful, otherwise returns false.

bool qFileCheckPath ( const char *  path  ) 

Check path string contains invalid characters.

Parameters:
path path string
Returns:
true if ok, otherwise returns false.

char* qFileGetName ( const char *  filepath  ) 

Get filename from filepath.

Parameters:
filepath file or directory path
Returns:
malloced filename string

char* qFileGetDir ( const char *  filepath  ) 

Get directory suffix from filepath.

Parameters:
filepath file or directory path
Returns:
malloced filepath string

char* qFileGetExt ( const char *  filepath  ) 

Get extension from filepath.

Parameters:
filepath file or directory path
Returns:
malloced extension string which is converted to lower case.

off_t qFileGetSize ( const char *  filepath  ) 

Get file size.

Parameters:
filepath file or directory path
Returns:
the file size if exists, otherwise returns -1.

char* qFileCorrectPath ( char *  path  ) 

Correct path string.

Parameters:
path path string
Returns:
path string pointer
Note:
This modify path argument itself.
   "/hello//my/../world" => "/hello/world"
   "././././hello/./world" => "./hello/world"
   "/../hello//world" => "/hello/world"

char* qFileGetAbsPath ( char *  buf,
size_t  bufsize,
const char *  path 
)

Make full absolute system path string.

Parameters:
buf buffer string pointer
bufsize buffer size
path path string
Returns:
buffer pointer if successful, otherwise returns NULL.
   char buf[PATH_MAX];
   chdir("/usr/local");
   qFileGetAbsPathFullPathGetAbs(buf, sizeof(buf), ".");    // returns "/usr/local"
   qFileGetAbsPathFullPathGetAbs(buf, sizeof(buf), "..");   // returns "/usr"
   qFileGetAbsPathFullPathGetAbs(buf, sizeof(buf), "etc");  // returns "/usr/local/etc"
   qFileGetAbsPathFullPathGetAbs(buf, sizeof(buf), "/etc"); // returns "/etc"

[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]