iofunc_attr_t

Description:

The iofunc_attr_t structure describes the data and state associated with a service offered by a resource manager. An attribute structure is often associated with a specific name (e.g., /dev/ser1, /dev/ser2), but need not be (e.g., a pipe created by a call to pipe()). You typically use iofunc_attr_init() to initialize this structure.

The members include the following:

mount

A pointer to a structure with 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.

mmap_list and lock_list

To manage their particular functionality on the resource, the mmap_list member is used by iofunc_mmap(), iofunc_mmap_default(), and iofunc_mmap_default_ext(); the lock_list member is used by iofunc_lock_default(). Generally, you shouldn't need to modify or examine these members.

acl

Access control lists.

lockobj and lock

Members of a union that provide a way to lock 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 attribute structure can be locked recursively.

• The default behavior is to use the lock member, which is a built-in lock mutex. If you use iofunc_attr_init() to initialize the structure, it initializes the built-in lock mutex (lock) using a static lock initializer.

  The resource manager layer automatically locks the attribute structure (using iofunc_attr_lock()) for you when certain handler functions are called (i.e., IO_*). You can lock the attribute structure by calling iofunc_attr_lock() or iofunc_attr_trylock(); unlock it by calling iofunc_attr_unlock().

• If you want to use an external lock object, override the built-in lock by pointing the lockobj member to the external lock object. You also need to provide your own functions to lock and unlock the attribute structure and set the appropriate members of the funcs structure in the iofunc_mount_t structure.

flags

Flags that your resource manager can set to indicate the state of the resource. 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 when the information for a file changes.

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

The attribute structure includes the fields used for nanosecond-resolution timestamps, mtime_ns, atime_ns, and ctime_ns.

You can use these flags to determine which fields of the attribute structure have been modified by the various iofunc-layer helper routines. That way, if you need to write the entries to some medium, you can write just those that have changed. 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>).

count, rcount, wcount, rlocks and wlocks

Several counters are stored in the attribute structure and are incremented/decremented by some of the iofunc layer helper functions. Both the functionality and the actual contents of the message received from the client determine which specific members are affected.

This counter:	Tracks the number of:
count	OCBs using this attribute in any manner. When this count goes to zero, it means that no one is using this attribute.
rcount	OCBs using this attribute for reading
wcount	OCBs using this attribute for writing
rlocks	Read locks currently registered on the attribute
wlocks	Write locks currently registered on the attribute

These counts aren't exclusive. For example, if an OCB has specified that the resource is opened for reading and writing, then count, rcount, and wcount are all incremented. (See the iofunc_attr_init(), iofunc_lock_default(), iofunc_lock(), iofunc_ocb_attach(), and iofunc_ocb_detach() functions.)

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

POSIX states that these times must be valid when the fstat() is performed, but they don't have to reflect the actual time that the associated change occurred. Also, the times must be updated between fstat() invocations if the associated change occurred between fstat() invocations. If the associated change never occurred between fstat() invocations, then the time returned should be the same as returned last time. Furthermore, if the associated change occurred multiple times between fstat() invocations, then the time need only be different from the previously returned time.

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 resource; your resource manager can modify this member. For resources 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

The nanosecond values for the POSIX time members, mtime, atime, and ctime.

Classification:

QNX OS