libgpac
Documentation of the core library of GPAC
File System

File System tools. More...

+ Collaboration diagram for File System:

Data Structures

struct  GF_FileEnumInfo
 FileEnum info object. More...
 

Typedefs

typedef Bool(* gf_enum_dir_item) (void *cbck, char *item_name, char *item_path, GF_FileEnumInfo *file_info)
 Directory Enumeration Callback. More...
 
typedef struct __gf_file_io GF_FileIO
 
typedef GF_FileIO *(* gfio_open_proc) (GF_FileIO *fileio_ref, const char *url, const char *mode, GF_Err *out_error)
 
typedef GF_Err(* gfio_seek_proc) (GF_FileIO *fileio, u64 offset, s32 whence)
 
typedef u32(* gfio_read_proc) (GF_FileIO *fileio, u8 *buffer, u32 bytes)
 
typedef u32(* gfio_write_proc) (GF_FileIO *fileio, u8 *buffer, u32 bytes)
 
typedef s64(* gfio_tell_proc) (GF_FileIO *fileio)
 
typedef Bool(* gfio_eof_proc) (GF_FileIO *fileio)
 
typedef int(* gfio_printf_proc) (GF_FileIO *fileio, const char *format, va_list args)
 

Functions

GF_Err gf_file_load_data (const char *file_name, u8 **out_data, u32 *out_size)
 reads a file into memory More...
 
GF_Err gf_file_load_data_filep (FILE *file, u8 **out_data, u32 *out_size)
 reads a file into memory More...
 
GF_Err gf_rmdir (const char *DirPathName)
 Delete Directory. More...
 
GF_Err gf_mkdir (const char *DirPathName)
 Create Directory. More...
 
Bool gf_dir_exists (const char *DirPathName)
 Check Directory Exists. More...
 
GF_Err gf_dir_cleanup (const char *DirPathName)
 Create Directory. More...
 
const char * gf_get_default_cache_directory ()
 
u32 gf_file_handles_count ()
 
size_t gf_fwrite (const void *ptr, size_t nb_bytes, FILE *stream)
 file writing helper More...
 
size_t gf_fread (void *ptr, size_t nbytes, FILE *stream)
 file reading helper More...
 
char * gf_fgets (char *buf, size_t size, FILE *stream)
 file reading helper More...
 
int gf_fgetc (FILE *stream)
 file reading helper More...
 
int gf_fputc (int val, FILE *stream)
 file writing helper More...
 
int gf_fputs (const char *buf, FILE *stream)
 file writing helper More...
 
int gf_fprintf (FILE *stream, const char *format,...)
 file writing helper More...
 
int gf_vfprintf (FILE *stream, const char *format, va_list args)
 file writing helper More...
 
int gf_fflush (FILE *stream)
 file flush helper More...
 
int gf_feof (FILE *stream)
 end of file helper More...
 
int gf_ferror (FILE *stream)
 file error helper More...
 
u64 gf_fsize (FILE *fp)
 file size helper More...
 
Bool gf_fileio_check (FILE *fp)
 file IO helper More...
 
FILE * gf_fopen (const char *file_name, const char *mode)
 file opening More...
 
FILE * gf_fopen_ex (const char *file_name, const char *parent_url, const char *mode, Bool no_warn)
 file opening More...
 
s32 gf_fclose (FILE *file)
 file closing More...
 
u64 gf_ftell (FILE *f)
 large file position query More...
 
s32 gf_fseek (FILE *f, s64 pos, s32 whence)
 large file seeking More...
 
char * gf_file_basename (const char *filename)
 
char * gf_file_ext_start (const char *filename)
 
GF_Err gf_enum_directory (const char *dir, Bool enum_directory, gf_enum_dir_item enum_dir, void *cbck, const char *filter)
 Directory enumeration. More...
 
GF_Err gf_file_delete (const char *fileName)
 File Deletion. More...
 
GF_Err gf_file_move (const char *fileName, const char *newFileName)
 File Move. More...
 
FILE * gf_file_temp (char **const fileName)
 Temporary File Creation. More...
 
u64 gf_file_modification_time (const char *filename)
 File Modification Time. More...
 
Bool gf_file_exists (const char *fileName)
 File existence check. More...
 
Bool gf_file_exists_ex (const char *file_name, const char *par_name)
 File existence check. More...
 
GF_FileIOgf_fileio_new (char *url, void *udta, gfio_open_proc open, gfio_seek_proc seek, gfio_read_proc read, gfio_write_proc write, gfio_tell_proc tell, gfio_eof_proc eof, gfio_printf_proc printf)
 
void gf_fileio_del (GF_FileIO *fileio)
 
void * gf_fileio_get_udta (GF_FileIO *fileio)
 
const char * gf_fileio_url (GF_FileIO *fileio)
 
void gf_fileio_set_stats (GF_FileIO *fileio, u64 bytes_done, u64 file_size, Bool cache_complete, u32 bytes_per_sec)
 
Bool gf_fileio_get_stats (GF_FileIO *fileio, u64 *bytes_done, u64 *file_size, Bool *cache_complete, u32 *bytes_per_sec)
 
GF_FileIOgf_fileio_open_url (GF_FileIO *fileio, const char *url, const char *mode, GF_Err *out_err)
 
GF_Err gf_fileio_tag_main_thread (GF_FileIO *fileio)
 
Bool gf_fileio_is_main_thread (const char *url)
 
GF_FileIOgf_fileio_from_url (const char *url)
 
const char * gf_fileio_factory (GF_FileIO *fileio, const char *new_res_url)
 
const char * gf_fileio_translate_url (const char *url)
 
const char * gf_fileio_resource_url (GF_FileIO *fileio)
 
Bool gf_fileio_read_mode (GF_FileIO *fileio)
 
Bool gf_fileio_write_mode (GF_FileIO *fileio)
 

Detailed Description

This section documents file system tools used in GPAC.

FILE objects are wrapped in GPAC for direct memory or callback operations. All file functions not using stderr/stdout must use the gf_ prefixed versions, eg:

//bad design, will fail when using wrapped memory IOs
FILE *t = fopen(url, "rb");
fputs(t, mystring);
fclose(t);
//good design, will work fine when using wrapped memory IOs
FILE *t = gf_fopen(url, "rb");
gf_fputs(t, mystring);

Data Structure Documentation

◆ GF_FileEnumInfo

struct GF_FileEnumInfo

The FileEnumInfo object is used to get file attributes upon enumeration of a directory.

Data Fields
Bool hidden

File is marked as hidden

Bool directory

File is a directory

Bool drive

File is a drive mountpoint

Bool system

File is a system file

u64 size

File size in bytes

u64 last_modified

File last modif time in UTC seconds

Typedef Documentation

◆ gf_enum_dir_item

typedef Bool(* gf_enum_dir_item) (void *cbck, char *item_name, char *item_path, GF_FileEnumInfo *file_info)

The gf_enum_dir_item type is the type for the callback of the gf_enum_directory function

Parameters
cbckOpaque user data.
item_nameFile or directory name.
item_pathFile or directory full path and name from filesystem root.
file_infoinformation for the file or directory.
Returns
1 to abort enumeration, 0 to continue enumeration.

◆ GF_FileIO

typedef struct __gf_file_io GF_FileIO

File IO wrapper object

◆ gfio_open_proc

typedef GF_FileIO*(* gfio_open_proc) (GF_FileIO *fileio_ref, const char *url, const char *mode, GF_Err *out_error)

open proc for memory file IO

Parameters
fileio_refreference file_io. A file can be opened multiple times for the same reference, your code must handle this
urltarget file name.
modeopening mode of file, same as fopen mode. The following additional modes are defined:
  • "ref": indicates this FileIO object is used by some part of the code and must not be destroyed upon closing of the file. Associated URL is null
  • "unref": indicates this FileIO object is not used by some part of the code and may be destroyed if no more references to this object are set. Associated URL is null
  • "url": indicates to create a new FileIO object for the given URL without opening the output file. The resulting FileIO object must be garbage collected by the app in case its is never used by the callers
  • "probe": checks if the file exists, but no need to open the file. The function should return NULL in this case. If file does not exist, set out_error to GF_URL_ERROR
  • "close": indicates the fileIO object is being closed (fclose)
out_errormust be set to error code if any (never NULL)
Returns
the opened GF_FileIO if success, or NULL otherwise

◆ gfio_seek_proc

typedef GF_Err(* gfio_seek_proc) (GF_FileIO *fileio, u64 offset, s32 whence)

seek proc for memory file IO

Parameters
fileiotarget file IO object
offsetoffset in file
whenceposition from offset, same as fseek
Returns
error if any

◆ gfio_read_proc

typedef u32(* gfio_read_proc) (GF_FileIO *fileio, u8 *buffer, u32 bytes)

read proc for memory file IO

Parameters
fileiotarget file IO object
bufferbuffer to read.
bytesnumber of bytes to read.
Returns
number of bytes read, 0 if error.

◆ gfio_write_proc

typedef u32(* gfio_write_proc) (GF_FileIO *fileio, u8 *buffer, u32 bytes)

write proc for memory file IO

Parameters
fileiotarget file IO object
bufferbuffer to write.
bytesnumber of bytes to write. If 0, acts as fflush
Returns
number of bytes write, 0 if error

◆ gfio_tell_proc

typedef s64(* gfio_tell_proc) (GF_FileIO *fileio)

positon tell proc for memory file IO

Parameters
fileiotarget file IO object
Returns
position in bytes from file start

◆ gfio_eof_proc

typedef Bool(* gfio_eof_proc) (GF_FileIO *fileio)

end of file proc for memory file IO

Parameters
fileiotarget file IO object
Returns
GF_TRUE if end of file, GF_FALSE otherwise

◆ gfio_printf_proc

typedef int(* gfio_printf_proc) (GF_FileIO *fileio, const char *format, va_list args)

printf proc for memory file IO

Parameters
fileiotarget file IO object
formatformat string to use
argsvariable argument list for printf, already initialized (va_start called)
Returns
same as vfprint

Function Documentation

◆ gf_file_load_data()

GF_Err gf_file_load_data ( const char *  file_name,
u8 **  out_data,
u32 out_size 
)

Reads a local file into memory, in binary open mode.

Parameters
file_namepath on disk of the file to read
out_datapointer to allocted address, to be freed by caller
out_sizepointer to allocted size
Returns
error code if any

◆ gf_file_load_data_filep()

GF_Err gf_file_load_data_filep ( FILE *  file,
u8 **  out_data,
u32 out_size 
)

Reads a local file into memory, in binary open mode.

Parameters
filestream object to read (no seek is performed)
out_datapointer to allocted address, to be freed by caller
out_sizepointer to allocted size
Returns
error code if any

◆ gf_rmdir()

GF_Err gf_rmdir ( const char *  DirPathName)

Delete a dir within the full path.

Parameters
DirPathNamethe file path name.
Returns
error if any

◆ gf_mkdir()

GF_Err gf_mkdir ( const char *  DirPathName)

Create a directory within the full path.

Parameters
DirPathNamethe dir path name.
Returns
error if any

◆ gf_dir_exists()

Bool gf_dir_exists ( const char *  DirPathName)

Create a directory within the full path.

Parameters
DirPathNamethe dir path name.
Returns
GF_TRUE if directory exists

◆ gf_dir_cleanup()

GF_Err gf_dir_cleanup ( const char *  DirPathName)

Cleanup a directory within the full path, removing all the files and the directories.

Parameters
DirPathNamethe dir path name.
Returns
error if any

◆ gf_get_default_cache_directory()

const char* gf_get_default_cache_directory ( )

Gets a newly allocated string containing the default cache directory. It is the responsibility of the caller to free the string.

Returns
a fully qualified path to the default cache directory

◆ gf_file_handles_count()

u32 gf_file_handles_count ( )

Gets the number of open file handles (gf_fopen/gf_fclose only).

Returns
number of open file handles

◆ gf_fwrite()

size_t gf_fwrite ( const void *  ptr,
size_t  nb_bytes,
FILE *  stream 
)

Wrapper to properly handle calls to fwrite(), ensuring proper error handling is invoked when it fails.

Parameters
ptrdata buffer to write
nb_bytesnumber of bytes to write
streamstream object
Returns
number of bytes to written

◆ gf_fread()

size_t gf_fread ( void *  ptr,
size_t  nbytes,
FILE *  stream 
)

Wrapper to properly handle calls to fread()

Parameters
ptrdata buffer to read
nbytesnumber of bytes to read
streamstream object
Returns
number of bytes read

◆ gf_fgets()

char* gf_fgets ( char *  buf,
size_t  size,
FILE *  stream 
)

Wrapper to properly handle calls to fgets()

Parameters
bufsame as fgets
sizesame as fgets
streamsame as fgets
Returns
same as fgets

◆ gf_fgetc()

int gf_fgetc ( FILE *  stream)

Wrapper to properly handle calls to fgetc()

Parameters
streamsame as fgetc
Returns
same as fgetc

◆ gf_fputc()

int gf_fputc ( int  val,
FILE *  stream 
)

Wrapper to properly handle calls to fputc()

Parameters
valsame as fputc
streamsame as fputc
Returns
same as fputc

◆ gf_fputs()

int gf_fputs ( const char *  buf,
FILE *  stream 
)

Wrapper to properly handle calls to fputs()

Parameters
bufsame as fputs
streamsame as fputs
Returns
same as fputs

◆ gf_fprintf()

int gf_fprintf ( FILE *  stream,
const char *  format,
  ... 
)

Wrapper to properly handle calls to fprintf()

Parameters
streamsame as fprintf
formatsame as fprintf
Returns
same as fprintf

◆ gf_vfprintf()

int gf_vfprintf ( FILE *  stream,
const char *  format,
va_list  args 
)

Wrapper to properly handle calls to vfprintf()

Parameters
streamsame as vfprintf
formatsame as vfprintf
argssame as vfprintf
Returns
same as fprintf

◆ gf_fflush()

int gf_fflush ( FILE *  stream)

Wrapper to properly handle calls to fflush()

Parameters
streamsame as fflush
Returns
same as fflush

◆ gf_feof()

int gf_feof ( FILE *  stream)

Wrapper to properly handle calls to feof()

Parameters
streamsame as feof
Returns
same as feof

◆ gf_ferror()

int gf_ferror ( FILE *  stream)

Wrapper to properly handle calls to ferror()

Parameters
streamsame as ferror
Returns
same as ferror

◆ gf_fsize()

u64 gf_fsize ( FILE *  fp)

Gets the file size given a FILE object. The FILE object position will be reset to 0 after this call

Parameters
fpFILE object to check
Returns
file size in bytes

◆ gf_fileio_check()

Bool gf_fileio_check ( FILE *  fp)

Checks if the given FILE object is a native FILE or a GF_FileIO wrapper.

Parameters
fpFILE object to check
Returns
GF_TRUE if the FILE object is a wrapper to GF_FileIO

◆ gf_fopen()

FILE* gf_fopen ( const char *  file_name,
const char *  mode 
)

Opens a file, potentially bigger than 4GB. if filename identifies a blob (gmem://), the blob will be opened

Parameters
file_namesame as fopen
modesame as fopen
Returns
stream handle of the file object

◆ gf_fopen_ex()

FILE* gf_fopen_ex ( const char *  file_name,
const char *  parent_url,
const char *  mode,
Bool  no_warn 
)

Opens a file, potentially using file IO if the parent URL is a File IO wrapper

Parameters
file_namesame as fopen
parent_urlURL of parent file. If not a file io wrapper (gfio://), the function is equivalent to gf_fopen
modesame as fopen
no_warnif GF_TRUE, do not throw log message if failure
Returns
stream handle of the file object
Note
You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio.
Returns
stream habdle of the file or file IO object

◆ gf_fclose()

s32 gf_fclose ( FILE *  file)

Closes a file

Note
You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio.
Parameters
filefile to close
Returns
same as flcose

◆ gf_ftell()

u64 gf_ftell ( FILE *  f)

Queries the current read/write position in a large file

Parameters
fSame semantics as gf_ftell
Returns
position in the file
Note
You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio.

◆ gf_fseek()

s32 gf_fseek ( FILE *  f,
s64  pos,
s32  whence 
)

Seeks the current read/write position in a large file

Parameters
fSame semantics as fseek
posSame semantics as fseek
whenceSame semantics as fseek
Returns
0 if success, -1 if error
Note
You only need to call this function if you're suspecting the file to be a large one (usually only media files), otherwise use regular stdio.

◆ gf_file_basename()

char* gf_file_basename ( const char *  filename)

gets basename from filename/path

Parameters
filenamePath of the file, can be an absolute path
Returns
a pointer to the start of a filepath basename or null

◆ gf_file_ext_start()

char* gf_file_ext_start ( const char *  filename)

gets extension from filename

Parameters
filenamePath of the file, can be an absolute path
Returns
a pointer to the start of a filepath extension or null

◆ gf_enum_directory()

GF_Err gf_enum_directory ( const char *  dir,
Bool  enum_directory,
gf_enum_dir_item  enum_dir,
void *  cbck,
const char *  filter 
)

Enumerates a directory content. Feedback is provided by the enum_dir_item function

Parameters
dirDirectory to enumerate
enum_directoryIf set, only directories will be enumerated, otherwise only files are.
enum_dirgf_enum_dir_item callback function for enumeration.
cbckOpaque user data passed to callback function.
filteroptional filter for file extensions. If a file extension without the dot '.' character is not found in the filter the file will be skipped.
Returns
error if any

◆ gf_file_delete()

GF_Err gf_file_delete ( const char *  fileName)

Deletes a file from the disk.

Parameters
fileNameabsolute name of the file or name relative to the current working directory.
Returns
error if any

◆ gf_file_move()

GF_Err gf_file_move ( const char *  fileName,
const char *  newFileName 
)

Moves or renames a file or directory.

Parameters
fileNameabsolute path of the file / directory to move or rename
newFileNameabsolute new path/name of the file / directory
Returns
error if any

◆ gf_file_temp()

FILE* gf_file_temp ( char **const  fileName)

Creates a new temporary file in binary mode

Parameters
fileNameif not NULL, strdup() of the temporary filename when created by GPAC (NULL otherwise as the system automatically removes its own tmp files)
Returns
stream handle to the new file ressoucre

◆ gf_file_modification_time()

u64 gf_file_modification_time ( const char *  filename)

Gets the UTC modification time of the given file in microseconds

Parameters
filenamefile to check
Returns
modification time of the file

◆ gf_file_exists()

Bool gf_file_exists ( const char *  fileName)

Checks if file with given name exists

Parameters
fileNamepath of the file to check
Returns
GF_TRUE if file exists

◆ gf_file_exists_ex()

Bool gf_file_exists_ex ( const char *  file_name,
const char *  par_name 
)

Checks if file with given name exists, for regular files or File IO wrapper

Parameters
file_namepath of the file to check
par_namename of the parent file
Returns
GF_TRUE if file exists

◆ gf_fileio_new()

GF_FileIO* gf_fileio_new ( char *  url,
void *  udta,
gfio_open_proc  open,
gfio_seek_proc  seek,
gfio_read_proc  read,
gfio_write_proc  write,
gfio_tell_proc  tell,
gfio_eof_proc  eof,
gfio_printf_proc  printf 
)

Creates a new file IO object

There is no guarantee that the corresponding resource will be opened by the framework, it is therefore the caller responsability to track objects created by gf_fileio_new or as a response to open with mode "url".

Parameters
urlthe original URL this file IO object wraps
udtaopaque data for caller
openopen proc for IO, must not be NULL
seekseek proc for IO, must not be NULL
readread proc for IO - if NULL the file is considered write only
writewrite proc for IO - if NULL the file is considered read only
telltell proc for IO, must not be NULL
eofeof proc for IO, must not be NULL
printfprintf proc for IO, may be NULL
Returns
the newly created file IO wrapper

◆ gf_fileio_del()

void gf_fileio_del ( GF_FileIO fileio)

Deletes a new fileIO object

Parameters
fileiothe File IO object to delete

◆ gf_fileio_get_udta()

void* gf_fileio_get_udta ( GF_FileIO fileio)

Gets associated user data of a fileIO object

Parameters
fileiotarget file IO object
Returns
the associated user data

◆ gf_fileio_url()

const char* gf_fileio_url ( GF_FileIO fileio)

Gets URL of a fileIO object. The url uses the protocol scheme "gfio://"

Parameters
fileiotarget file IO object
Returns
the file IO url to use

◆ gf_fileio_set_stats()

void gf_fileio_set_stats ( GF_FileIO fileio,
u64  bytes_done,
u64  file_size,
Bool  cache_complete,
u32  bytes_per_sec 
)

Sets statistics on a fileIO object.

Parameters
fileiotarget file IO object
bytes_donenumber of bytes fetched for this file
file_sizetotal size of this file, 0 if unknown
cache_completeif GF_TRUE, means the file is completely available
bytes_per_secreception bytes per second, 0 if unknown

◆ gf_fileio_get_stats()

Bool gf_fileio_get_stats ( GF_FileIO fileio,
u64 bytes_done,
u64 file_size,
Bool cache_complete,
u32 bytes_per_sec 
)

Gets statistics on a fileIO object.

Parameters
fileiotarget file IO object
bytes_donenumber of bytes fetched for this file (may be NULL)
file_sizetotal size of this file, 0 if unknown (may be NULL)
cache_completeif GF_TRUE, means the file is completely available (may be NULL)
bytes_per_secreception bytes per second, 0 if unknown (may be NULL)
Returns
GF_TRUE if success, GF_FALSE otherwise

◆ gf_fileio_open_url()

GF_FileIO* gf_fileio_open_url ( GF_FileIO fileio,
const char *  url,
const char *  mode,
GF_Err out_err 
)

Checks if a FileIO object can write

Parameters
fileiotarget file IO object
urlthe original resource URL to open
modethe desired open mode
out_errset to error code if any, must not be NULL
Returns
file IO object for this resource

◆ gf_fileio_tag_main_thread()

GF_Err gf_fileio_tag_main_thread ( GF_FileIO fileio)

Tags a FileIO object to be accessed from main thread only

Parameters
fileiotarget file IO object
Returns
error if any

◆ gf_fileio_is_main_thread()

Bool gf_fileio_is_main_thread ( const char *  url)

Check if a FileIO object is to be accessed from main thread only

Note
Filters accessing FileIO objects by other means that a filter option must manually tag themselves as main thread, potentially rescheduling a configure call to next process. Not doing so can result in binding crashes in multi-threaded mode.
Parameters
urltarget url
Returns
GF_TRUE if object is tagged for main thread, GF_FALSE otherwise

◆ gf_fileio_from_url()

GF_FileIO* gf_fileio_from_url ( const char *  url)

Gets GF_FileIO object from its URL The url uses the protocol scheme "gfio://"

Parameters
urlthe URL of the File IO object
Returns
the file IO object

◆ gf_fileio_factory()

const char* gf_fileio_factory ( GF_FileIO fileio,
const char *  new_res_url 
)

Constructs a new GF_FileIO object from a URL The url can be absolute or relative to the parent GF_FileIO. This is typcically needed by filters (dash input, dasher, NHML/NHNT writers...) generating or consuming additional files associated with the main file IO object but being written or read by other filters. The function will not open the associated resource, only create the file IO wrapper for later usage If you need to create a new fileIO to be opened immediately, use gf_fopen_ex.

Parameters
fileioparent file IO object
new_res_urlthe original URL of the new object to create
Returns
the url (gfio://) of the created file IO object, NULL otherwise

◆ gf_fileio_translate_url()

const char* gf_fileio_translate_url ( const char *  url)

Translates a FileIO object URL into the original resource URL

Parameters
urlthe URL of the File IO object
Returns
the original resource URL associated with the file IO object

◆ gf_fileio_resource_url()

const char* gf_fileio_resource_url ( GF_FileIO fileio)

Gets a FileIO original resource URL

Parameters
fileiotarget file IO object
Returns
the original resource URL associated with the file IO object

◆ gf_fileio_read_mode()

Bool gf_fileio_read_mode ( GF_FileIO fileio)

Checks if a FileIO object can read

Parameters
fileiotarget file IO object
Returns
GF_TRUE if read is enabled on this object

◆ gf_fileio_write_mode()

Bool gf_fileio_write_mode ( GF_FileIO fileio)

Checks if a FileIO object can write

Parameters
fileiotarget file IO object
Returns
GF_TRUE if write is enabled on this object
gf_fputs
int gf_fputs(const char *buf, FILE *stream)
file writing helper
gf_fclose
s32 gf_fclose(FILE *file)
file closing
gf_fopen
FILE * gf_fopen(const char *file_name, const char *mode)
file opening