libUnihan  0.5.3
Macros | Typedefs | Enumerations | Functions
file_functions.h File Reference

File functions. More...

#include <string.h>
#include <stdbool.h>
#include <limits.h>
#include <glib.h>
#include "str_functions.h"

Go to the source code of this file.

Macros

#define DIRECTORY_SEPARATOR   '/'
 DIRECTORY_SEPARATOR is the separator for splits the directories in paths. More...
 
#define PATH_SEPARATOR   ':'
 PATH_SEPARATOR is the separator for splits the paths in configuration files or environment variables. More...
 
File access mode

Access modes of a file or directory.

This is similar to F_OK, R_OK, W_OK, X_OK in unistd.h. However, as F_OK == 0, which is not very helpful when cooperates with other modes.

#define FILE_MODE_EXIST   1<<4
 Test for existence.
 
#define FILE_MODE_DIRECTORY   1<<3
 Test whether the 'file' is directory.
 
#define FILE_MODE_READ   1<<2
 Test for read permission.
 
#define FILE_MODE_WRITE   1<<1
 Test for write permission.
 
#define FILE_MODE_EXECUTE   1
 Test for execute permission.
 

Typedefs

typedef TaskStatus(* ChooseFilenameFunc )(gchar *filename_buf, guint filename_len, StringList *extensions, guint access_mode_mask, const gchar *prompt, gpointer option)
 Prototype of callback function for choosing a filename. More...
 

Enumerations

enum  TaskStatus { TASK_RUNNING, TASK_CANCELED, TASK_FAILED, TASK_COMPLETED }
 An enumeration of task running status. More...
 

Functions

gchar * truepath (const gchar *path, gchar *resolved_path)
 Return the canonicalized absolute pathname. More...
 
gboolean isReadable (const gchar *filename)
 Whether the file is readable. More...
 
gboolean isWritable (const gchar *filename)
 Whether the file is writable. More...
 
gboolean filename_meets_accessMode (const gchar *filename, guint access_mode_mask)
 Whether the file meets the given access mode mask. More...
 
gchar * filename_search_paths (const gchar *filename, const gchar *search_paths)
 Find a file from the search path. More...
 
gchar * filename_search_paths_mode (const gchar *filename, const gchar *search_paths, guint access_mode_mask)
 Find a file with specified access mode from the search path. More...
 
gchar * filename_choose (const gchar *filename_default, guint filename_len, StringList *extensions, guint access_mode_mask, const gchar *prompt, gpointer option, ChooseFilenameFunc callback)
 Choose a suitable filename if default one is not. More...
 

Detailed Description

This header filed define file functions.

Macro Definition Documentation

#define DIRECTORY_SEPARATOR   '/'

If WIN32 is defined, DIRECTORY_SEPARATOR is '\', otherwise '/' is used as DIRECTORY_SEPARATOR.

#define PATH_SEPARATOR   ':'

If WIN32 is defined, PATH_SEPARATOR is ';', otherwise ':' is used as PATH_SEPARATOR.

Typedef Documentation

typedef TaskStatus(* ChooseFilenameFunc)(gchar *filename_buf, guint filename_len, StringList *extensions, guint access_mode_mask, const gchar *prompt, gpointer option)

This callback function should provide an UI for user select a filename. It should return:

  • TASK_COMPLETED if a suitable file is chosen, and the chosen filename is in filename_buf.
  • TASK_CANCELED if user canceled the operation.
  • TAKS_FAILED if user selected an unsuitable file, or encounter I/O error, the selected file should be in filename_buf

The parameter filename_buf is a buffer that hold the result filename. and filename_len is the buffer size. The present content of filename_buf will be default filename.

Parameter extensions for available extension filename, assign NULL if no need to have a specific extension. Use access_modes_mask to filter the files that has suitable access mode and permission.

Value in prompt is to be show in UI, such as dialog title or textual prompt in CLI. Use option to pass other data to the callback function.

Parameters
filename_bufBuffer that holds the filename, the present content will be default filename.
filename_lenpre-selected filename. Can be NULL.
extensionsacceptable file extensions. NULL for don't care.
access_mode_maskthe required access mode mask defined in File access mode..
promptthe string to be shown in UI, usually shown as dialog title for GUI.
optionOther custom option.
Return values
TASK_COMPLETEDif a suitable file is chosen, and the chosen filename is in filename_buf.
TASK_CANCELEDif user canceled the operation.
TAKS_FAILEDif user selected an unsuitable file, or encounter I/O error, the selected file should be in filename_buf
See also
filename_meets_accessMode()
filename_choose()

Enumeration Type Documentation

enum TaskStatus

This enumeration lists the task running status. It can be used as function return values, or as concurrent process running status.

Enumerator
TASK_CANCELED 

< The task is still running, usually this for concurrent process.

TASK_FAILED 

< The task is canceled.

TASK_COMPLETED 

< The task is failed.

< The task is complete.

Function Documentation

gchar* filename_choose ( const gchar *  filename_default,
guint  filename_len,
StringList extensions,
guint  access_mode_mask,
const gchar *  prompt,
gpointer  option,
ChooseFilenameFunc  callback 
)

This function returns either a newly allocated filename string that meets the access_mode_mask, or NULL if user cancel the process.

This function firstly try the filename given by a non-NULL filename_default, if it does not meet access_mode_make, then it will keep calling callback() to open an UI for user input until:

  • user inputs a valid filename, or
  • user cancels the operation (usually by clicking "cancel" button.)

If filename_default is NULL, this function will call callback() directly for user input.

Parameters
filename_defaultThe default filename to be check, NULL or "" if no default filename.
filename_lenpre-selected filename. Can be NULL.
extensionsacceptable file extensions. NULL for don't care.
access_mode_maskthe required access mode mask defined in File access mode..
promptthe string to be shown in UI, usually shown as dialog title for GUI.
optionOther custom option.
callbacka ChooseFilenameFunc callback that open a UI for filename input.
Returns
a newly allocated filename string that meets the access_mode_mask; NULL otherwise.
See also
ChooseFilenameFunc()
filename_meets_accessMode()
gboolean filename_meets_accessMode ( const gchar *  filename,
guint  access_mode_mask 
)

This function checks whether the filename meets the requirement specified as access_mode_mask. It returns TRUE if all file access mode are meet; FALSE otherwise.

Note that if only FILE_MODE_WRITE is given to access_mode_mask, this function returns TRUE even if the file does not exist, but can be created and written. Use FILE_MODE_EXIST|FILE_MODE_WRITE the check the write permission of existing file.

Parameters
filenameThe filename to be checked.
access_mode_maskthe required access mode mask defined in File access mode..
gchar* filename_search_paths ( const gchar *  filename,
const gchar *  search_paths 
)

This function searches the given file within the search_paths. It is essentially filename_search_paths_mode(filename, search_paths, FILE_MODE_EXIST).

Parameters
filenameThe filename to be located.
search_pathsThe paths to be searched.
Returns
A newly allocated string of the exact location of the file; otherwise NULL is returned.
gchar* filename_search_paths_mode ( const gchar *  filename,
const gchar *  search_paths,
guint  access_mode_mask 
)

This function searches the file within the search_paths, after the file is found, filename_meets_accessMode() is called to check whether the file meets the required access_mode_mask.

This function return newly allocated string of the exact location of the file if the file is found and it match the requirement; otherwise NULL is returned.

Parameters
filenameThe filename to be located.
search_pathsThe paths to be searched.
access_mode_maskthe required access mode mask defined in File access mode..
Returns
A newly allocated string of the exact location of the file if the file is found and it match the requirement; otherwise NULL is returned.
See also
File access mode..
filename_meets_accessMode()
gboolean isReadable ( const gchar *  filename)
Parameters
filenameThe path name of the file.
Returns
TRUE if the file is readable; FALSE otherwise.
gboolean isWritable ( const gchar *  filename)

This function checks whether the file is writable, or can be created if filename does not exists.

Parameters
filenameThe path name of the file.
Returns
TRUE if the file is writeable ; FALSE otherwise.
gchar* truepath ( const gchar *  path,
gchar *  resolved_path 
)

It works exactly the same with realpath(3), except this function can handle the path with ~, where realpath cannot.

Parameters
pathThe path to be resolved.
resolved_pathBuffer for holding the resolved_path.
Returns
resolved path, NULL is the resolution is not sucessful.