The qDecoder Project: C/C++ Library

- Main Page
- Data Structures
- Files

- File List
- Globals

# qFile.c File Reference

File Handling API. More...

## Defines
#define | MAX_EXTENSION_LENGTH (5)
#define | MAX_FILESEND_CHUNK_SIZE (32 * 1024)
## 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.
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.
ssize_t | qFileSend (int outfd, int infd, size_t nbytes)
| Transfer data between file descriptors.
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.
char * | qFileReadLine (FILE *fp)
| Read string.
ssize_t | qFileSave (const char *filepath, const void *buf, size_t size, bool append)
| Save to file.

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

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.

ssize_t qFileSend | ( | int | outfd,
|  | int | infd,
|  | size_t | nbytes |
| ) |  |  |

Transfer data between file descriptors.

Parameters:

  | outfd | output file descriptor
  | infd | input file descriptor
  | nbytes | the number of bytes to copy between file descriptors. 0 means transfer until end of infd.

Returns:
  the number of bytes written to outfd.

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.

char* qFileReadLine | ( | FILE * | fp | ) |

Read string.

Same as fgets but can be used for unlimited string line.

Parameters:

  | fp | FILE pointer

Returns:
  allocated memory pointer if successful, otherwise returns NULL.

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

Save to 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));

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