Byte-oriented devices. More...

#include <wfio/type.h>
#include <stdarg.h>

Classes
struct	wfio_device_vtable_t
	The virtual table for a wfio_device_t. More...

struct	wfio_device_t
	A simple, byte-oriented channel. More...

class	wfio::Device
	A C++ wrapper for a wfio_device_t. More...

class	wfio::Device::CXXStrategy
	A strategy for a device. More...

Namespaces
	wfio
	The root namespace for WFIO.

Typedefs
typedef WFIO_C_BEGIN struct wfio_device_vtable_t	wfio_device_vtable_t
	The virtual table for a wfio_device_t. More...

typedef enum wfio_device_flag_t	wfio_device_flag_t
	Flags applying to a device.

typedef struct wfio_device_t	wfio_device_t
	A simple, byte-oriented channel.

Enumerations
enum	wfio_device_flag_t { WFIO_DEVICE_CLASSIFIED = 0x1, WFIO_DEVICE_READABLE = 0x2, WFIO_DEVICE_WRITABLE = 0x4, WFIO_DEVICE_SEEKABLE = 0x8, WFIO_DEVICE_NONBLOCK = 0x10, WFIO_DEVICE_RESERVED = 0x800, WFIO_DEVICE_USRBASE = 0x1000, WFIO_DEVICE_READWRITE }
	Flags applying to a device. More...

Functions
WFIO_DLL wfio_device_t *	wfio_device_from_voidp (const wfio_device_vtable_t vtable, void data, int *error)
	Open a new device from a VTable and a void pointer representing the implementation. More...

WFIO_DLL wfio_device_t *	wfio_device_from_int (const wfio_device_vtable_t vtable, int data, int error)
	Open a new device from a VTable and an integral handle representing the implementation. More...

WFIO_DLL_FASTCALL wfio_device_t *	wfio_device_ioshare (wfio_device_t *dev, int ioshare)
	Share this device with the supplied `ioshare` mode. More...

WFIO_ALWAYS_INLINE int	wfio_device_acquire (wfio_device_t *dev)
	Share this device by acquiring it. More...

WFIO_DLL void	wfio_device_close (wfio_device_t *dev)
	Close the supplied device. More...

WFIO_DLL int	wfio_device_forceClassify (wfio_device_t *dev)
	Deduce the appropriate flags for this device if they have not already been set. More...

WFIO_INLINE int	wfio_device_classify (wfio_device_t *dev)
	Conditionally classify a device.

WFIO_INLINE size_t	wfio_device_read (wfio_device_t dev, void buf, size_t sz, size_t elem)
	Read from the supplied device. More...

WFIO_INLINE size_t	wfio_device_readbV (wfio_device_t dev, void buf, size_t len)
	Read a vector of bytes from the supplied device. More...

WFIO_INLINE int	wfio_device_readb (wfio_device_t *dev)
	Read a single byte from the supplied device. More...

WFIO_INLINE size_t	wfio_device_write (wfio_device_t dev, const void buf, size_t sz, size_t elem)
	Write to the supplied device. More...

WFIO_INLINE size_t	wfio_device_writebV (wfio_device_t dev, const void buf, size_t len)
	Write a vector of bytes to the supplied device. More...

WFIO_INLINE size_t	wfio_device_writeb (wfio_device_t *dev, char c)
	Write a single byte to the supplied device. More...

WFIO_INLINE int	wfio_device_seek (wfio_device_t *dev, wfio_off_t offset, wfio_whence_t whence)
	Seek to a position in the stream. More...

WFIO_INLINE int	wfio_device_canSeek (wfio_device_t *dev)
	Determine whether or not this device is capable of seeking. More...

WFIO_INLINE wfio_off_t	wfio_device_tell (wfio_device_t *dev)
	Determine the current stream position of this device. More...

WFIO_INLINE wfio_device_t *	wfio_device_dup (wfio_device_t *dev)
	Duplicate this device. More...

WFIO_INLINE size_t	wfio_device_setbufsz (wfio_device_t *dev, size_t sz)
	Set the buffer size. More...

WFIO_INLINE size_t	wfio_device_getbufsz (wfio_device_t *dev)
	Obtain the buffer size. More...

WFIO_ALWAYS_INLINE int	wfio_device_isBuffered (wfio_device_t *dev)
	Determine whether or not the device is buffered. More...

WFIO_INLINE int	wfio_device_flush (wfio_device_t *dev)
	Attempt to flush this device. More...

WFIO_DLL int	wfio_device_vdcntl (wfio_device_t *dev, wfio_dcntl_t cmd, va_list va)
	Perform device-independent I/O control on this device using a va_list. More...

WFIO_INLINE int	wfio_device_dcntl (wfio_device_t *dev, wfio_dcntl_t cmd,...)
	Perform device-independent I/O control on this device. More...

WFIO_DLL int	wfio_device_vioctl (wfio_device_t *dev, int cmd, va_list va)
	Perform device-dependent I/O control on this device. More...

WFIO_INLINE int	wfio_device_ioctl (wfio_device_t *dev, int cmd,...)
	Perform device-dependent I/O control on this device. More...

WFIO_DLL int	wfio_device_sink (wfio_device_t src, wfio_device_t dest, size_t *copied)
	Copy the contents of the device `src` into `dest`. More...

WFIO_DLL_FASTCALL size_t	wfio_device_readbuf (wfio_device_t dev, struct wfio_iobuf_t buf)
	Read the contents of the device `dev` into `buf`. More...

WFIO_DLL_FASTCALL size_t	wfio_device_writebuf (wfio_device_t dev, struct wfio_iobuf_t buf)
	Write the contents of the buffer `buf` into `dev`. More...

WFIO_ALWAYS_INLINE wfio_fd_t	wfio_device_getfd (wfio_device_t *dev)
	Obtain the file descriptor for this device. More...

WFIO_ALWAYS_INLINE int	wfio_device_setflags (wfio_device_t *dev, int flags)
	Set the flags for this device. More...

WFIO_ALWAYS_INLINE int	wfio_device_getflags (wfio_device_t *dev)
	Obtain the flags for this device. More...

WFIO_ALWAYS_INLINE int	wfio_device_truncate (wfio_device_t *dev, size_t len)
	Truncate the file to the specified length. More...

Detailed Description

Byte-oriented devices.

Author: Phillip Kilgore

Since: 0.0.1

Typedef Documentation

◆ wfio_device_vtable_t

typedef WFIO_C_BEGIN struct wfio_device_vtable_t wfio_device_vtable_t

The virtual table for a wfio_device_t.

This structure facilitates dynamic dispatch for a wfio_device_t. Each callback serves to service one the methods of the wfio_device_t and is assumed.

Precondition: Each entry in the vtable must point to a valid callback.

Postcondition: The corresponding callback will be invoked when a device's method is called.

Enumeration Type Documentation

◆ wfio_device_flag_t

enum wfio_device_flag_t

Flags applying to a device.

Enumerator
WFIO_DEVICE_CLASSIFIED	The device flags were set.
WFIO_DEVICE_READABLE	The device may be read.
WFIO_DEVICE_WRITABLE	The device may be written.
WFIO_DEVICE_SEEKABLE	The device is allowed to seek.
WFIO_DEVICE_NONBLOCK	This device is nonblocking.
WFIO_DEVICE_RESERVED	The device is reserved by WFIO or some other library and should not have its device handle freed.
WFIO_DEVICE_USRBASE	A device-specific flag. This function shall refer to the first unallocated flag which may be used by the device for its own internal bookkeeping.
WFIO_DEVICE_READWRITE	The device is both readable and writable.

Function Documentation

◆ wfio_device_acquire()

WFIO_ALWAYS_INLINE int wfio_device_acquire ( wfio_device_t * dev )

Share this device by acquiring it.

This function increases the reference count on the device to indicate that the device has been shared. A successful call to wfio_device_acquire() should be followed by a corresponding call to wfio_device_close() to later release it.

Returns: Whether or not the device could be successfully acquired.

Warning: This function must eventually be followed by a call to wfio_device_close() or resources will leak.

◆ wfio_device_canSeek()

WFIO_INLINE int wfio_device_canSeek ( wfio_device_t * dev )

Determine whether or not this device is capable of seeking.

Parameters

dev	The device to interrogate.

Returns: Nonzero if this device can seek; otherwise, 0.

◆ wfio_device_close()

WFIO_DLL void wfio_device_close ( wfio_device_t * dev )

Close the supplied device.

This function decrements the reference count of dev. If the reference count is then zero, then the device is closed; if its classification does not include WFIO_DEVICE_RESERVED, then the memory associated with the device is also freed.

Parameters

dev	The device to close.

◆ wfio_device_dcntl()

WFIO_INLINE int wfio_device_dcntl	(	wfio_device_t *	dev,
		wfio_dcntl_t	cmd,
			...
	)

Perform device-independent I/O control on this device.

Parameters

dev	The device to dcntl.
cmd	The command to send to the device.
...	Additional arguments to the dcntl.

This function performs standardized I/O control on this device. If the command is not supported, then this device's ecode is set to WFIO_E_NOIMPL; otherwise, the command is performed according to its description in wfio_dcntl_t.

Returns: A return value peculiar to the command invoked.

Note: This method sets ecode.; It is not sufficient to look at the return value from this function to determine failure because the return value is dependent on the dcntl command. Instead, check he value of ecode; if the value is WFIO_E_SUCCESS, then no error has occurred.; If NULL is passed, zero shall be returned.

◆ wfio_device_dup()

WFIO_INLINE wfio_device_t* wfio_device_dup ( wfio_device_t * dev )

Duplicate this device.

Parameters

dev	The device to duplicate.

Returns: A new device on success; otherise NULL;

Note: This method may set ecode.

◆ wfio_device_flush()

WFIO_INLINE int wfio_device_flush ( wfio_device_t * dev )

Attempt to flush this device.

If this device is unbuffered, do nothing. Otherwise, the contents of the buffer are written to

Parameters

dev	The device to flush.

Returns: Nonzero on success; otherwise, zero.

Note: This method may set ecode.

◆ wfio_device_forceClassify()

WFIO_DLL int wfio_device_forceClassify ( wfio_device_t * dev )

Deduce the appropriate flags for this device if they have not already been set.

This function attempts to classify its present capabilities.

Parameters

dev	The device to classify.

Returns: Whether or not the device could be classified.

◆ wfio_device_from_int()

WFIO_DLL wfio_device_t* wfio_device_from_int	(	const wfio_device_vtable_t *	vtable,
		int	data,
		int *	error
	)

Open a new device from a VTable and an integral handle representing the implementation.

Warning: This function must eventually be followed by a call to wfio_device_close() or resources will leak.

◆ wfio_device_from_voidp()

WFIO_DLL wfio_device_t* wfio_device_from_voidp	(	const wfio_device_vtable_t *	vtable,
		void *	data,
		int *	error
	)

Open a new device from a VTable and a void pointer representing the implementation.

Warning: This function must eventually be followed by a call to wfio_device_close() or resources will leak.

◆ wfio_device_getbufsz()

WFIO_INLINE size_t wfio_device_getbufsz ( wfio_device_t * dev )

Obtain the buffer size.

Parameters

dev	The device to interrogate.

Returns: The size of the buffer associated with this device on success; otherwise, WFIO_NPOS. A return value of zero shall indicate that the device is unbuffered.

Note: This method may set ecode.

◆ wfio_device_getfd()

WFIO_ALWAYS_INLINE wfio_fd_t wfio_device_getfd ( wfio_device_t * dev )

Obtain the file descriptor for this device.

This function is synonymous with wfio_device_dcntl(dev, WFIO_DCTNL_GETFD).

Parameters

dev	The device to interrogate.

Returns: The file descriptor on success; otherwise, WFIO_BAD_FD.

◆ wfio_device_getflags()

WFIO_ALWAYS_INLINE int wfio_device_getflags ( wfio_device_t * dev )

Obtain the flags for this device.

This function is synonymous with wfio_device_dcntl(dev, WFIO_DCTNL_GETFLAGS).

Parameters

dev	The device to interrogate.

Returns: Nonzero on success; otherwise, zero.

◆ wfio_device_ioctl()

WFIO_INLINE int wfio_device_ioctl	(	wfio_device_t *	dev,
		int	cmd,
			...
	)

Perform device-dependent I/O control on this device.

This function performs operations peculiar to the device. The cmd parameter shall accept an integer command name which is specific to the device, but shall set WFIO_E_NOIMPL if the command is not recognized.

Parameters

dev	The device to ioctl.
cmd	The command to send to the device.
...	Additional arguments to the ioctl.

Returns: A return value peculiar to the command invoked.

Note: This method sets ecode.; It is not sufficient to look at the return value from this function to determine failure because the return value is dependent on the dcntl command. Instead, check he value of ecode; if the value is WFIO_E_SUCCESS, then no error has occurred.

◆ wfio_device_ioshare()

WFIO_DLL_FASTCALL wfio_device_t* wfio_device_ioshare	(	wfio_device_t *	dev,
		int	ioshare
	)

Share this device with the supplied ioshare mode.

Parameters

dev	The device to share.
ioshare	The ioshare mode.

This function allows for the device to be shared in the specified manner.

Returns: The shared instance of this device.

Warning: If WFIO_IOSHARE_O_ACQUIRE or WFIO_IOSHARE_DUP is specified, then the resulting device must be matched with a corresponding call to wfio_device_close() or resources will leak.

◆ wfio_device_isBuffered()

WFIO_ALWAYS_INLINE int wfio_device_isBuffered ( wfio_device_t * dev )

Determine whether or not the device is buffered.

Parameters

dev	The device to interrogate.

Returns: Nonzero if the device is buffered; otherwise, zero.

Note: When the buffer size if WFIO_NPOS, this function will claim that the device is buffered. This is done because flushing does not adversely affect the operation of the stream if the; This method may set ecode.

◆ wfio_device_read()

WFIO_INLINE size_t wfio_device_read	(	wfio_device_t *	dev,
		void *	buf,
		size_t	sz,
		size_t	elem
	)

Read from the supplied device.

Parameters

dev	The device to read from.
buf	The buffer to read into.
sz	The size of each element to read.
elem	The number of elements to read.

Returns: The number of elements actually read on success; otherwise, WFIO_NPOS.

Note: This method may set ecode.

◆ wfio_device_readb()

WFIO_INLINE int wfio_device_readb ( wfio_device_t * dev )

Read a single byte from the supplied device.

Parameters

dev	The device to read from.

Returns: The value of the byte read on success; otherwise, WFIO_NPOS.

Note: This method may set ecode.

◆ wfio_device_readbuf()

WFIO_DLL_FASTCALL size_t wfio_device_readbuf	(	wfio_device_t *	dev,
		struct wfio_iobuf_t *	buf
	)

Read the contents of the device dev into buf.

Parameters

dev	The device to read from.
buf	The buffer to read into.

Returns: The number of bytes read on success; otherwise, WFIO_NPOS.

◆ wfio_device_readbV()

WFIO_INLINE size_t wfio_device_readbV	(	wfio_device_t *	dev,
		void *	buf,
		size_t	len
	)

Read a vector of bytes from the supplied device.

Parameters

dev	The device to read from.
buf	The buffer to read into.
len	The maximum number of bytes to read.

Returns: The number of bytes actually read on success; otherwise, WFIO_NPOS.

Note: This method may set ecode.

◆ wfio_device_seek()

WFIO_INLINE int wfio_device_seek	(	wfio_device_t *	dev,
		wfio_off_t	offset,
		wfio_whence_t	whence
	)

Seek to a position in the stream.

This method attempts to seek the device to the specified position. This is only successful if the device is open and seekable.

Parameters

dev	The device to seek.
offset	The offset relative to `whence` to seek to.
whence	The origin added to `whence` to seek to.

Returns: Zero on success; otherwise, nonzero.

Note: This method may set ecode.

◆ wfio_device_setbufsz()

WFIO_INLINE size_t wfio_device_setbufsz	(	wfio_device_t *	dev,
		size_t	sz
	)

Set the buffer size.

This function sets the size of the underlying buffer belonging to dev if it supports this behavior. The device itself is not required to change the size of the buffer to sz; if it changes it to a different size, If for some reason this operation fails or is unsupported, then it shall return WFIO_NPOS and the buffer size shall remain unchanged.

Parameters

dev	The device to set the buffer size for.
sz	The requested size to set.

Returns: The size of the buffer after this operation; otherwise, WFIO_NPOS. A return value of zero shall indicate that device is unbuffered.

Note: When the buffer size is immutable or the device cannot be buffered, but is otherwise known, then the size of the buffer is returned.; This method may set ecode.

◆ wfio_device_setflags()

WFIO_ALWAYS_INLINE int wfio_device_setflags	(	wfio_device_t *	dev,
		int	flags
	)

Set the flags for this device.

This function is synonymous with wfio_device_dcntl(dev, WFIO_DCTNL_SETFLAGS, flags).

Parameters

dev	The device to modify.
flags	The desired flags.

Returns: Nonzero on success; otherwise, zero.

◆ wfio_device_sink()

WFIO_DLL int wfio_device_sink	(	wfio_device_t *	src,
		wfio_device_t *	dest,
		size_t *	copied
	)

Copy the contents of the device src into dest.

This function "sinks" the remaining contents of the device src into the device dest.

Parameters

src	The device to copy from.
dest	The device to copy to.

Returns: Nonzero on success; otherwise, zero.

Note: This method may set ecode.

◆ wfio_device_tell()

WFIO_INLINE wfio_off_t wfio_device_tell ( wfio_device_t * dev )

Determine the current stream position of this device.

Parameters

dev	The device to interrogate.

Returns: The current stream position of the device on success; otherwise, WFIO_NPOS.

Note: This method may set ecode.

◆ wfio_device_truncate()

WFIO_ALWAYS_INLINE int wfio_device_truncate	(	wfio_device_t *	dev,
		size_t	len
	)

Truncate the file to the specified length.

This function is synonymous with wfio_device_dcntl(dev, WFIO_DCTNL_TRUNCATE, len).

Parameters

dev	The device to truncate.
len	The length to truncate to.

Returns: Nonzero on success; otherwise, zero.

◆ wfio_device_vdcntl()

WFIO_DLL int wfio_device_vdcntl	(	wfio_device_t *	dev,
		wfio_dcntl_t	cmd,
		va_list	va
	)

Perform device-independent I/O control on this device using a va_list.

This function is like wfio_device_dcntl(), except it accepts a va_list instead of an elipsis.

Parameters

dev	The device to dcntl.
cmd	The command to send to the device.
va	Additional arguments to the dcntl.

Note: This method sets ecode.; It is not sufficient to look at the return value from this function to determine failure because the return value is dependent on the dcntl command. Instead, check he value of ecode; if the value is WFIO_E_SUCCESS, then no error has occurred.; If NULL is passed, zero shall be returned.

◆ wfio_device_vioctl()

WFIO_DLL int wfio_device_vioctl	(	wfio_device_t *	dev,
		int	cmd,
		va_list	va
	)

Perform device-dependent I/O control on this device.

This function is like wfio_device_ioctl(), except it accepts a va_list instead of an elipsis.

Parameters

dev	The device to ioctl.
cmd	The command to send to the device.
...	Additional arguments to the ioctl.

Returns: A return value peculiar to the command invoked.

Note: This method sets ecode.; It is not sufficient to look at the return value from this function to determine failure because the return value is dependent on the dcntl command. Instead, check he value of ecode; if the value is WFIO_E_SUCCESS, then no error has occurred.

◆ wfio_device_write()

WFIO_INLINE size_t wfio_device_write	(	wfio_device_t *	dev,
		const void *	buf,
		size_t	sz,
		size_t	elem
	)

Write to the supplied device.

Parameters

dev	The device to write to.
buf	The buffer to write from.
sz	The size of each elements.
sz	The maximum number of elements to write.

Returns: The number of elements actually written on success; otherwise, WFIO_NPOS.

Note: This method may set ecode.

◆ wfio_device_writeb()

WFIO_INLINE size_t wfio_device_writeb	(	wfio_device_t *	dev,
		char	c
	)

Write a single byte to the supplied device.

Parameters

dev	The device to write to.
c	The byte to write.

Returns: Nonzero if written; otherwise, zero.

Note: This method may set ecode.

◆ wfio_device_writebuf()

WFIO_DLL_FASTCALL size_t wfio_device_writebuf	(	wfio_device_t *	dev,
		struct wfio_iobuf_t *	buf
	)

Write the contents of the buffer buf into dev.

Parameters

dev	The device to write into.
buf	The buffer to write from.

Returns: The number of bytes written on success; otherwise, WFIO_NPOS.

◆ wfio_device_writebV()

WFIO_INLINE size_t wfio_device_writebV	(	wfio_device_t *	dev,
		const void *	buf,
		size_t	len
	)

Write a vector of bytes to the supplied device.

Parameters

dev	The device to write to.
buf	The buffer to write from.
len	The maximum number of bytes to write.

Returns: The number of bytes actually written on success; otherwise, WFIO_NPOS.

Note: This method may set ecode.

Classes

Namespaces

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ wfio_device_vtable_t

Enumeration Type Documentation

◆ wfio_device_flag_t

Function Documentation

◆ wfio_device_acquire()

◆ wfio_device_canSeek()

◆ wfio_device_close()

◆ wfio_device_dcntl()

◆ wfio_device_dup()

◆ wfio_device_flush()

◆ wfio_device_forceClassify()

◆ wfio_device_from_int()

◆ wfio_device_from_voidp()

◆ wfio_device_getbufsz()

◆ wfio_device_getfd()

◆ wfio_device_getflags()

◆ wfio_device_ioctl()

◆ wfio_device_ioshare()

◆ wfio_device_isBuffered()

◆ wfio_device_read()

◆ wfio_device_readb()

◆ wfio_device_readbuf()

◆ wfio_device_readbV()

◆ wfio_device_seek()

◆ wfio_device_setbufsz()

◆ wfio_device_setflags()

◆ wfio_device_sink()

◆ wfio_device_tell()

◆ wfio_device_truncate()

◆ wfio_device_vdcntl()

◆ wfio_device_vioctl()

◆ wfio_device_write()

◆ wfio_device_writeb()

◆ wfio_device_writebuf()

◆ wfio_device_writebV()