// Copyright (c) 2002 David Muse
// See the COPYING file for more information.
#ifndef RUDIMENTS_FILE_H
#define RUDIMENTS_FILE_H
#include <rudiments/private/fileincludes.h>
// The file class provides methods for interacting with files and for
// discovering the properties associated with a file such as permissions,
// ownership, size, etc.
//
// Use the static methods in this class if you need to get a a single property.
//
// If you need to get more that one property, create an instance of the class,
// call open(), then use the non-static methods to access the properties that
// you need.
class file : public filedescriptor {
public:
file();
// Creates an uninitialized instance of the file class.
file(int fd);
// Creates an uninitialized instance of the file class
// and associates already open file descriptor "fd"
// with it.
bool open(const char *name, int flags);
// Opens file "name" using "flags". Once the file is
// open, it also gets it's properties.
//
// Returns true on success and false on failure.
bool open(const char *name, int flags, mode_t perms);
// Opens file "name" using "flags". If the file
// doesn't already exist and flags contains O_CREAT,
// the file will be created with permissions "perms".
// Once the file is open, it also gets it's properties.
//
// Returns true on success and false on failure.
bool create(const char *name, mode_t perms);
// Creates the file "name" with permissions "perms"
// If the file already exists, it will be truncated.
// Once the file is created, it also gets it's
// properties.
//
// Returns true on success and false on failure.
// These methods create the file "name" with permissions
// "perms". If the the file already exists, it will be
// truncated. The initial contents of the file are set to
// "data".
//
// These methods return the number of bytes written to the file
// or -1 if an error occurs.
ssize_t create(const char *name, mode_t perms,
unsigned short number);
// Sets the initial contents "number".
ssize_t create(const char *name, mode_t perms,
unsigned long number);
// Sets the initial contents "number".
ssize_t create(const char *name, mode_t perms, float number);
// Sets the initial contents "number".
ssize_t create(const char *name, mode_t perms, double number);
// Sets the initial contents "number".
ssize_t create(const char *name, mode_t perms, char number);
// Sets the initial contents "number".
ssize_t create(const char *name, mode_t perms,
const char *string);
// Sets the initial contents to "string".
ssize_t create(const char *name, mode_t perms,
const char *string, size_t size);
// Sets the initial contents to "string" of size "size".
ssize_t create(const char *name, mode_t perms,
const void *data, size_t size);
// Sets the initial contents to "data" of size "size".
// The following methods allow you to lock files or regions
// of files.
//
// The tryLock() methods attempt to lock and return success if
// the lock can be established immediately or false otherwise.
//
// The lock() methods block until a lock is established and
// return true on success or false if an error occurs.
//
// The checkLock() methods check to see if a lock can be
// established but do not actually lock anything. If a lock
// can be established, they return true. Otherwise they return
// false and populate the fields in the supplied flock struct
// with information about one of the conflicting locks.
//
// The unlock() methods attempt to release a previosly
// established lock and return true on success or false on
// error.
// These methods allow you to lock the entire file.
bool tryLockFile(short type);
bool lockFile(short type);
bool checkLockFile(short type, struct flock *lck);
bool unlockFile(short type);
// These methods allow you to lock an arbitrary region of the
// file.
bool tryLockRegion(short type, off_t start, off_t len);
bool lockRegion(short type, off_t start, off_t len);
bool checkLockRegion(short type, off_t start, off_t len,
struct flock *lck);
bool unlockRegion(off_t start, off_t len);
// These methods allow you to lock an arbitrary region of the
// file relative to the current position.
bool tryLockFromCurrent(short type, off_t len);
bool tryLockFromCurrent(short type, off_t start, off_t len);
bool lockFromCurrent(short type, off_t len);
bool lockFromCurrent(short type, off_t start, off_t len);
bool checkLockFromCurrent(short type, off_t len,
struct flock *lck);
bool checkLockFromCurrent(short type, off_t start, off_t len,
struct flock *lck);
bool unlockFromCurrent(off_t len);
bool unlockFromCurrent(off_t start, off_t len);
// These methods allow you to lock an arbitrary region of the
// file relative to the end of the file.
bool tryLockFromEnd(short type, off_t len);
bool tryLockFromEnd(short type, off_t start, off_t len);
bool lockFromEnd(short type, off_t len);
bool lockFromEnd(short type, off_t start, off_t len);
bool checkLockFromEnd(short type, off_t len,
struct flock *lck);
bool checkLockFromEnd(short type, off_t start, off_t len,
struct flock *lck);
bool unlockFromEnd(off_t len);
bool unlockFromEnd(off_t start, off_t len);
// These methods allow you to lock "the remainder" of a file
// starting at a given offset.
bool tryLockRemainder(short type, off_t start);
bool lockRemainder(short type, off_t start);
bool checkLockRemainder(short type, off_t start,
struct flock *lck);
bool unlockRemainder(off_t start);
// These methods allow you to lock "the remainder" of a file
// relative to the current position.
bool tryLockRemainderFromCurrent(short type);
bool tryLockRemainderFromCurrent(short type, off_t start);
bool lockRemainderFromCurrent(short type);
bool lockRemainderFromCurrent(short type, off_t start);
bool checkLockRemainderFromCurrent(short type,
struct flock *lck);
bool checkLockRemainderFromCurrent(short type, off_t start,
struct flock *lck);
bool unlockRemainderFromCurrent();
bool unlockRemainderFromCurrent(off_t start);
// These methods allow you to lock "the remainder" of a file
// relative to the end of the file.
bool tryLockRemainderFromEnd(short type);
bool tryLockRemainderFromEnd(short type, off_t start);
bool lockRemainderFromEnd(short type);
bool lockRemainderFromEnd(short type, off_t start);
bool checkLockRemainderFromEnd(short type,
struct flock *lck);
bool checkLockRemainderFromEnd(short type, off_t start,
struct flock *lck);
bool unlockRemainderFromEnd();
bool unlockRemainderFromEnd(off_t start);
// These methods allow you to truncate a file
static bool truncate(const char *filename);
bool truncate();
// Truncates all data in the file, resulting in
// a file of zero length. Returns true on
// success and false on failure.
static bool truncate(const char *filename, off_t length);
bool truncate(off_t length);
// Truncates all data beyond the first "length"
// bytes, resulting in a file of "length" bytes.
// Returns true on success and false on failure.
// These methods allow you to set the position at which the
// next read or write will occur. Each returns the position
// relative to the beginning of the file on success or -1 on
// failure.
off_t setPositionRelativeToBeginning(off_t offset);
// Sets the position to the beginning of the
// file + "offset" bytes.
off_t setPositionRelativeToCurrent(off_t offset);
// Sets the position to the current
// position + "offset" bytes.
off_t setPositionRelativeToEnd(off_t offset);
// Sets the position to the end of the
// file + "offset" bytes.
off_t getCurrentPosition();
// Returns the position at which the next read or
// write will occur or -1 on error.
char *getContents();
// Allocates a string large enough to accommodate the
// contents of the currently opened file, reads the
// contents of the file into the string and returns the
// string. The string must be freed by the calling
// program.
//
// If the file contains no data, then a string of length
// zero is returned. If an error occurs then a NULL
// is returned.
static char *getContents(const char *name);
// Allocates a string large enough to accommodate the
// contents of the file "name" , reads the contents of
// the file into the string, terminates it with a NULL
// and returns the string.
// The string must be freed by the calling program.
//
// If the file contains no data, then a string of length
// zero is returned. If an error occurs then a NULL
// is returned.
ssize_t getContents(unsigned char *buffer, size_t buffersize);
// Reads the contents of the currently open file into
// "buffer" of length "buffersize". If the file is
// larger than "buffersize" then only "buffersize" bytes
// of the file will be read into "buffer".
//
// Returns the number of bytes copied into "buffer" or
// -1 on error.
static ssize_t getContents(const char *name,
unsigned char *buffer,
size_t buffersize);
// Reads the contents of the file "name" into
// "buffer" of length "buffersize". If the file is
// larger than "buffersize" then only "buffersize" bytes
// of the file will be read into "buffer".
//
// Returns the number of bytes copied into "buffer" or
// -1 on error.
bool getCurrentProperties();
// Gets the current file properties.
//
// Returns true on success and false on failure.
static bool exists(const char *filename);
// Returns true if the file exists and false otherwise.
// These methods return the permissions of the file.
//
// The static methods return true on success and false on
// failure.
mode_t getPermissions() const;
static bool getPermissions(const char *filename,
mode_t *perms);
static bool getPermissions(int fd, mode_t *perms);
// These methods return the user id of the file's owner.
//
// The static methods return true on success and false on
// failure.
uid_t getOwnerUserId() const;
static bool getOwnerUserId(const char *filename,
uid_t *uid);
static bool getOwnerUserId(int fd, uid_t *uid);
// These methods return the group id of the file's owner.
//
// The static methods return true on success and false on
// failure.
gid_t getOwnerGroupId() const;
static bool getOwnerGroupId(const char *filename,
gid_t *gid);
static bool getOwnerGroupId(int fd, gid_t *gid);
// These methods return the number of bytes in the file.
//
// The static methods return true on success and false on
// failure.
off_t getSize() const;
static bool getSize(const char *filename,
off_t *size);
static bool getSize(int fd, off_t *size);
// These methods return the blocksize to use
// for most efficient I/O with the file.
// Note that some systems don't support this.
// On those systems, a block size of -1 is returned.
//
// The static methods return true on success and false on
// failure.
blksize_t getBlockSize() const;
static bool getBlockSize(const char *filename,
blksize_t *size);
static bool getBlockSize(int fd, blksize_t *size);
// These methods return the number of
// blocks allocated for the file.
// Note that some systems don't support this.
// On those systems, a block count of -1 is returned.
//
// The static methods return true on success and false on
// failure.
blkcnt_t getBlockCount() const;
static bool getBlockCount(const char *filename,
blkcnt_t *blocks);
static bool getBlockCount(int fd, blkcnt_t *blocks);
// These methods return 1 of the file is a
// socket or 0 if it's not or -1 on error.
int isSocket() const;
static int isSocket(const char *filename);
static int isSocket(int fd);
// These methods return 1 of the file is a
// symbolic link, 0 if it's not or -1 on error.
int isSymbolicLink() const;
static int isSymbolicLink(const char *filename);
static int isSymbolicLink(int fd);
// These methods return 1 of the file is a
// regular file, 0 if it's not or -1 on error.
int isRegularFile() const;
static int isRegularFile(const char *filename);
static int isRegularFile(int fd);
// These methods return 1 of the file is a
// block device, 0 if it's not or -1 on error.
int isBlockDevice() const;
static int isBlockDevice(const char *filename);
static int isBlockDevice(int fd);
// These methods return 1 of the file is a
// directory, 0 if it's not or -1 on error.
int isDirectory() const;
static int isDirectory(const char *filename);
static int isDirectory(int fd);
// These methods return 1 of the file is a
// character device, 0 if it's not or -1 on error.
int isCharacterDevice() const;
static int isCharacterDevice(const char *filename);
static int isCharacterDevice(int fd);
// These methods return 1 of the file is a
// fifo, 0 if it's not or -1 on error.
int isFifo() const;
static int isFifo(const char *filename);
static int isFifo(int fd);
// These methods return the time of last access.
//
// The static methods return true on success and false on
// failure.
time_t getLastAccessTime() const;
static bool getLastAccessTime(const char *filename,
time_t *atime);
static bool getLastAccessTime(int fd, time_t *atime);
// These methods return the time of last modification.
//
// Modification time IS NOT affected by chmod, chown,
// or creating links.
//
// The static methods return true on success and false on
// failure.
time_t getLastModificationTime() const;
static bool getLastModificationTime(const char *filename,
time_t *mtime);
static bool getLastModificationTime(int fd, time_t *mtime);
// These methods return the time of last change.
//
// Change time IS affected by chmod, chown and creating links.
//
// The static methods return true on success and false on
// failure.
time_t getLastChangeTime() const;
static bool getLastChangeTime(const char *filename,
time_t *ctime);
static bool getLastChangeTime(int fd, time_t *ctime);
// These methods return the device of the file.
//
// The static methods return true on success and false on
// failure.
dev_t getDevice() const;
static bool getDevice(const char *filename, dev_t *dev);
static bool getDevice(int fd, dev_t *dev);
// These methods return the device type of the file.
//
// The static methods return true on success and false on
// failure.
dev_t getDeviceType() const;
static bool getDeviceType(const char *filename,
dev_t *devtype);
static bool getDeviceType(int fd, dev_t *devtype);
// These methods return the inode of the file.
//
// The static methods return true on success and false on
// failure.
ino_t getInode() const;
static bool getInode(const char *filename, ino_t *inode);
static bool getInode(int fd, ino_t *inode);
// These methods return the number of hard links to the file.
//
// The static methods return true on success and false on
// failure.
nlink_t getNumberOfHardLinks() const;
static bool getNumberOfHardLinks(const char *filename,
nlink_t *nlink);
static bool getNumberOfHardLinks(int fd, nlink_t *nlink);
// This method returns a pointer to the stat structure
// used internally.
struct stat *getStat();
// By default, the open() and create() methods call
// getCurrentProperties() so the other methods of this class
// will return valid data about the file immediately. These
// methods alter that behaviour.
void getCurrentPropertiesOnOpen();
void dontGetCurrentPropertiesOnOpen();
#include <rudiments/private/file.h>
};
#ifdef ENABLE_RUDIMENTS_INLINES
#include <rudiments/private/fileinlines.h>
#endif
#endif