// Copyright (c) 2002 David Muse
// See the COPYING file for more information.
#ifndef RUDIMENTS_FILEDESCRIPTOR_H
#define RUDIMENTS_FILEDESCRIPTOR_H
#include <rudiments/private/filedescriptorincludes.h>
// The filedescriptor class is a base class for other classes that utilize
// file descriptors.
class filedescriptor {
public:
filedescriptor();
// Creates an uninitialized filedescriptor.
virtual ~filedescriptor();
// Calls close() if it hasn't already been
// called.
bool close();
// Closes the file descriptor.
// Returns true on success and false on failure.
int getFileDescriptor() const;
// Returns the file descriptor.
void setFileDescriptor(int filedesc);
// Sets the file descriptor associated with
// the class to "filedesc".
int duplicate() const;
// Duplicates the file descriptor and returns
// the handle of the duplicate descriptor. The
// old and new descriptors may be used
// interchangeably, they share locks, position
// pointers, flags (except the close-on-exec
// flag), etc.
//
// Returns the lowest-numbered unused descriptor
// on success or -1 on failure.
bool duplicate(int newfd) const;
// Sets file descriptor handle "newfd" to be a
// duplicate of this file descriptor. If
// "newfd" is already open, it will be closed
// first.
//
// Returns true on success and false on failure.
#ifdef RUDIMENTS_HAS_SSL
void setSSLContext(SSL_CTX *ctx);
// Associates SSL context "ctx" with the
// filedescriptor. Passing in a NULL for "ctx"
// has the additional side effect of calling
// deInitializeSSL() below.
bool initializeSSL();
// Should be called after calling
// setSSLContext() and one of open(),
// create() or connect() (from socket child
// classes). Causes the appropriate SSL
// function to be called instead of or in
// concert with read(), write(), connect(),
// accept() and close() methods.
//
// Returns true on success and false on failure
SSL *getSSL() const;
// Returns a pointer to the currently
// initialized SSL handle or NULL if
// initializeSSL() has not been called or
// failed.
void deInitializeSSL();
// Causes read(), write(), connect(), accept()
// and close() methods to be performed
// without the accompanying SSL-specific
// functions.
int getSSLResult() const;
// Returns the result code of the previously
// executed SSL command. If a method fails
// but errno is 0 then an SSL-related error
// occurred. You may call SSL_get_error()
// on the result of this method to determine
// the exact error.
#endif
virtual bool useNonBlockingMode() const;
// Puts the file descriptor in non-blocking
// mode. Returns true on success and false on
// failure.
virtual bool useBlockingMode() const;
// Puts the file descriptor in blocking mode.
// Returns true on success and false on
// failure.
bool isUsingNonBlockingMode() const;
// Returns true if the file descriptor is in
// non-blocking mode and false otherwise.
// Write methods - write data to the file descriptor.
// These methods return the number of bytes that were
// successfully written or RESULT_ERROR if an error occurred.
ssize_t write(unsigned short number);
// Write "number" to the file descriptor.
ssize_t write(unsigned long number);
// Write "number" to the file descriptor.
ssize_t write(short number);
// Write "number" to the file descriptor.
ssize_t write(long number);
// Write "number" to the file descriptor.
ssize_t write(float number);
// Write "number" to the file descriptor.
ssize_t write(double number);
// Write "number" to the file descriptor.
ssize_t write(unsigned char character);
// Write "character" to the file descriptor.
ssize_t write(char character);
// Write "character" to the file descriptor.
ssize_t write(bool value);
// Write "value" to the file descriptor.
ssize_t write(const unsigned char *string);
// Write "string" to the file descriptor. Note
// that "string" must be NULL-terminated.
ssize_t write(const char *string);
// Write "string" to the file descriptor. Note
// that "string" must be NULL-terminated.
ssize_t write(const unsigned char *string, size_t size);
// Write "size" bytes from "string" to the file
// descriptor. Note that it is possible to
// write beyond the string's NULL terminator
// using this method.
ssize_t write(const char *string, size_t size);
// Write "size" bytes from "string" to the file
// descriptor. Note that it is possible to
// write beyond the string's NULL terminator
// using this method.
ssize_t write(const void *buffer, size_t size);
// Write "size" bytes from "buffer" to the file
// descriptor.
// Write methods - write data to the file descriptor with a
// timeout of "sec" seconds and "usec" microseconds.
// These methods return the number of bytes that were
// successfully written, RESULT_ERROR if an error occurred or
// RESULT_TIMEOUT if a timeout occurred.
ssize_t write(unsigned short number, long sec, long usec);
// Write "number" to the file descriptor.
ssize_t write(unsigned long number, long sec, long usec);
// Write "number" to the file descriptor.
ssize_t write(short number, long sec, long usec);
// Write "number" to the file descriptor.
ssize_t write(long number, long sec, long usec);
// Write "number" to the file descriptor.
ssize_t write(float number, long sec, long usec);
// Write "number" to the file descriptor.
ssize_t write(double number, long sec, long usec);
// Write "number" to the file descriptor.
ssize_t write(unsigned char character, long sec, long usec);
// Write "character" to the file descriptor.
ssize_t write(char character, long sec, long usec);
// Write "character" to the file descriptor.
ssize_t write(bool value, long sec, long usec);
// Write "value" to the file descriptor.
ssize_t write(const unsigned char *string, long sec, long usec);
// Write "string" to the file descriptor. Note
// that "string" must be NULL-terminated.
ssize_t write(const char *string, long sec, long usec);
// Write "string" to the file descriptor. Note
// that "string" must be NULL-terminated.
ssize_t write(const unsigned char *string, size_t size,
long sec, long usec);
// Write "size" bytes from "string" to the file
// descriptor. Note that it is possible to
// write beyond the string's NULL terminator
// using this method.
ssize_t write(const char *string, size_t size,
long sec, long usec);
// Write "size" bytes from "string" to the file
// descriptor. Note that it is possible to
// write beyond the string's NULL terminator
// using this method.
ssize_t write(const void *buffer, size_t size,
long sec, long usec);
// Write "size" bytes from "buffer" to the file
// descriptor.
// Read methods - read data from the file descriptor.
// These methods return the number of bytes that were
// successfully read or RESULT_ERROR if an error occurred.
ssize_t read(unsigned short *buffer);
// Reads sizeof(unsigned short) bytes
// from the file descriptor into "buffer".
ssize_t read(unsigned long *buffer);
// Reads sizeof(unsigned long) bytes
// from the file descriptor into "buffer".
ssize_t read(short *buffer);
// Reads sizeof(short) bytes
// from the file descriptor into "buffer".
ssize_t read(long *buffer);
// Reads sizeof(long) bytes
// from the file descriptor into "buffer".
ssize_t read(float *buffer);
// Reads sizeof(float) bytes from the file
// descriptor into "buffer".
ssize_t read(double *buffer);
// Reads sizeof(double) bytes from the file
// descriptor into "buffer".
ssize_t read(unsigned char *buffer);
// Reads sizeof(unsigned char) bytes
// from the file descriptor into "buffer".
ssize_t read(char *buffer);
// Reads sizeof(char) bytes from the file
// descriptor into "buffer".
ssize_t read(bool *buffer);
// Reads sizeof(bool) bytes from the file
// descriptor into "buffer".
ssize_t read(unsigned char *buffer, size_t size);
// Reads "size" bytes from the file descriptor
// into "buffer".
ssize_t read(char *buffer, size_t size);
// Reads "size" bytes from the file descriptor
// into "buffer".
ssize_t read(void *buf, size_t size);
// Reads "size" bytes from the file descriptor
// into "buffer".
ssize_t read(char **buffer, char *terminator);
// Reads from the file desciptor into "buffer"
// until "terminator" is encountered. Note
// that "buffer" is allocated internally and
// must be freed by the calling program.
// Read methods - read data from the file descriptor with a
// timeout of "sec" seconds and "usec" microseconds.
// These methods return the number of bytes that were
// successfully read, RESULT_ERROR if an error occurred or
// RESULT_TIMEOUT if a timeout occurred.
ssize_t read(unsigned short *buffer, long sec, long usec);
// Reads sizeof(unsigned short) bytes
// from the file descriptor into "buffer".
ssize_t read(unsigned long *buffer, long sec, long usec);
// Reads sizeof(unsigned long) bytes
// from the file descriptor into "buffer".
ssize_t read(short *buffer, long sec, long usec);
// Reads sizeof(short) bytes
// from the file descriptor into "buffer".
ssize_t read(long *buffer, long sec, long usec);
// Reads sizeof(long) bytes
// from the file descriptor into "buffer".
ssize_t read(float *buffer, long sec, long usec);
// Reads sizeof(float) bytes from the file
// descriptor into "buffer".
ssize_t read(double *buffer, long sec, long usec);
// Reads sizeof(double) bytes from the file
// descriptor into "buffer".
ssize_t read(unsigned char *buffer, long sec, long usec);
// Reads sizeof(unsigned char) bytes
// from the file descriptor into "buffer".
ssize_t read(char *buffer, long sec, long usec);
// Reads sizeof(char) bytes from the file
// descriptor into "buffer".
ssize_t read(bool *buffer, long sec, long usec);
// Reads sizeof(bool) bytes from the
// file descriptor into "buffer".
ssize_t read(unsigned char *buffer, size_t size,
long sec, long usec);
// Reads "size" bytes from the file descriptor
// into "buffer".
ssize_t read(char *buffer, size_t size, long sec, long usec);
// Reads "size" bytes from the file descriptor
// into "buffer".
ssize_t read(void *buf, size_t size, long sec, long usec);
// Reads "size" bytes from the file descriptor
// into "buffer".
ssize_t read(char **buffer, char *terminator,
long sec, long usec);
// Reads from the file desciptor into "buffer"
// until "terminator" is encountered. Note
// that "buffer" is allocated internally and
// must be freed by the calling program.
// Wait methods.
int waitForNonBlockingRead(long sec, long usec) const;
// Causes the application to wait until a read()
// will proceed without blocking or until "sec"
// seconds and "usec" microseconds have elapsed.
//
// Entering -1 for either parameter causes the
// method to wait indefinitely.
//
// Entering 0 for both parameters causes the
// method to fall through immediately unless a
// data is immediately available.
//
// Returns RESULT_ERROR on error, RESULT_TIMEOUT
// on timeout and otherwise returns the number
// of file descriptors that are ready to be
// read from.
//
// This will usually be 1, indicating that the
// file descriptor represented by the class is
// ready to be read from. However, if
// useListener() has been called, it may be
// greater than 1, indicating that a set of
// file descriptors that the listener is
// listening on are all ready to be read from.
int waitForNonBlockingWrite(long sec, long usec) const;
// Causes the application to wait until a
// write() will proceed without blocking or
// until "sec" seconds and "usec" microseconds
// have elapsed.
//
// Entering -1 for either parameter causes the
// method to wait indefinitely.
//
// Entering 0 for both parameters causes the
// method to fall through immediately unless a
// data is immediately available.
//
// Returns RESULT_ERROR on error, RESULT_TIMEOUT
// on timeout and otherwise returns the number
// of file descriptors that are ready to be
// written to.
//
// This will usually be 1, indicating that the
// file descriptor represented by the class is
// ready to be written to. However, if
// useListener() has been called, it may be
// greater than 1, indicating that a set of
// file descriptors that the listener is
// listening on are all ready to be written to.
// By default, if a read or write is occurring and a signal
// interrupts it, the read or write returns with errno set to
// EINTR and must be retried. These methods override that
// behavior.
void retryInterruptedReads();
// Causes reads to automatically retry if interrupted
// by a signal.
void dontRetryInterruptedReads();
// Causes reads not to automatically retry if
// interrupted by a signal.
void retryInterruptedWrites();
// Causes writes to automatically retry if
// interrupted by a signal. This is the default.
void dontRetryInterruptedWrites();
// Causes writes not to automatically retry if
// interrupted by a signal.
void retryInterruptedWaits();
// Causes waits to automatically retry if
// interrupted by a signal. This is the default.
void dontRetryInterruptedWaits();
// Causes waits not to automatically retry if
// interrupted by a signal.
void retryInterruptedFcntl();
// Causes fcntl() to automatically retry if
// interrupted by a signal. This is the default.
void dontRetryInterruptedFcntl();
// Causes fcntl() not to automatically retry if
// interrupted by a signal.
void retryInterruptedIoctl();
// Causes ioctl() to automatically retry if
// interrupted by a signal. This is the default.
void dontRetryInterruptedIoctl();
// Causes ioctl() not to automatically retry if
// interrupted by a signal.
// By default, read() will attempt to read the specified number
// of bytes from the file descriptor, in several passes if
// necessary. No single pass will try to read more than
// SSIZE_MAX bytes. These methods override that behavior.
void allowShortReads();
// Causes a read to return the number of bytes that
// were read in a single pass from the file descriptor.
// Note that reads longer than SSIZE_MAX will always
// return SSIZE_MAX or fewer bytes. This is useful,
// for example, when reading from devices which block
// rather than returning 0 for EOF.
void dontAllowShortReads();
// Causes a read to attempt to read the specified
// number of bytes from the file descriptor, in several
// passes if necessary.
// By default, calls to waitForNonBlockingRead() and
// waitForNonBlockingWrite() will wait using the select()
// system call. These methods override that behavior.
void useListener(listener *lstnr);
// Causes calls to waitForNonBlockingRead() and
// waitForNonBlockingWrite() to in turn call
// lstnr->waitForNonBlockingRead() or
// lstnr->waitForNonBlockingWrite().
void dontUseListener();
// Causes calls to waitForNonBlockingRead() and
// waitForNonBlockingWrite() to use select().
// This is the default.
listener *getListener();
// Returns the listener set previously by useListener()
// or NULL if none has been set.
virtual bool passFileDescriptor(int descriptor);
virtual bool receiveFileDescriptor(int *descriptor);
void translateByteOrder();
void dontTranslateByteOrder();
int fcntl(int command, long arg) const;
int ioctl(int command, void *arg) const;
// Interfaces for performing varions miscellaneous
// operations on the file descriptor.
#include <rudiments/private/filedescriptor.h>
};
#endif