iofunc_attr_t

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                            *list;
    uint32_t                        list_size;
#if !defined(_IOFUNC_OFFSET_BITS) || _IOFUNC_OFFSET_BITS == 64
 #if _FILE_OFFSET_BITS - 0 == 64
    off_t                           nbytes;
    ino_t                           inode;
 #else
    off64_t                         nbytes;
    ino64_t                         inode;
 #endif
#elif _IOFUNC_OFFSET_BITS - 0 == 32
 #if !defined(_FILE_OFFSET_BITS) || _FILE_OFFSET_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;
} iofunc_attr_t;

Description:

The iofunc_attr_t structure describes the attributes of the device that's associated with a resource manager. 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_NLINK

The number of links has changed.

IOFUNC_ATTR_DIRTY_MODE

The mode 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.

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 attributes. 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 (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 attributes by calling iofunc_attr_lock() or iofunc_attr_trylock(); unlock them by calling iofunc_attr_unlock()

---

A thread must unlock the attributes as many times as it locked them.

---

count

The number of OCBs using this attribute in any manner. When this count is zero, no one is using this attribute.

rcount

The number of OCBs using this attribute for reading.

wcount

The number of OCBs using this attribute for writing.

rlocks

The number of read locks currently registered on the attribute.

wlocks

The number of write locks currently registered on the attribute.

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.

list

Reserved for future use.

list_size

Size of reserved area; reserved for future use.

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

This is 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).

---

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 “Access permissions” in the documentation for 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.

Classification:

QNX Neutrino

See also:

iofunc_attr_lock(), iofunc_attr_trylock(), iofunc_attr_unlock(), iofunc_lock_default(), iofunc_mmap(), iofunc_mmap_default(), iofunc_ocb_t, iofunc_time_update()

Writing a Resource Manager