Chapter 7
Input/Output Interfaces

This chapter defines the I/O-related COM interfaces which are defined by header files in the oskit/io directory. Most of these interfaces are fairly generic and can be used in a wide variety of situations. Some of these interfaces, such as the bufio interface, are extensions to other more primitive interfaces, and allow objects to export the same functionality in different forms, permitting clients to select the service that most directly meets their needs thereby reducing interface crossing overhead and increasing overall performance.

7.1 oskit_absio: Absolute I/O Interface

The oskit_absio interface supports reading from and writing to objects at specified absolute offsets, with no concept of a seek pointer. The oskit_absio interface is identical to the oskit_blkio COM interface, except that the block size is always one, since absolute IO is byte-oriented. In fact, an object that supports byte-granularity reads and writes can easily export both oskit_blkio and oskit_absio using exactly the same function pointer table, simply by implementing an oskit_blkio interface that always returns one from getblocksize, and then returning a pointer to that interface on queries for either oskit_blkio or oskit_absio.

The oskit_absio COM interface inherits from IUnknown, and has the following additional methods:

read:
Read from this object, starting at the specified offset.
write:
Write to this object, starting at the specified offset.
getsize:
Get the current size of this object.
setsize:
Set the current size of this object.

7.1.1 read: Read from this object, starting at specified offset

SYNOPSIS

#include <oskit/io/absio.h>

OSKIT_COMDECL oskit_absio_read(oskit_absio_t *f, void *buf, oskit_off_t offset, oskit_size_t amount, [out] oskit_size_t *out_actual);

DESCRIPTION

This method reads no more than amount bytes into buf from this object, starting at offset. out_actual is set to the actual number of bytes read.

PARAMETERS
f :
The object from which to read.
buf :
The buffer into which the data is to be copied.
offset:
The offset in this object at which to start reading.
amount:
The maximum number of bytes to read.
out_actual:
The actual number of bytes read.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.1.2 write: Write to this object, starting at specified offset

SYNOPSIS

#include <oskit/io/absio.h>

OSKIT_COMDECL oskit_absio_write(oskit_absio_t *f, const void *buf, oskit_off_t offset, oskit_size_t amount, [out] oskit_size_t *out_actual);

DESCRIPTION

This method writes no more than amount bytes from buf into this object, starting at offset. out_actual is set to the actual number of bytes written.

PARAMETERS
f :
The object to which to write.
buf :
The buffer from which the data is to be copied.
offset:
The offset in this object at which to start writing.
amount:
The maximum number of bytes to write.
out_actual:
The actual number of bytes written.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.1.3 getsize: Get the size of this object

SYNOPSIS

#include <oskit/io/absio.h>

OSKIT_COMDECL oskit_absio_getsize(oskit_absio_t *f, [out] oskit_off_t *out_size);

DESCRIPTION

This method returns the current size of this object in bytes.

PARAMETERS
f :
The object whose size is desired.
out_size:
The current size in bytes of this object.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.1.4 setsize: Set the size of this object

SYNOPSIS

#include <oskit/io/absio.h>

OSKIT_COMDECL oskit_absio_setsize(oskit_absio_t *f, oskit_off_t new_size);

DESCRIPTION

This method sets the size of this object to new_size bytes. If new_size is larger than the former size of this object, then the contents of the object between its former end and its new end are undefined.

Note that some absolute I/O objects may be fixed-size, such as objects representing preallocated memory buffers; in such cases, this method will always return OSKIT_E_NOTIMPL.

PARAMETERS
f :
The object whose size is to be changed.
new_size:
The new size in bytes for this object.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.2 oskit_asyncio: Asynchronous I/O Interface

The oskit_asyncio interface provides interfaces in support of basic asynchronous I/O, based on registered callback objects (see Section 4.9). This can be used, for example, to implement Unix SIGIO or select or POSIX.1b aio.

This interface supports a notion of three kinds of interesting events: readability, writeability, and “other” exceptional conditions. These are defined via the flags: OSKIT_ASYNCIO_READABLE, OSKIT_ASYNCIO_WRITEABLE, and OSKIT_ASYNCIO_EXCEPTION which are passed and returned in a mask in the various methods.

The oskit_asyncio COM interface inherits from IUnknown, and has the following additional methods:

poll:
Poll for currently pending asynchronous I/O conditions.
add_listener:
Add a callback object for async I/O events.
remove_listener:
Remove a previously registered callback object.
readable:
Returns the number of bytes that can be read.

7.2.1 poll: Poll for pending asynchronous I/O conditions on this object

SYNOPSIS

#include <oskit/io/asyncio.h>

OSKIT_COMDECL oskit_asyncio_poll(oskit_asyncio_t *io);

DESCRIPTION

Poll for currently pending asynchronous I/O conditions, returning a mask indicating which conditions are currently present.

PARAMETERS
io:
The async I/O object.
RETURNS

If successful, returns a mask of the OSKIT_ASYNCIO flags above. Otherwise, returns an error code specified in <oskit/error.h>.

7.2.2 add_listener: Associate a callback with this object

SYNOPSIS

#include <oskit/io/asyncio.h>

OSKIT_COMDECL oskit_asyncio_add_listener(oskit_asyncio_t *io, oskit_listener_t *l, oskit_s32_t mask);

DESCRIPTION

Add a callback listener object to handle asynchronous I/O events. When an event of interest occurs on this I/O object (i.e., when one of the one to three I/O conditions becomes true), all registered listeners will be called.

The mask parameter is an OR’ed combination of the OSKIT_ASYNCIO flags above. It specifies which events the listener is interested in. Note that spurious notifications are possible, the listener must use oskit_asyncio_poll to determine the actual state of affairs.

Also, if successful, this method returns a mask describing which of the OSKIT_ASYNCIO conditions are already true, which the caller must check in order to avoid missing events that occur just before the listener is registered.

PARAMETERS
io:
The async I/O object.
l:
The oskit_listener object to call.
mask:
A mask of flags indicating which events are of interest.
RETURNS

If successful, returns a mask of the OSKIT_ASYNCIO currently pending. Otherwise, returns an error code specified in <oskit/error.h>.

7.2.3 remove_listener: Disassociate a callback from this object

SYNOPSIS

#include <oskit/io/asyncio.h>

OSKIT_COMDECL oskit_asyncio_remove_listener(oskit_asyncio_t *io, oskit_listener_t *l);

DESCRIPTION

Remove a previously registered listener callback object. Returns an error if the specified callback has not been registered.

PARAMETERS
io:
The async I/O object.
l:
The oskit_listener object to call.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.2.4 readable: Return the number of bytes available for reading from this object

SYNOPSIS

#include <oskit/io/asyncio.h>

OSKIT_COMDECL oskit_asyncio_readable(oskit_asyncio_t *io);

DESCRIPTION

Returns the number of bytes that can be read from the I/O object.

PARAMETERS
io:
The async I/O object.
RETURNS

The number of bytes available for reading.

7.3 oskit_blkio: Block I/O Interface

The oskit_blkio interface supports reading and writing of raw data in units of fixed-sized blocks which are some power of two. This interface is identical to the oskit_absio interface except for the addition of a getblocksize method; in fact, an object that supports byte-granularity reads and writes can easily export both oskit_blkio and oskit_absio using exactly the same function pointer table, simply by implementing an oskit_blkio interface that always returns one from getblocksize, and then returning a pointer to that interface on queries for either oskit_blkio or oskit_absio.

The oskit_blkio interface inherits from IUnknown, and has the following additional methods:

getblocksize:
Return the minimum block size of this block I/O object.
read:
Read from this object, starting at the specified offset.
write:
Write to this object, starting at the specified offset.
getsize:
Get the current size of this object.
setsize:
Set the current size of this object.

7.3.1 getblocksize: Return the minimum block size of this block I/O object

SYNOPSIS

#include <oskit/io/blkio.h>

OSKIT_COMDECL_U oskit_blkio_getblocksize(oskit_blkio_t *f);

DESCRIPTION

This method simply returns the block size of the object, which must be a power of two. Calls by the client to read from or write to the object must only use offsets and sizes that are evenly divisible by this block size.

PARAMETERS
f :
The block I/O object.
RETURNS

Returns the block size of the object.

7.3.2 read: Read from this object, starting at specified offset

SYNOPSIS

#include <oskit/io/blkio.h>

OSKIT_COMDECL oskit_blkio_read(oskit_blkio_t *f, void *buf, oskit_off_t offset, oskit_size_t amount, [out] oskit_size_t *out_actual);

DESCRIPTION

This method reads no more than amount bytes into buf from this object, starting at offset. out_actual is set to the actual number of bytes read.

PARAMETERS
f :
The object from which to read.
buf :
The buffer into which the data is to be copied.
offset:
The offset in this object at which to start reading. Must be a multiple of the object’s block size.
amount:
The maximum number of bytes to read. Must be a multiple of the object’s block size.
out_actual:
The actual number of bytes read. Must be a multiple of the object’s block size.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.3.3 write: Write to this object, starting at specified offset

SYNOPSIS

#include <oskit/io/blkio.h>

OSKIT_COMDECL oskit_blkio_write(oskit_blkio_t *f, const void *buf, oskit_off_t offset, oskit_size_t amount, [out] oskit_size_t *out_actual);

DESCRIPTION

This method writes no more than amount bytes from buf into this object, starting at offset. out_actual is set to the actual number of bytes written.

PARAMETERS
f :
The object to which to write.
buf :
The buffer from which the data is to be copied.
offset:
The offset in this object at which to start writing. Must be a multiple of the object’s block size.
amount:
The maximum number of bytes to write. Must be a multiple of the object’s block size.
out_actual:
The actual number of bytes written. Must be a multiple of the object’s block size.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.3.4 getsize: Get the size of this object

SYNOPSIS

#include <oskit/io/blkio.h>

OSKIT_COMDECL oskit_blkio_getsize(oskit_blkio_t *f, [out] oskit_off_t *out_size);

DESCRIPTION

This method returns the current size of this object in bytes.

PARAMETERS
f :
The object whose size is desired.
out_size:
The current size in bytes of this object. Must be a multiple of the object’s block size.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.3.5 setsize: Set the size of this object

SYNOPSIS

#include <oskit/io/blkio.h>

OSKIT_COMDECL oskit_blkio_setsize(oskit_blkio_t *f, oskit_off_t new_size);

DESCRIPTION

This method sets the size of this object to new_size bytes. If new_size is larger than the former size of this object, then the contents of the object between its former end and its new end are undefined.

Note that some block I/O objects may be fixed-size, such as objects representing physical disks or partitions; in such cases, this method will always return OSKIT_E_NOTIMPL.

PARAMETERS
f :
The object whose size is to be changed.
new_size:
The new size in bytes for this object. Must be a multiple of the object’s block size.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.4 oskit_bufio: Buffer-based I/O interface

The oskit_bufio interface extends the oskit_absio interface, providing additional alternative methods of accessing the object’s data. In particular, for objects whose data is stored in an in-memory buffer of some kind, this interface allows clients to obtain direct access to the buffer itself so that they can read and write data using loads and stores, rather than having to copy data into and out of the buffer using the read and write methods. In addition, this interface provides similar methods to allow clients to “wire” the buffer’s contents to physical memory, enabling DMA-based hardware devices to access the buffer directly.

However, note that only the read/write methods, inherited from oskit_absio, are mandatory; the others may consistently fail with OSKIT_E_NOTIMPL if they cannot be implemented efficiently in a particular situation. In that case, the caller must use the basic read and write methods instead to copy the data. In other words, oskit_bufio object implementations are not required to implement direct buffer access, either software- or DMA-based; the purpose of this interface is merely to allow them to provide this optional functionality easily and consistently. In general, the map and wire methods should only be implemented if they can be done more efficiently than simply copying the data. Further, even if a buffer I/O implementation does implement map and/or wire it may allow only one mapping or wiring to be in effect at once, failing if the client attempts to map or wire the buffer a second time before the first mapping is undone. Similarly, on some buffer I/O implementations, these operations may only work on certain areas of the buffer or only when the request has certain size or alignment properties: for example, a buffer object that stores data in discontiguous segments, such as BSD’s mbuf system, may only allow a buffer to be mapped if the requested region happens to fall entirely within one segment. Thus, the client of a bufio object should call the map or wire methods whenever it can take advantage of direct buffer access, but must always be prepared to fall back to the basic copying methods.

A particular buffer object may be semantically read-only or write-only; it is assumed that parties passing bufio objects around will agree upon this as part of their protocols. For a read-only buffer, the write method may or may not fail, and a mapping established using the map method may or may not actually be a read-only memory mapping; it is the client’s responsibility not to attempt to write to the buffer. Similarly, for a write-only buffer, the read method may or may not fail; it is the client’s responsibility not to attempt to read from the buffer.

The oskit_bufio interface extends the oskit_absio interface with the following additional methods:

map:
Map some or all of this buffer into locally accessible memory.
unmap:
Release a previously mapped region of this buffer.
wire:
Wire a region of this buffer into contiguous physical memory.
unwire:
Unwire a previously wired region of this buffer.
copy:
Create a copy of the specified portion of this buffer.

7.4.1 map: Map some or all of this buffer into locally accessible memory

SYNOPSIS

#include <oskit/io/bufio.h>

OSKIT_COMDECL map(oskit_bufio_t *io, [out] void **addr, oskit_off_t offset, oskit_size_t amount);

DESCRIPTION

This method attempts to map some or all of this buffer into memory directly accessible to the client, so that the client can access it using loads and stores. The operation may or may not succeed, depending on the parameters and the implementation of the object; if it fails, the client must be prepared to fall back to the basic read and write methods. If the mapping operation succeeds, the pointer returned is not guaranteed to have any particular alignment.

If a call to the map method requests only a subset of the buffer to be mapped, the object may actually map more than the requested amount; however, since no information is passed back indicating how much of the buffer was actually mapped, the client must only attempt to access the region it requested.

Note that this method does not necessarily twiddle with virtual memory, as its name may seem to imply; in fact in most cases in which it is implemented at all, it just returns a pointer to a buffer if the data is already in locally-accessible memory.

PARAMETERS
io:
The object whose contents are to be mapped.
addr:
On success, the method returns in this parameter the address at which the client can directly access the requested buffer region.
offset:
The offset into the buffer of the region to be mapped.
size:
The size of the region to be mapped.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.4.2 unmap: Release a previously mapped region of this buffer

SYNOPSIS

#include <oskit/io/bufio.h>

OSKIT_COMDECL unmap(oskit_bufio_t *io, void *addr, oskit_off_t offset, oskit_size_t amount);

DESCRIPTION

After a successful call to the map method, the client should call this method after it is finished accessing the buffer directly, so that the buffer object can clean up and free any resources that might be associated with the mapping.

The addr parameter passed to this method must be exactly the value returned by the map request, and the offset and amount parameters must be exactly the same as the values previously passed in the corresponding map call. In other words, clients must only attempt to unmap whole regions; they must not attempt to unmap only part of a region, or to unmap two previously mapped regions in one call, even if the two regions appear to be contiguous in memory.

PARAMETERS
io:
The object whose contents are to be mapped.
addr:
The address of the mapped region, as returned from the corresponding map call.
offset:
The offset into the buffer of the mapped region, as passed to the corresponding map call.
size:
The size of the mapped region, as passed to the corresponding map call.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.4.3 wire: Wire a region of this buffer into contiguous physical memory

SYNOPSIS

#include <oskit/io/bufio.h>

OSKIT_COMDECL wire(oskit_bufio_t *io, [out] oskit_addr_t *phys_addr, oskit_off_t offset, oskit_size_t amount);

DESCRIPTION

This method attempts to wire down some or all of this buffer into memory directly accessible by DMA hardware. The operation may or may not succeed, depending on the parameters and the implementation of the object; if it fails, the client must be prepared to fall back to the basic read and write methods.

If the wiring operation succeeds, the physical address of the buffer is guaranteed not to change or otherwise become invalid until the region is unwired or the bufio object is released. The wired buffer is not guaranteed to have any particular alignment or location properties: for example, on a PC, if the device that is going to be accessing the buffer requires memory below 16MB, then it must be prepared to use appropriate bounce buffers if the wired buffer turns out to be above 16MB.

If a call to the wire method requests only a subset of the buffer to be mapped, the object may actually wire more than the requested amount; however, since no information is passed back indicating how much of the buffer was actually wired, the client must only attempt to use the region it requested.

PARAMETERS
io:
The object whose contents are to be wired.
addr:
On success, the method returns in this parameter the physical address at which DMA hardware can directly access the requested buffer region.
offset:
The offset into the buffer of the region to be wired.
size:
The size of the region to be wired.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.4.4 unwire: Unwire a previously wired region of this buffer

SYNOPSIS

#include <oskit/io/bufio.h>

OSKIT_COMDECL unwire(oskit_bufio_t *io, void *addr, oskit_off_t offset, oskit_size_t amount);

DESCRIPTION

After a successful call to the wire method, the client should call this method after the hardware is finished accessing the buffer directly, so that the buffer object can clean up and free any resources that might be associated with the wiring.

The addr parameter passed to this method must be exactly the value returned by the wire request, and the offset and amount parameters must be exactly the same as the values previously passed in the corresponding wire call. In other words, clients must only attempt to unwire whole regions; they must not attempt to unwire only part of a region, or to unwire two previously wired regions in one call, even if the two regions appear to be contiguous in physical memory.

PARAMETERS
io:
The object whose contents are to be wired.
addr:
The address of the wired region, as returned from the corresponding map call.
offset:
The offset into the buffer of the wired region, as passed to the corresponding wire call.
size:
The size of the wired region, as passed to the corresponding wire call.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.4.5 copy: Create a copy of the specified portion of this buffer

SYNOPSIS

#include <oskit/io/bufio.h>

OSKIT_COMDECL copy(oskit_bufio_t *io, oskit_off_t offset, oskit_size_t amount, [out] oskit_bufio_t **out_io);

DESCRIPTION

This method attempts to create a logical copy of a portion of this buffer object (possibly the whole buffer), returning a new oskit_bufio object representing the copy. As with the map and wire methods, this method should only be implemented by an object if it can be done more efficiently than a simple “brute-force” copy using read. For example, in virtual memory environments, the object may be able to use copy-on-write optimizations. Similarly, if the buffer’s contents are stored in special memory not efficiently accessible to the processor, such as memory on a video or coprocessor board, this method could use on-board hardware to perform a much faster copy.

PARAMETERS
io:
The object whose contents are to be copied.
offset:
The offset into the buffer of the region to be copied.
size:
The size of the region to be copied.
out_io:
On success, this parameter holds the bufio object representing the newly created copy of the buffer’s contents.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.5 oskit_netio: Network packet I/O interface

This interface builds on the above interfaces to provide a clean and simple but powerful interface for passing network packets between device drivers and protocol stacks, and possibly between layers of a protocol stack as well.

The oskit_netio interface uses a symmetric sender-driven model for asynchronous communication. Each party involved (e.g., the network device driver and the protocol stack) must implement a netio object and pass a reference to its own netio object to the other party. For example, in the oskit_netdev interface, which represents a network device of some kind, this exchange of netio objects occurs when the protocol stack or other client opens the device. The oskit_netio interface defines only a single additional method beyond the basic methods inherited from oskit_iunknown; this method, appropriately named push, is used to “push” a network packet to the “other” party. For example, when a network device driver receives a packet from the hardware, the driver calls the push method on the netio object provided by the protocol stack; conversely, when the protocol stack needs to send a packet, it calls the netio object returned by the device driver at the time the device was opened. Thus, a netio object essentially represents a “packet consumer.”

The following section describes the specifics of the push method.

7.5.1 push: Push a packet through to the packet consumer

SYNOPSIS

#include <oskit/io/netio.h>

OSKIT_COMDECL push(oskit_netio_t *io, oskit_bufio *buf, oskit_size_t size);

DESCRIPTION

This method feeds a network packet to the packet consumer represented by the netio object; what the consumer does with the packet depends entirely on who the consumer is and how it is configured. The packet is contained in a bufio object which must be at least the size of the packet, but may be larger; the size parameter on the push call indicates the actual size of the packet.

If the consumer needs to hold on to the provided bufio object after returning from the call, it must call addref on the bufio object to obtain its own reference; then it must release this reference at some later time when it is done with the buffer. Otherwise, if the consumer doesn’t obtain its own reference, the caller may recycle the buffer as soon as the call returns.

The passed buffer object is logically read-only; the consumer must not attempt to write to it. The size parameter to this call is the actual size of the packet; the size of the buffer, as returned by the getsize method, may be larger than the size of the packet.

PARAMETERS
io:
The oskit_netio interface representing the packet consumer.
buf :
The oskit_bufio interface to the buffer object containing the packet.
size:
The actual size of the packet; must be less than or equal to the size of the buffer object.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.6 oskit_posixio: POSIX I/O interface

The oskit_posixio interface defines the minimal POSIX I/O interface that any POSIX I/O object (file, device, pipe, socket, etc) can be expected to support. Only per-object methods are provided by this interface. Additional I/O operations are supported through separate interfaces, such as the oskit_stream interface and oskit_absio COM interface.

The oskit_posixio COM interface inherits from oskit_iunknown, and has the following additional methods:

stat:
Get this object’s attributes.
setstat:
Set this object’s attributes.
pathconf:
Get this object’s value for a configuration option variable.

7.6.1 stat: Get attributes of this object

SYNOPSIS

#include <oskit/io/posixio.h>

OSKIT_COMDECL oskit_posixio_stat(oskit_posixio_t *f, [out] oskit_stat_t *out_stats);

DESCRIPTION

This method returns the attributes of this object. Depending on the type of object, only some of the attributes may be meaningful. out_stats is a pointer to a oskit_stat_t structure defined as follows:

struct oskit_stat {

oskit_dev_t dev; /* device on which inode resides */
oskit_ino_t ino; /* inode’s number */
oskit_mode_t mode; /* file mode */
oskit_nlink_t nlink; /* number of hard links to file */
oskit_uid_t uid; /* user id of owner */
oskit_gid_t gid; /* group id of owner */
oskit_dev_t rdev; /* device number, for device files */
oskit_timespec_t atime; /* time of last access */
oskit_timespec_t mtime; /* time of last data modification */
oskit_timespec_t ctime; /* time of last attribute change */
oskit_off_t size; /* size in bytes */
oskit_u64_t blocks; /* blocks allocated for file */
oskit_u32_t blksize; /* optimal block size in bytes */

};
PARAMETERS
f :
The object whose attributes are desired.
out_stats:
The attributes of the specified object.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.6.2 setstat: Set the attributes of this object

SYNOPSIS

#include <oskit/io/posixio.h>

OSKIT_COMDECL oskit_posixio_setstat(oskit_posixio_t *f, oskit_u32_t mask, const oskit_stat_t *stat);

DESCRIPTION

This method sets the attributes specified in mask to the values specified in stat. mask may be any combination of the following:

OSKIT_STAT_MODE:
Set the file mode, except for the file type bits, as in the Unix chmod system call.
OSKIT_STAT_UID:
Set the file user id, as in the Unix chown system call.
OSKIT_STAT_GID:
Set the file group id, as in the Unix chown system call.
OSKIT_STAT_SIZE:
Set the file size, as in the Unix truncate system call.
OSKIT_STAT_ATIME:
Set the file’s last access timestamp to a particular value, as in the Unix utimes system call with a non-NULL parameter.
OSKIT_STAT_MTIME:
Set the file’s last data modification timestamp to a particular value, as in the Unix utimes system call with a non-NULL parameter.
OSKIT_STAT_UTIMES_NULL:
Set the file’s last access timestamp and data modification timestamp to the current time, as in the Unix utimes system call with a NULL parameter.

Typically, this method is not supported for symbolic links.

PARAMETERS
f :
The object whose attributes are to be changed.
mask:
The attributes to be changed.
stat:
The new attribute values.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.6.3 pathconf: Get value of a configuration option variable

SYNOPSIS

#include <oskit/io/posixio.h>

OSKIT_COMDECL oskit_posixio_pathconf(oskit_posixio_t *f, oskit_s32_t option, [out] oskit_s32_t *out_val);

DESCRIPTION

This method returns the value of the specified configuration option variable for this object. The value of option may be one of the following:

OSKIT_PC_LINK_MAX:
Get the maximum file link count.
OSKIT_PC_MAX_CANON:
Get the maximum size of the terminal input line.
OSKIT_PC_MAX_INPUT:
Get the maximum input queue size.
OSKIT_PC_NAME_MAX:
Get the maximum number of bytes in a filename.
OSKIT_PC_PATH_MAX:
Get the maximum number of bytes in a pathname.
OSKIT_PC_PIPE_BUF:
Get the maximum atomic write size to a pipe.
OSKIT_PC_CHOWN_RESTRICTED:
Determine whether use of chown is restricted.
OSKIT_PC_NO_TRUNC:
Determine whether too-long pathnames produce errors.
OSKIT_PC_VDISABLE:
Get value to disable special terminal characters.
OSKIT_PC_ASYNC_IO:
Determine whether asynchronous IO is supported.
OSKIT_PC_PRIO_IO:
Determine whether prioritized IO is supported.
OSKIT_PC_SYNC_IO:
Determine whether synchronized IO is supported.
PARAMETERS
f :
The object from which to obtain a configuration option value
option:
The configuration option variable
out_val:
The value of the configuration option value.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.7 oskit_ttystream: Interface to Unix TTY-like streams

This interface extends the standard COM IStream interface with POSIX/Unix TTY functionality, such as methods to control serial port settings, enable, disable, and control line editing, flush the input and output queues, etc.

This interface is currently exported by character-oriented device drivers incorporated into the OSKit from legacy systems such as BSD and Linux, in which full Unix TTY functionality can be provided easily. In the future, these drivers are expected to export more minimal, lower-level interfaces instead of or in addition to this interface; however, in the short term, this interface allows clients to obtain full Unix terminal functionality quickly and easily.

The oskit_ttystream interface inherits from oskit_stream, and has the following additional methods:

getattr:
Get the stream’s current TTY attributes.
setattr:
Set the stream’s TTY attributes.
sendbreak:
Send a break signal over the line.
drain:
Wait until all buffered output has been transmitted.
flush:
Discared buffered input and/or output data.
flow:
Suspend or resume data transmission or reception.

In addition, this header file defines a structure called oskit_termios, corresponding to the standard POSIX termios structure, and a set of related definitions used to specify terminal-related settings. See the POSIX and Unix standards for details on the exact contents and meaning of this structure.

7.7.1 getattr: Get the stream’s current TTY attributes

SYNOPSIS

#include <oskit/io/ttystream.h>

OSKIT_COMDECL getattr(oskit_ttystream_t *tty, [out] struct oskit_termios *attr);

DESCRIPTION

This method retrieves the current line settings of this stream and returns them in the specified oskit_termios structure. This method corresponds to the POSIX tcgetattr function; see the POSIX standard for details.

PARAMETERS
tty:
The TTY stream object to query.
attr:
The structure to be filled with the current line settings.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.7.2 setattr: Set the stream’s TTY attributes

SYNOPSIS

#include <oskit/io/ttystream.h>

OSKIT_COMDECL setattr(oskit_ttystream_t *tty, const struct oskit_termios *attr);

DESCRIPTION

This method sets the line settings of this stream based on the specified oskit_termios structure. This method corresponds to the POSIX tcsetattr function; see the POSIX standard for details.

PARAMETERS
tty:
The TTY stream object to modify.
attr:
The structure containing the new line settings.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.7.3 sendbreak: Send a break signal

SYNOPSIS

#include <oskit/io/ttystream.h>

OSKIT_COMDECL sendbreak(oskit_ttystream_t *tty, oskit_u32_t duration);

DESCRIPTION

On streams controlling asynchronous serial communication, this method sends a break signal (a continuous stream of zero-valued bits) for a specific duration. This method corresponds to the POSIX tcsendbreak function; see the POSIX standard for details.

PARAMETERS
tty:
The TTY stream on which to send the break.
duration:
The duration of the break signal to send. If this parameter is zero, then the duration will be between 0.25 and 0.5 seconds.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.7.4 drain: Wait until all buffered output has been transmitted

SYNOPSIS

#include <oskit/io/ttystream.h>

OSKIT_COMDECL drain(oskit_ttystream_t *tty);

DESCRIPTION

This method waits until any buffered output data that has been written to the stream is successfully transmitted. This method corresponds to the POSIX tcdrain function; see the POSIX standard for details.

PARAMETERS
tty:
The TTY stream object to drain.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.7.5 flush: Discared buffered input and/or output data

SYNOPSIS

#include <oskit/io/ttystream.h>

OSKIT_COMDECL flush(oskit_ttystream_t *tty, int queue_selector);

DESCRIPTION

This method discards any buffered output data that has not yet been transmitted, and/or any buffered input data that has not yet been read, depending on the queue_selector parameter. This method corresponds to the POSIX tcflush function; see the POSIX standard for details.

PARAMETERS
tty:
The TTY stream object to flush.
queue_selector:
Must be one of the following:
OSKIT_TCIFLUSH:
Flush the input buffer.
OSKIT_TCOFLUSH:
Flush the output buffer.
OSKIT_TCIOFLUSH:
Flush the input and output buffers.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.

7.7.6 flow: Suspend or resume data transmission or reception

SYNOPSIS

#include <oskit/io/ttystream.h>

OSKIT_COMDECL flow(oskit_ttystream_t *tty, int action);

DESCRIPTION

This method controls the transmission or reception of data on this TTY stream. This method corresponds to the POSIX tcflow function; see the POSIX standard for details.

PARAMETERS
tty:
The TTY stream object to control.
action:
Must be one of the following:
OSKIT_TCOOFF:
Suspend output.
OSKIT_TCOON:
Restart output.
OSKIT_TCIOFF:
Transmit a STOP character.
OSKIT_TCION:
Transmit a START character.
RETURNS

Returns 0 on success, or an error code specified in <oskit/error.h>, on error.