UCommon
ucommon::fsys Class Reference

A container for generic and o/s portable threadsafe file system functions. More...

#include <fsys.h>

Inheritance diagram for ucommon::fsys:

Public Types

enum  {
  OWNER_READONLY = 0400 , GROUP_READONLY = 0440 , PUBLIC_READONLY = 0444 , OWNER_PRIVATE = 0600 ,
  OWNER_PUBLIC = 0644 , GROUP_PRIVATE = 0660 , GROUP_PUBLIC = 0664 , EVERYONE = 0666 ,
  DIR_TEMPORARY = 01777
}
 Most of the common chmod values are predefined. More...
 
enum  access_t {
  RDONLY , WRONLY , REWRITE , RDWR = REWRITE ,
  APPEND , SHARED , EXCLUSIVE , DEVICE ,
  STREAM , RANDOM
}
 Enumerated file access modes. More...
 
typedef struct stat fileinfo_t
 
typedef long offset_t
 File offset type.
 

Public Member Functions

void assign (fd_t descriptor)
 Assign descriptor directly.
 
int close (void)
 Close a fsys resource.
 
int drop (offset_t size=0)
 Drop cached data from start of file.
 
int err (void) const
 Get last error.
 
 fsys ()
 Construct an unattached fsys descriptor.
 
 fsys (const char *path, access_t access)
 Create a fsys descriptor by opening an existing file or directory.
 
 fsys (const char *path, unsigned permission, access_t access)
 Create a fsys descriptor by creating a file.
 
 fsys (const fsys &descriptor)
 Copy (dup) an existing fsys descriptor.
 
 fsys (fd_t handle)
 Contruct fsys from raw file handle.
 
fd_t handle (void) const
 Get the native system descriptor handle of the file descriptor.
 
int info (fileinfo_t *buffer)
 Get status of open descriptor.
 
bool is_tty (void) const
 See if current file stream is a tty device.
 
void open (const char *path, access_t access)
 Open a file or directory.
 
void open (const char *path, unsigned mode, access_t access)
 Open a file descriptor directly.
 
 operator bool () const
 Test if file descriptor is open.
 
 operator fd_t () const
 Get the descriptor from the object by casting reference.
 
bool operator! () const
 Test if file descriptor is closed.
 
fd_t operator* () const
 Get the descriptor from the object by pointer reference.
 
fsysoperator*= (fd_t &descriptor)
 Replace current file descriptor with an external descriptor.
 
fsysoperator= (const fsys &descriptor)
 Assign file descriptor by duplicating another descriptor.
 
fsysoperator= (fd_t descriptor)
 Assing file descriptor from system descriptor.
 
ssize_t read (void *buffer, size_t count)
 Read data from descriptor or scan directory.
 
fd_t release (void)
 Release descriptor, do not close.
 
void reset (void)
 Reset error flag.
 
int seek (offset_t offset)
 Set the position of a file descriptor.
 
void set (fd_t descriptor)
 Set with external descriptor.
 
int sync (void)
 Commit changes to the filesystem.
 
int trunc (offset_t offset)
 Truncate file to specified length.
 
ssize_t write (const void *buffer, size_t count)
 Write data to descriptor.
 
 ~fsys ()
 Close and release a file descriptor.
 

Static Public Member Functions

static fd_t append (const char *path)
 Direct means to create or append a writable path and return descriptor.
 
static void assign (fsys &object, fd_t descriptor)
 Assign a descriptor directly.
 
static int copy (const char *source, const char *target, size_t size=1024)
 Copy a file.
 
static int erase (const char *path)
 Erase (remove) a file only.
 
static int exec (const char *path, char **argv, char **envp=NULL)
 Execute a process and get exit code.
 
static int hardlink (const char *path, const char *target)
 Create a hard link.
 
static int info (const char *path, fileinfo_t *buffer)
 Stat a file.
 
static int inherit (fd_t &descriptor, bool enable)
 Changle inheritable handle.
 
static fd_t input (const char *path)
 Direct means to open a read-only file path and return a descriptor.
 
static bool is_char (struct stat *inode)
 
static bool is_dev (struct stat *inode)
 
static bool is_device (const char *path)
 Test if path is a device path.
 
static bool is_dir (const char *path)
 Test if path is a directory.
 
static bool is_dir (struct stat *inode)
 
static bool is_disk (struct stat *inode)
 
static bool is_executable (const char *path)
 Test if path is executable.
 
static bool is_exists (const char *path)
 Test if path exists.
 
static bool is_file (const char *path)
 Test if path is a file.
 
static bool is_file (struct stat *inode)
 
static bool is_hidden (const char *path)
 Test if path is a hidden file.
 
static bool is_link (const char *path)
 Test if path is a symlink.
 
static bool is_link (struct stat *inode)
 
static bool is_readable (const char *path)
 Test if path readable.
 
static bool is_sys (struct stat *inode)
 
static bool is_tty (fd_t fd)
 See if the file handle is a tty device.
 
static bool is_writable (const char *path)
 Test if path writable.
 
static int link (const char *path, const char *target)
 Create a symbolic link.
 
static int linkinfo (const char *path, char *buffer, size_t size)
 Read a symbolic link to get it's target.
 
static int load (const char *path)
 Load a library into memory.
 
static int mode (const char *path, unsigned value)
 Change file access mode.
 
static fd_t null (void)
 Create inheritable /dev/null handle.
 
static fd_t output (const char *path)
 Direct means to create or access a writable path and return descriptor.
 
static int pipe (fd_t &input, fd_t &output, size_t size=0)
 Create pipe.
 
static int prefix (char *path, size_t size)
 Get current directory prefix (pwd).
 
static int prefix (const char *path)
 Set directory prefix (chdir).
 
static stringref_t prefix (void)
 
static void release (fd_t descriptor)
 Release a file descriptor.
 
static int remapError (void)
 
static int rename (const char *oldpath, const char *newpath)
 Rename a file.
 
static int unlink (const char *path)
 Remove a symbolic link explicitly.
 

Static Public Attributes

static const offset_t end
 Used to mark "append" in set position operations.
 

Protected Attributes

int error
 
fd_t fd
 

Detailed Description

A container for generic and o/s portable threadsafe file system functions.

These are based roughly on their posix equivilents. For libpth, the system calls are wrapped. The native file descriptor or handle may be used, but it is best to use "class fsys" instead because it can capture the errno of a file operation in a threadsafe and platform independent manner, including for mswindows targets.

Definition at line 125 of file fsys.h.

Member Typedef Documentation

◆ fileinfo_t

typedef struct stat ucommon::fsys::fileinfo_t

Definition at line 147 of file fsys.h.

◆ offset_t

File offset type.

Definition at line 176 of file fsys.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Most of the common chmod values are predefined.

Definition at line 135 of file fsys.h.

◆ access_t

Enumerated file access modes.

Definition at line 160 of file fsys.h.

Constructor & Destructor Documentation

◆ fsys() [1/3]

ucommon::fsys::fsys ( const fsys & descriptor)

Copy (dup) an existing fsys descriptor.

Parameters
descriptorto copy from.

◆ fsys() [2/3]

ucommon::fsys::fsys ( const char * path,
access_t access )

Create a fsys descriptor by opening an existing file or directory.

Parameters
pathof file to open for created descriptor.
accessmode of file.

◆ fsys() [3/3]

ucommon::fsys::fsys ( const char * path,
unsigned permission,
access_t access )

Create a fsys descriptor by creating a file.

Parameters
pathof file to create for descriptor.
accessmode of file access.
permissionmode of file.

Member Function Documentation

◆ append()

static fd_t ucommon::fsys::append ( const char * path)
static

Direct means to create or append a writable path and return descriptor.

Parameters
pathto create.
Returns
descriptor on success, invalid handle on failure.

◆ assign() [1/2]

void ucommon::fsys::assign ( fd_t descriptor)
inline

Assign descriptor directly.

Parameters
descriptorto assign.

Definition at line 491 of file fsys.h.

◆ assign() [2/2]

static void ucommon::fsys::assign ( fsys & object,
fd_t descriptor )
inlinestatic

Assign a descriptor directly.

Parameters
objectto assign descriptor to.
descriptorto assign.

Definition at line 501 of file fsys.h.

◆ close()

int ucommon::fsys::close ( void )

Close a fsys resource.

Returns
error code as needed.

◆ copy()

static int ucommon::fsys::copy ( const char * source,
const char * target,
size_t size = 1024 )
static

Copy a file.

Parameters
sourcefile.
targetfile.
sizeof buffer.
Returns
error number or 0 on success.

◆ drop()

int ucommon::fsys::drop ( offset_t size = 0)

Drop cached data from start of file.

Parameters
sizeof region to drop or until end of file.
Returns
error number or 0 on success.

◆ erase()

static int ucommon::fsys::erase ( const char * path)
static

Erase (remove) a file only.

Parameters
pathof file.
Returns
error number or 0 on success.

◆ err()

int ucommon::fsys::err ( void ) const
inline

Get last error.

Returns
error number.

Definition at line 557 of file fsys.h.

◆ exec()

static int ucommon::fsys::exec ( const char * path,
char ** argv,
char ** envp = NULL )
static

Execute a process and get exit code.

Parameters
pathto execute.
argvlist.
optionalenv.
Returns
exit code.

◆ handle()

fd_t ucommon::fsys::handle ( void ) const
inline

Get the native system descriptor handle of the file descriptor.

Returns
native os descriptor.

Definition at line 281 of file fsys.h.

◆ hardlink()

static int ucommon::fsys::hardlink ( const char * path,
const char * target )
static

Create a hard link.

Parameters
pathto create link to.
targetof link.
Returns
error number or 0 on success.

◆ info() [1/2]

static int ucommon::fsys::info ( const char * path,
fileinfo_t * buffer )
static

Stat a file.

Parameters
pathof file to stat.
bufferto save stat info.
Returns
error number or 0 on success.

◆ info() [2/2]

int ucommon::fsys::info ( fileinfo_t * buffer)

Get status of open descriptor.

Parameters
bufferto save status info in.
Returns
error number or 0 on success.

◆ inherit()

static int ucommon::fsys::inherit ( fd_t & descriptor,
bool enable )
static

Changle inheritable handle.

On windows this is done by creating a duplicate handle and then closing the original. Elsewhere this is done simply by setting flags.

Parameters
descriptorto modify.
enablechild process inheritence.
Returns
0 on success, error on failure.

◆ input()

static fd_t ucommon::fsys::input ( const char * path)
static

Direct means to open a read-only file path and return a descriptor.

Parameters
pathto open.
Returns
descriptor on success, invalid handle on failure.

◆ is_char()

static bool ucommon::fsys::is_char ( struct stat * inode)
inlinestatic

Definition at line 645 of file fsys.h.

◆ is_dev()

static bool ucommon::fsys::is_dev ( struct stat * inode)
inlinestatic

Definition at line 641 of file fsys.h.

◆ is_device()

static bool ucommon::fsys::is_device ( const char * path)
static

Test if path is a device path.

Parameters
pathto test.
Returns
true of is a device path.

◆ is_dir() [1/2]

static bool ucommon::fsys::is_dir ( const char * path)
static

Test if path is a directory.

Parameters
pathto test.
Returns
true if exists and is directory.

◆ is_dir() [2/2]

static bool ucommon::fsys::is_dir ( struct stat * inode)
inlinestatic

Definition at line 633 of file fsys.h.

◆ is_disk()

static bool ucommon::fsys::is_disk ( struct stat * inode)
inlinestatic

Definition at line 649 of file fsys.h.

◆ is_executable()

static bool ucommon::fsys::is_executable ( const char * path)
static

Test if path is executable.

Parameters
pathto test.
Returns
if true.

◆ is_exists()

static bool ucommon::fsys::is_exists ( const char * path)
static

Test if path exists.

Parameters
pathto test.
Returns
if true.

◆ is_file() [1/2]

static bool ucommon::fsys::is_file ( const char * path)
static

Test if path is a file.

Parameters
pathto test.
Returns
true if exists and is file.

◆ is_file() [2/2]

static bool ucommon::fsys::is_file ( struct stat * inode)
inlinestatic

Definition at line 629 of file fsys.h.

◆ is_hidden()

static bool ucommon::fsys::is_hidden ( const char * path)
static

Test if path is a hidden file.

Parameters
pathto test.
Returns
true if exists and is hidden.

◆ is_link() [1/2]

static bool ucommon::fsys::is_link ( const char * path)
static

Test if path is a symlink.

Parameters
pathto test.
Returns
true if exists and is symlink.

◆ is_link() [2/2]

static bool ucommon::fsys::is_link ( struct stat * inode)
inlinestatic

Definition at line 637 of file fsys.h.

◆ is_readable()

static bool ucommon::fsys::is_readable ( const char * path)
static

Test if path readable.

Parameters
pathto test.
Returns
if true.

◆ is_sys()

static bool ucommon::fsys::is_sys ( struct stat * inode)
inlinestatic

Definition at line 653 of file fsys.h.

◆ is_tty() [1/2]

static bool ucommon::fsys::is_tty ( fd_t fd)
static

See if the file handle is a tty device.

Returns
true if device.

◆ is_tty() [2/2]

bool ucommon::fsys::is_tty ( void ) const

See if current file stream is a tty device.

Returns
true if device.

◆ is_writable()

static bool ucommon::fsys::is_writable ( const char * path)
static

Test if path writable.

Parameters
pathto test.
Returns
if true.

◆ link()

static int ucommon::fsys::link ( const char * path,
const char * target )
static

Create a symbolic link.

Parameters
pathto create.
targetof link.
Returns
error number or 0 on success.

◆ linkinfo()

static int ucommon::fsys::linkinfo ( const char * path,
char * buffer,
size_t size )
static

Read a symbolic link to get it's target.

Parameters
pathof link.
bufferto save target into.
sizeof buffer.

◆ load()

static int ucommon::fsys::load ( const char * path)
static

Load a library into memory.

Parameters
pathto plugin.
Returns
0 on success, else error.

◆ mode()

static int ucommon::fsys::mode ( const char * path,
unsigned value )
static

Change file access mode.

Parameters
pathto change.
valueof mode to assign.
Returns
error number or 0 on success.

◆ null()

static fd_t ucommon::fsys::null ( void )
static

Create inheritable /dev/null handle.

Returns
null device handle.

◆ open() [1/2]

void ucommon::fsys::open ( const char * path,
access_t access )

Open a file or directory.

Parameters
pathof file to open.
accessmode of descriptor.

◆ open() [2/2]

void ucommon::fsys::open ( const char * path,
unsigned mode,
access_t access )

Open a file descriptor directly.

Parameters
pathof file to create.
accessmode of descriptor.
modeof file if created.

◆ operator bool()

ucommon::fsys::operator bool ( ) const
inline

Test if file descriptor is open.

Returns
true if open.

Definition at line 246 of file fsys.h.

◆ operator fd_t()

ucommon::fsys::operator fd_t ( ) const
inline

Get the descriptor from the object by casting reference.

Returns
low level file handle.

Definition at line 231 of file fsys.h.

◆ operator!()

bool ucommon::fsys::operator! ( ) const
inline

Test if file descriptor is closed.

Returns
true if closed.

Definition at line 254 of file fsys.h.

◆ operator*()

fd_t ucommon::fsys::operator* ( ) const
inline

Get the descriptor from the object by pointer reference.

Returns
low level file handle.

Definition at line 223 of file fsys.h.

◆ operator*=()

fsys & ucommon::fsys::operator*= ( fd_t & descriptor)

Replace current file descriptor with an external descriptor.

This does not create a duplicate. The external descriptor object is marked as invalid.

◆ operator=() [1/2]

fsys & ucommon::fsys::operator= ( const fsys & descriptor)

Assign file descriptor by duplicating another descriptor.

Parameters
descriptorto dup from.

◆ operator=() [2/2]

fsys & ucommon::fsys::operator= ( fd_t descriptor)

Assing file descriptor from system descriptor.

Parameters
descriptorto dup from.

◆ output()

static fd_t ucommon::fsys::output ( const char * path)
static

Direct means to create or access a writable path and return descriptor.

Parameters
pathto create.
Returns
descriptor on success, invalid handle on failure.

◆ pipe()

static int ucommon::fsys::pipe ( fd_t & input,
fd_t & output,
size_t size = 0 )
static

Create pipe.

These are created inheritable by default.

Parameters
inputdescriptor.
outputdescriptor.
sizeof buffer if supported.
Returns
0 or error code.

◆ prefix() [1/2]

static int ucommon::fsys::prefix ( char * path,
size_t size )
static

Get current directory prefix (pwd).

Parameters
pathto save directory into.
sizeof path we can save.
Returns
error number or 0 on success.

◆ prefix() [2/2]

static int ucommon::fsys::prefix ( const char * path)
static

Set directory prefix (chdir).

Parameters
pathto change to.
Returns
error number or 0 on success.

◆ read()

ssize_t ucommon::fsys::read ( void * buffer,
size_t count )

Read data from descriptor or scan directory.

Parameters
bufferto read into.
countof bytes to read.
Returns
bytes transferred, -1 if error.

◆ release() [1/2]

static void ucommon::fsys::release ( fd_t descriptor)
static

Release a file descriptor.

Parameters
descriptorto release.

◆ release() [2/2]

fd_t ucommon::fsys::release ( void )

Release descriptor, do not close.

Returns
handle being released.

◆ remapError()

static int ucommon::fsys::remapError ( void )
inlinestatic

Definition at line 152 of file fsys.h.

◆ rename()

static int ucommon::fsys::rename ( const char * oldpath,
const char * newpath )
static

Rename a file.

Parameters
oldpathto rename from.
newpathto rename to.
Returns
error number or 0 on success.

◆ reset()

void ucommon::fsys::reset ( void )
inline

Reset error flag.

Definition at line 238 of file fsys.h.

◆ seek()

int ucommon::fsys::seek ( offset_t offset)

Set the position of a file descriptor.

Parameters
offsetfrom start of file or "end" to append.
Returns
error number or 0 on success.

◆ set()

void ucommon::fsys::set ( fd_t descriptor)

Set with external descriptor.

Closes existing file if open.

Parameters
descriptorof open file.

◆ sync()

int ucommon::fsys::sync ( void )

Commit changes to the filesystem.

Returns
error number or 0 on success.

◆ trunc()

int ucommon::fsys::trunc ( offset_t offset)

Truncate file to specified length.

The file pointer is positioned to the new end of file.

Parameters
offsetto truncate to.
Returns
true if truncate successful.

◆ unlink()

static int ucommon::fsys::unlink ( const char * path)
static

Remove a symbolic link explicitly.

Other kinds of files are also deleted. This should be used when uncertain about symlinks requiring special support.

Parameters
pathto remove.
Returns
error number or 0 on success.

◆ write()

ssize_t ucommon::fsys::write ( const void * buffer,
size_t count )

Write data to descriptor.

Parameters
bufferto write from.
countof bytes to write.
Returns
bytes transferred, -1 if error.

Field Documentation

◆ end

const offset_t ucommon::fsys::end
static

Used to mark "append" in set position operations.

Definition at line 181 of file fsys.h.

◆ error

int ucommon::fsys::error
mutableprotected

Definition at line 129 of file fsys.h.

◆ fd

fd_t ucommon::fsys::fd
protected

Definition at line 128 of file fsys.h.


The documentation for this class was generated from the following file: