Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members

Dv::Util::fdstreambuf Class Reference

A streambuf specialization that manages a file descriptor and handles timeouts. More...

#include <fdstreambuf.h>

List of all members.

Public Member Functions

 fdstreambuf (int fd=-1, size_t inbuf_sz=1024, size_t outbuf_sz=1024, time_t delay=0, bool non_blocking=false, std::ostream *debug=0)
 The constructor simply allocates the buffers and stores the delay (in millisecs).
virtual ~fdstreambuf ()
 This is already virtual in streambuf.
size_t inbuf_sz () const
size_t outbuf_sz () const
time_t delay () const
 Return the number of millsecs to wait before an open or input operation fails.
void delay (time_t d)
 Set delay (0 means infinite delay).
bool non_blocking () const
 Return the blocking status.
int set_non_blocking ()
 Set non-blocking I/O.
int fd () const
 Return file descriptor underlying this fdstreambuf object.
bool fd (int i, bool non_blocking=false)
 Set the underlying file descriptor.
virtual bool close ()
 Close the underlying file descriptor.
bool timedout () const
 Return true iff last I/O operation timed out.
bool timedout (bool timed_out) const
 Set timedout() flag.
int error () const
 Return last relevant ::errno as set by the system.
std::string strerror () const
 Return ::strerror(error()), a string representation of error().
void debug (std::ostream *os)
 Set debug stream.
std::ostream * debug () const
 Return pointer to current debug stream.
virtual int sync ()
 Override iostream::sync(), i.e.

Static Public Member Functions

int fdwait (int fd, time_t delay, int &syserrno, bool output=false)
 Check whether input or output on fd would block.

Protected Member Functions

virtual int underflow ()
 Override iostream::underflow(), i.e.
virtual int overflow (int c)
 Override iostream::overflow().
int fdwait (bool output) const
 Wait for I/O to become available.
int fdwait (bool output, int &syserrno) const
 Wait for I/O to become available.
int iwait () const
 Wait for input to become available.
int owait () const
 Wait for output to become available.
virtual int read (char *buf, size_t buf_sz)
 Attempt an input operation.
virtual int write (char *buf, size_t buf_sz)
 Attempt an output operation.
virtual int rread (char *buf, size_t len)
 Low level read function, default is ::read(fd(), buf, len); may set error().
virtual int rwrite (char *buf, size_t len)
 Low level write function, default is ::write(fd(), buf, len); may set error().
void error (int e) const
 Set error status of fdstreambuf.

Static Protected Member Functions

int flags (std::ios::openmode mode)
 Translate ios::openmode flags to open(2) flags like O_RDWR etc.

Private Member Functions

 fdstreambuf (const fdstreambuf &)
fdstreambufoperator= (const fdstreambuf &)
std::string debug_header (const std::string &funname) const
 Return string of the form ``fdstreambuf[fd]::function_name''.

Private Attributes

int fd_
 Underlying file descriptor, <0 if invalid.
time_t delay_
 The number of millsecs to wait before an open or input operation fails.
bool non_blocking_
 Whether fd_ is non-blocking.
size_t inbuf_sz_
 Size of internal input buffer.
size_t outbuf_sz_
 Size of internal output buffer.
char * inbuf_
 Input buffer.
char * outbuf_
 Output buffer.
int errno_
 Error status.
bool timedout_
 Error status.
std::ostream * debug_
 Pointer to stream to which debug info is to be written.


Detailed Description

A streambuf specialization that manages a file descriptor and handles timeouts.

Definition at line 20 of file fdstreambuf.h.


Constructor & Destructor Documentation

Dv::Util::fdstreambuf::fdstreambuf int  fd = -1,
size_t  inbuf_sz = 1024,
size_t  outbuf_sz = 1024,
time_t  delay = 0,
bool  non_blocking = false,
std::ostream *  debug = 0
[explicit]
 

The constructor simply allocates the buffers and stores the delay (in millisecs).

Parameters:
fd filedescriptor to be used by this fdstreambuf
inbuf_sz size of input buffer.
outbuf_sz size of output buffer.
delay time, in millisecs, to wait before an open or input operation fails, a delay of 0 means ``wait foerver''.
non_blocking whether the underlying filedecriptor is in non-blocking (O_NONBLOCK) mode, see fctnl(2). Using a non-blocking streambuf prevents some blocking I/O operations. E.g. if select(2) indicates that writing is possible but the actual number of bytes to write is too large, the write may block indefinitely for a blocking Socket. For a non-blocking socket, the write(2) will return EAGAIN which will be handled appropriately by fdstreambuf.
debug pointer to ostream to write debug info on or 0, see fdstreambuf::debug().
The constructor also calls signal(SIGPIPE,SIG_IGN), causing SIGPIPE signals to be ignored. Instead, the system should let the I/O operation fail and set errno to EPIPE.

virtual Dv::Util::fdstreambuf::~fdstreambuf  )  [virtual]
 

This is already virtual in streambuf.

Dv::Util::fdstreambuf::fdstreambuf const fdstreambuf  )  [private]
 


Member Function Documentation

size_t Dv::Util::fdstreambuf::inbuf_sz  )  const [inline]
 

Returns:
size of input buffer
Definition at line 56 of file fdstreambuf.h.

References inbuf_sz_.

size_t Dv::Util::fdstreambuf::outbuf_sz  )  const [inline]
 

Returns:
size of output buffer
Definition at line 58 of file fdstreambuf.h.

References outbuf_sz_.

time_t Dv::Util::fdstreambuf::delay  )  const [inline]
 

Return the number of millsecs to wait before an open or input operation fails.

A value of 0 means wait forever.

Returns:
The current delay value.
Definition at line 65 of file fdstreambuf.h.

References delay_.

void Dv::Util::fdstreambuf::delay time_t  d  )  [inline]
 

Set delay (0 means infinite delay).

Parameters:
d delay in millisecs, 0 means ``wait forever''.
Definition at line 72 of file fdstreambuf.h.

References delay_.

bool Dv::Util::fdstreambuf::non_blocking  )  const [inline]
 

Return the blocking status.

Returns:
true iff the constructor was called with non_blocking or set_non_blocking() was called before.
Definition at line 80 of file fdstreambuf.h.

References non_blocking_.

int Dv::Util::fdstreambuf::set_non_blocking  ) 
 

Set non-blocking I/O.

Returns:
0 upon success, -1 else in which case error() will reflect the system errno.
See also:
fcntl(2)

int Dv::Util::fdstreambuf::fd  )  const [inline]
 

Return file descriptor underlying this fdstreambuf object.

Returns:
The current value for the underlying file descriptor.
Definition at line 96 of file fdstreambuf.h.

References fd_.

bool Dv::Util::fdstreambuf::fd int  i,
bool  non_blocking = false
 

Set the underlying file descriptor.

The previous descriptor, if valid, is closed.

Parameters:
i new file descriptor.
non_blocking whether I/O should be non-blocking.
Returns:
true iff close() of the previous valid file descriptor succeeded
See also:
fdstreambuf::close()

virtual bool Dv::Util::fdstreambuf::close  )  [virtual]
 

Close the underlying file descriptor.

Returns:
false iff close() of the underlying valid file descriptor failed.

bool Dv::Util::fdstreambuf::timedout  )  const
 

Return true iff last I/O operation timed out.

Returns:
true iff the last I/O operation timed out or timedout(true) was called since the last I/O operation.

bool Dv::Util::fdstreambuf::timedout bool  timed_out  )  const
 

Set timedout() flag.

This flag can only be cleared explicitly by fdstreambuf::timedout(false) or by fdstreambuf::fd(int).

Parameters:
timed_out New value for timedout().
Returns:
true iff timedout status actually changed. It will return false, e.g. if the argument is false but the previous timedout status was not true.

int Dv::Util::fdstreambuf::error  )  const [inline]
 

Return last relevant ::errno as set by the system.

Returns:
The last relevant errno as aset by the system.
Definition at line 142 of file fdstreambuf.h.

References errno_.

std::string Dv::Util::fdstreambuf::strerror  )  const
 

Return ::strerror(error()), a string representation of error().

Returns:
A string representation of error().

void Dv::Util::fdstreambuf::debug std::ostream *  os  )  [inline]
 

Set debug stream.

If not null, trace info will be written to this stream for all I/O operations.

Parameters:
os Pointer to ostream or 0. In the latter case, no debug information will be written.
Definition at line 158 of file fdstreambuf.h.

References debug_.

std::ostream* Dv::Util::fdstreambuf::debug  )  const [inline]
 

Return pointer to current debug stream.

The function may return 0, if debugging is ``off''.

Returns:
A pointer to the current debug stream or 0.
Debug output may be generated for the following member functions: set_non_blocking(), error(int), read(), write(). Definition at line 169 of file fdstreambuf.h.

References debug_.

int Dv::Util::fdstreambuf::fdwait int  fd,
time_t  delay,
int &  syserrno,
bool  output = false
[static]
 

Check whether input or output on fd would block.

Parameters:
fd file descriptor to check, none if -1
delay time (in millisecs) we are prepared to wait. If 0, fdwait() may block indefinitely.
syserrno will contain system's errno if return -1
output false if fd is checked for input
Returns:
1 if input/output is available; 0 if a timeout occurred (in which case syserrno=ETIMEOUT) and a value <0 if another error occurred, in which case syserrno set to errno.

Referenced by iwait(), and owait().

virtual int Dv::Util::fdstreambuf::sync  )  [virtual]
 

Override iostream::sync(), i.e.

force all pending output to be written using fdstreambuf::rwrite().

Returns:
0 if ok, -1 else.

virtual int Dv::Util::fdstreambuf::underflow  )  [protected, virtual]
 

Override iostream::underflow(), i.e.

attempt to fill the input buffer using fdstreambuf::rread().

Returns:
next input char or EOF.

virtual int Dv::Util::fdstreambuf::overflow int  c  )  [protected, virtual]
 

Override iostream::overflow().

May call fdstreambuf::sync().

Returns:
c if the character was succeffuly written or EOF.

int Dv::Util::fdstreambuf::fdwait bool  output  )  const [protected]
 

Wait for I/O to become available.

Wait for output or input, depending on the value of the parameter. Sets error() appropriately if return value is not 1.

Parameters:
output Wait for output to be available if
Returns:
1 if input is available, 0 if a timeout occurred; -1 indicates an error condition (e.g. underlying fd not set).
See also:
fdwait

int Dv::Util::fdstreambuf::fdwait bool  output,
int &  syserrno
const [protected]
 

Wait for I/O to become available.

Wait for output or input, depending on the value of the parameter.

Parameters:
output Wait for output to be available if
syserrno System errorno (output variable).
Returns:
1 if input is available, 0 if a timeout occurred; -1 indicates an error condition (e.g. underlying fd not set).
See also:
fdwait

int Dv::Util::fdstreambuf::iwait  )  const [inline, protected]
 

Wait for input to become available.

Equivalent to fdwait(0).

Returns:
1 if input is available, 0 if a timeout occurred; -1 indicates an error condition (e.g. underlying fd not set).
Definition at line 240 of file fdstreambuf.h.

References fdwait().

int Dv::Util::fdstreambuf::owait  )  const [inline, protected]
 

Wait for output to become available.

Equivalent to fdwait(0).

Returns:
1 if input is available, 0 if a timeout occurred; -1 indicates an error condition (e.g. underlying fd not set).
Definition at line 248 of file fdstreambuf.h.

References fdwait().

virtual int Dv::Util::fdstreambuf::read char *  buf,
size_t  buf_sz
[protected, virtual]
 

Attempt an input operation.

Parameters:
buf Buffer where characters read will be put.
buf_sz Number of characters to read.
Returns:
number of chars read, 0 on EOF, -1 if timeout, -2 if other error.
On timeout, error() is set to ETIMEDOUT. Input operations are retried if they were interrupted.

See also:
error()

virtual int Dv::Util::fdstreambuf::write char *  buf,
size_t  buf_sz
[protected, virtual]
 

Attempt an output operation.

Parameters:
buf Buffer containing characters to write.
buf_sz Number of characters to write from buf.
Returns:
number of chars written, 0 on EOF, -1 if timeout, -2 if other error. On timeout, error() is set to ETIMEDOUT. Output operations are retried if they were interrupted.
See also:
error()

virtual int Dv::Util::fdstreambuf::rread char *  buf,
size_t  len
[protected, virtual]
 

Low level read function, default is ::read(fd(), buf, len); may set error().

Derived classes can override this function.

Parameters:
buf Buffer where characters read will be put.
len Number of characters to read.
Returns:
number of chars read, 0 on EOF, -1 on error.
See also:
error()

virtual int Dv::Util::fdstreambuf::rwrite char *  buf,
size_t  len
[protected, virtual]
 

Low level write function, default is ::write(fd(), buf, len); may set error().

Derived classes can override this function.

Parameters:
buf Buffer containing characters to write.
len Number of characters to write from buf.
Returns:
number of chars read, 0 means no chars were written. On error, -1 is returned.
See also:
error()

int Dv::Util::fdstreambuf::flags std::ios::openmode  mode  )  [static, protected]
 

Translate ios::openmode flags to open(2) flags like O_RDWR etc.

Parameters:
mode Stream open mode.
Returns:
A combination of O_RDWR, O_CREAT, O_APPEND, O_WRONLY, O_TRUNC, O_RDONLY.
Currently, the function understands combinations with ios::in, ios::out, ios::app, ios::trunc.

void Dv::Util::fdstreambuf::error int  e  )  const [protected]
 

Set error status of fdstreambuf.

Parameters:
e new error code.
See also:
fdstreambuf::error().

fdstreambuf& Dv::Util::fdstreambuf::operator= const fdstreambuf  )  [private]
 

std::string Dv::Util::fdstreambuf::debug_header const std::string &  funname  )  const [private]
 

Return string of the form ``fdstreambuf[fd]::function_name''.

Parameters:
funname Name to put after ``::''.
Returns:
A string of the form ``fdstreambuf[fd]::function_name'' where fd is value of fd().


Member Data Documentation

int Dv::Util::fdstreambuf::fd_ [private]
 

Underlying file descriptor, <0 if invalid.

Definition at line 332 of file fdstreambuf.h.

Referenced by fd().

time_t Dv::Util::fdstreambuf::delay_ [private]
 

The number of millsecs to wait before an open or input operation fails.

A value of 0 means wait forever. Definition at line 337 of file fdstreambuf.h.

Referenced by delay().

bool Dv::Util::fdstreambuf::non_blocking_ [private]
 

Whether fd_ is non-blocking.

Definition at line 341 of file fdstreambuf.h.

Referenced by non_blocking().

size_t Dv::Util::fdstreambuf::inbuf_sz_ [private]
 

Size of internal input buffer.

Definition at line 345 of file fdstreambuf.h.

Referenced by inbuf_sz().

size_t Dv::Util::fdstreambuf::outbuf_sz_ [private]
 

Size of internal output buffer.

Definition at line 349 of file fdstreambuf.h.

Referenced by outbuf_sz().

char* Dv::Util::fdstreambuf::inbuf_ [private]
 

Input buffer.

Definition at line 353 of file fdstreambuf.h.

char* Dv::Util::fdstreambuf::outbuf_ [private]
 

Output buffer.

Definition at line 357 of file fdstreambuf.h.

int Dv::Util::fdstreambuf::errno_ [mutable, private]
 

Error status.

A value of 0 means ok. Usually, the value of the last ::errno as set by the system. Definition at line 362 of file fdstreambuf.h.

Referenced by error().

bool Dv::Util::fdstreambuf::timedout_ [mutable, private]
 

Error status.

A value of 0 means ok. Usually, the value of the last ::errno as set by the system. Definition at line 367 of file fdstreambuf.h.

std::ostream* Dv::Util::fdstreambuf::debug_ [private]
 

Pointer to stream to which debug info is to be written.

If 0, no debug information is generated. Definition at line 372 of file fdstreambuf.h.

Referenced by debug().


The documentation for this class was generated from the following file:
dvutil-0.13.15 [30 December, 2004]