UCommon
Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Attributes
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:
Inheritance graph
[legend]

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.
enum  access_t {
  RDONLY, WRONLY, REWRITE, RDWR = REWRITE,
  APPEND, SHARED, EXCLUSIVE, DEVICE,
  STREAM, RANDOM
}
 Enumerated file access modes.
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 (fd_t handle)
 Contruct fsys from raw file handle.
 fsys (const fsys &descriptor)
 Copy (dup) an existing 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.
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.
void operator*= (fd_t &descriptor)
 Replace current file descriptor with an external descriptor.
void operator= (const fsys &descriptor)
 Assign file descriptor by duplicating another descriptor.
void operator= (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=((void *) 0))
 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 (const char *path)
 Set directory prefix (chdir).
static int prefix (char *path, size_t size)
 Get current directory prefix (pwd).
static string_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.


Constructor & Destructor Documentation

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

Copy (dup) an existing fsys descriptor.

Parameters:
descriptorto copy from.
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.
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

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.
void ucommon::fsys::assign ( fd_t  descriptor) [inline]

Assign descriptor directly.

Parameters:
descriptorto assign.

Definition at line 484 of file fsys.h.

static void ucommon::fsys::assign ( fsys object,
fd_t  descriptor 
) [inline, static]

Assign a descriptor directly.

Parameters:
objectto assign descriptor to.
descriptorto assign.

Definition at line 492 of file fsys.h.

int ucommon::fsys::close ( void  )

Close a fsys resource.

Returns:
error code as needed.

Reimplemented in ucommon::dir.

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.
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.
static int ucommon::fsys::erase ( const char *  path) [static]

Erase (remove) a file only.

Parameters:
pathof file.
Returns:
error number or 0 on success.
int ucommon::fsys::err ( void  ) const [inline]

Get last error.

Returns:
error number.

Reimplemented in ucommon::dir.

Definition at line 546 of file fsys.h.

static int ucommon::fsys::exec ( const char *  path,
char **  argv,
char **  envp = ((void *) 0) 
) [static]

Execute a process and get exit code.

Parameters:
pathto execute.
argvlist.
optionalenv.
Returns:
exit code.
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 275 of file fsys.h.

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.
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.
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.
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.
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.
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.
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.
static bool ucommon::fsys::is_executable ( const char *  path) [static]

Test if path is executable.

Parameters:
pathto test.
Returns:
if true.
static bool ucommon::fsys::is_exists ( const char *  path) [static]

Test if path exists.

Parameters:
pathto test.
Returns:
if true.
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.
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.
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.
static bool ucommon::fsys::is_readable ( const char *  path) [static]

Test if path readable.

Parameters:
pathto test.
Returns:
if true.
bool ucommon::fsys::is_tty ( void  ) const

See if current file stream is a tty device.

Returns:
true if device.
static bool ucommon::fsys::is_tty ( fd_t  fd) [static]

See if the file handle is a tty device.

Returns:
true if device.
static bool ucommon::fsys::is_writable ( const char *  path) [static]

Test if path writable.

Parameters:
pathto test.
Returns:
if true.
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.
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.
static int ucommon::fsys::load ( const char *  path) [static]

Load a library into memory.

Parameters:
pathto plugin.
Returns:
0 on success, else error.
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.
static fd_t ucommon::fsys::null ( void  ) [static]

Create inheritable /dev/null handle.

Returns:
null device handle.
void ucommon::fsys::open ( const char *  path,
access_t  access 
)

Open a file or directory.

Parameters:
pathof file to open.
accessmode of descriptor.
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.
ucommon::fsys::operator bool ( ) const [inline]

Test if file descriptor is open.

Returns:
true if open.

Reimplemented in ucommon::dir.

Definition at line 242 of file fsys.h.

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

Get the descriptor from the object by casting reference.

Returns:
low level file handle.

Definition at line 229 of file fsys.h.

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

Test if file descriptor is closed.

Returns:
true if closed.

Reimplemented in ucommon::dir.

Definition at line 249 of file fsys.h.

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

Get the descriptor from the object by pointer reference.

Returns:
low level file handle.

Definition at line 222 of file fsys.h.

void 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.

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

Assign file descriptor by duplicating another descriptor.

Parameters:
descriptorto dup from.
void ucommon::fsys::operator= ( fd_t  descriptor)

Assing file descriptor from system descriptor.

Parameters:
descriptorto dup from.
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.
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.
static int ucommon::fsys::prefix ( const char *  path) [static]

Set directory prefix (chdir).

Parameters:
pathto change to.
Returns:
error number or 0 on success.
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.
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.
fd_t ucommon::fsys::release ( void  )

Release descriptor, do not close.

Returns:
handle being released.
static void ucommon::fsys::release ( fd_t  descriptor) [static]

Release a file descriptor.

Parameters:
descriptorto release.
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.
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.
void ucommon::fsys::set ( fd_t  descriptor)

Set with external descriptor.

Closes existing file if open.

Parameters:
descriptorof open file.
int ucommon::fsys::sync ( void  )

Commit changes to the filesystem.

Returns:
error number or 0 on success.
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.
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.
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.

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