I/O attribute structure
Synopsis:
#include <sys/iofunc.h>
typedef struct _iofunc_attr {
IOFUNC_MOUNT_T *mount;
uint32_t flags;
int32_t lock_tid;
uint16_t lock_count;
uint16_t count;
uint16_t rcount;
uint16_t wcount;
uint16_t rlocks;
uint16_t wlocks;
struct _iofunc_mmap_list *mmap_list;
struct _iofunc_lock_list *lock_list;
void *lockobj;
void *acl;
#if !defined(_IOFUNC_OFFSET_BITS) || _IOFUNC_OFFSET_BITS == 64
#if __OFF_BITS__ == 64
off_t nbytes;
ino_t inode;
#else
off64_t nbytes;
ino64_t inode;
#endif
#elif _IOFUNC_OFFSET_BITS - 0 == 32
#if __OFF_BITS__ == 32
#if defined(__LITTLEENDIAN__)
off_t nbytes;
off_t nbytes_hi;
ino_t inode;
ino_t inode_hi;
#elif defined(__BIGENDIAN__)
off_t nbytes_hi;
off_t nbytes;
ino_t inode_hi;
ino_t inode;
#else
#error endian not configured for system
#endif
#else
#if defined(__LITTLEENDIAN__)
int32_t nbytes;
int32_t nbytes_hi;
int32_t inode;
int32_t inode_hi;
#elif defined(__BIGENDIAN__)
int32_t nbytes_hi;
int32_t nbytes;
int32_t inode_hi;
int32_t inode;
#else
#error endian not configured for system
#endif
#endif
#else
#error _IOFUNC_OFFSET_BITS value is unsupported
#endif
uid_t uid;
gid_t gid;
time_t mtime;
time_t atime;
time_t ctime;
mode_t mode;
nlink_t nlink;
dev_t rdev;
#if defined(IOFUNC_NS_TIMESTAMP_SUPPORT)
unsigned mtime_ns;
unsigned atime_ns;
unsigned ctime_ns;
#endif
} iofunc_attr_t;
Description:
The iofunc_attr_t structure describes the attributes of the
device that's associated with a resource manager.
You typically use
iofunc_attr_init()
to initialize this structure.
The members include the following:
- mount
- A pointer a structure information about the mountpoint.
By default, this structure is of type iofunc_mount_t,
but you can specify your own structure by changing the
IOFUNC_MOUNT_T manifest.
- flags
- Flags that your resource manager can set to indicate the state of the device.
This member is a combination of the following flags:
- IOFUNC_ATTR_ATIME
- The access time is no longer valid.
Typically set on a read from the resource.
- IOFUNC_ATTR_CTIME
- The change of status time is no longer valid.
Typically set on a file info change.
- IOFUNC_ATTR_DIRTY_ACL
- The access control list has changed.
- IOFUNC_ATTR_DIRTY_MODE
- The mode has changed.
- IOFUNC_ATTR_DIRTY_NLINK
- The number of links has changed.
- IOFUNC_ATTR_DIRTY_OWNER
- The uid or the gid has changed.
- IOFUNC_ATTR_DIRTY_RDEV
- The rdev member has changed, e.g., mknod().
- IOFUNC_ATTR_DIRTY_SIZE
- The size has changed.
- IOFUNC_ATTR_DIRTY_TIME
- One or more of mtime, atime, or ctime has changed.
- IOFUNC_ATTR_MTIME
- The modification time is no longer valid.
Typically set on a write to the resource.
- IOFUNC_ATTR_NS_TIMESTAMPS
- (QNX Neutrino 7.0 or later) The attribute structure includes the fields used for nanosecond-resolution
timestamps, mtime_ns, atime_ns, and ctime_ns.
In addition to the above, your resource manager can use in any way
the bits in the range defined by IOFUNC_ATTR_PRIVATE (see <sys/iofunc.h>).
- lock_tid
- The ID of the thread that has locked the attribute structure.
To support multiple threads in your resource manager,
you'll need to lock the attribute structure so that only one
thread at a time is allowed to change it.
The resource manager layer automatically locks the attribute structure (using
iofunc_attr_lock())
for you when certain handler functions are called (i.e., IO_*).
- lock_count
- The number of times the thread has locked the attribute structure.
You can lock the attribute structure by calling
iofunc_attr_lock()
or
iofunc_attr_trylock();
unlock them by calling
iofunc_attr_unlock()
Note:
A thread must unlock the attribute structure as many times as it locked it.
- count
- The number of OCBs using this attribute structure in any manner.
When this count is zero, no one is using this structure.
- rcount
- The number of OCBs using this attribute structure for reading.
- wcount
- The number of OCBs using this attribute structure for writing.
- rlocks
- The number of read locks currently registered on the attribute structure.
- wlocks
- The number of write locks currently registered on the attribute structure.
- mmap_list and lock_list
- To manage their particular functionality on the resource,
the mmap_list member is used by
iofunc_mmap()
and
iofunc_mmap_default();
the lock_list member is used by
iofunc_lock_default().
Generally, you shouldn't need to modify or examine these members.
- lockobj
- Attribute locking object.
- acl
- Access control lists.
- nbytes
- The number of bytes in the resource; your resource manager can change this value.
For a file, this would contain the file's size.
For special devices (e.g., /dev/null) that don't support
lseek()
or have a radically different interpretation for lseek(),
this field isn't used (because you wouldn't use any of the helper functions, but would supply your own instead).
In these cases, we recommend that you set this field to zero,
unless there's a meaningful interpretation that you care to put to it.
- inode
- The number of a mountpoint-specific inode that must be unique per mountpoint.
You can specify your own value, or 0 to have the process manager fill it in for you.
For filesystem type of applications, this may correspond to some on-disk structure.
In any case, the interpretation of this field is up to you.
- uid and gid
- The user ID and group ID of the owner of this resource.
These fields are updated automatically by the chown() helper functions (e.g.,
iofunc_chown_default()) and are referenced in
conjunction with the mode member for access-granting purposes by the
open() help functions (e.g., iofunc_open_default()).
- mtime, atime, and ctime
- POSIX time members:
- mtime — modification time (write() updates this).
- atime — access time (read() updates this).
- ctime — change of status time (write(),
chmod() and chown() update this).
Note:
One or more of the three time members may be invalidated as a result of calling an iofunc-layer function.
To see if a time member is invalid, check the flags member.
This is to avoid having each and every I/O message handler go to the kernel
and request the current time of day, just to fill in the attribute structure's time member(s).
To fill the members with the correct time, call
iofunc_time_update().
- mode
- The resource's mode (e.g., type, permissions).
Valid modes may be selected from the S_* series
of constants in <sys/stat.h>; see the entry for
struct stat.
- nlink
- The number of links to this particular name; your resource manager can modify this member.
For names that represent a directory, this value must be at least 2
(one for the directory itself, one for the ./ entry in it).
- rdev
- The device number for a character special device and the
rdev number for a named special device.
- mtime_ns, atime_ns, and ctime_ns
- (QNX Neutrino 7.0 or later) The nanosecond values for the POSIX time members,
mtime, atime, and ctime.
These fields are included if you compile for a 64-bit architecture, or if you define
IOFUNC_NS_TIMESTAMP_SUPPORT before including <sys/iofunc.h>
when you compile for a 32-bit architecture.
If these fields are included, IOFUNC_ATTR_NS_TIMESTAMPS is set in the attribute's
flags.