// Copyright (c) 2002 David Muse
// See the COPYING file for more information.
#ifndef RUDIMENTS_FILE_H
#define RUDIMENTS_FILE_H
#include <rudiments/filedescriptor.h>
#include <stdlib.h>
#ifndef __USE_UNIX98
#define __USE_UNIX98
#endif
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#ifndef HAVE_BLKCNT_T
typedef long blkcnt_t;
#endif
#ifndef HAVE_BLKSIZE_T
typedef long blksize_t;
#endif
// 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.
int open(const char *name, int flags);
// Opens file "name" using "flags". Once the file is
// open, it also gets it's properties.
//
// Returns 1 on success and 0 on failure.
int 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 1 on success and 0 on failure.
int 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 1 on success and 0 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.
size_t create(const char *name, mode_t perms,
unsigned short number);
// Sets the initial contents "number".
size_t create(const char *name, mode_t perms,
unsigned long number);
// Sets the initial contents "number".
size_t create(const char *name, mode_t perms, float number);
// Sets the initial contents "number".
size_t create(const char *name, mode_t perms, double number);
// Sets the initial contents "number".
size_t create(const char *name, mode_t perms, char number);
// Sets the initial contents "number".
size_t create(const char *name, mode_t perms,
const char *string);
// Sets the initial contents to "string".
size_t create(const char *name, mode_t perms,
const char *string, size_t size);
// Sets the initial contents to "string" of size "size".
size_t create(const char *name, mode_t perms,
const void *data, size_t size);
// Sets the initial contents to "data" of size "size".
// 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 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.
int getCurrentProperties();
// Gets the current file properties.
// These methods return the permissions of the file.
mode_t getPermissions() const;
static int getPermissions(const char *filename,
mode_t *perms);
static int getPermissions(int fd, mode_t *perms);
// These methods return the user id of the file's owner.
uid_t getOwnerUserId() const;
static int getOwnerUserId(const char *filename,
uid_t *uid);
static int getOwnerUserId(int fd, uid_t *uid);
// These methods return the group id of the file's owner.
gid_t getOwnerGroupId() const;
static int getOwnerGroupId(const char *filename,
gid_t *gid);
static int getOwnerGroupId(int fd, gid_t *gid);
// These methods return the number of bytes in the file.
off_t getSize() const;
static int getSize(const char *filename,
off_t *size);
static int 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.
blksize_t getBlockSize() const;
static int getBlockSize(const char *filename,
blksize_t *size);
static int 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.
blkcnt_t getBlockCount() const;
static int getBlockCount(const char *filename,
blkcnt_t *blocks);
static int 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.
time_t getLastAccessTime() const;
static int getLastAccessTime(const char *filename,
time_t *atime);
static int 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.
time_t getLastModificationTime() const;
static int getLastModificationTime(const char *filename,
time_t *mtime);
static int getLastModificationTime(int fd, time_t *mtime);
// These methods return the time of last change.
//
// Change time IS affected by chmod, chown and creating links.
time_t getLastChangeTime() const;
static int getLastChangeTime(const char *filename,
time_t *ctime);
static int getLastChangeTime(int fd, time_t *ctime);
// These methods return the device of the file.
dev_t getDevice() const;
static int getDevice(const char *filename, dev_t *dev);
static int getDevice(int fd, dev_t *dev);
// These methods return the device type of the file.
dev_t getDeviceType() const;
static int getDeviceType(const char *filename,
dev_t *devtype);
static int getDeviceType(int fd, dev_t *devtype);
// These methods return the inode of the file.
ino_t getInode() const;
static int getInode(const char *filename, ino_t *inode);
static int getInode(int fd, ino_t *inode);
// These methods return the number of hard links to the file.
nlink_t getNumberOfHardLinks() const;
static int getNumberOfHardLinks(const char *filename,
nlink_t *nlink);
static int getNumberOfHardLinks(int fd, nlink_t *nlink);
// This method returns a pointer to the stat structure
// used internally.
struct stat *getStat();
#include <rudiments/private/file.h>
};
#ifdef ENABLE_INLINES
#include <rudiments/private/fileinlines.h>
#endif
#endif