The iofunc_ocb_t OCB structure

The OCB structure contains information on a per-file-descriptor basis. What this means is that when a client performs an open() call and gets back a file descriptor (as opposed to an error indication), the resource manager will have created an OCB and associated it with the client. This OCB will be around for as long as the client has the file descriptor open.

Effectively, the OCB and the file descriptor are a matched pair. Whenever the client calls an I/O function, the resource manager library will automatically associate the OCB, and pass it along with the message to the I/O function specified by the I/O function table entry. This is why the I/O functions all had the ocb parameter passed to them. Finally, the client will close the file descriptor (via close()), which will cause the resource manager to dissociate the OCB from the file descriptor and client. Note that the client's dup() function simply increments a reference count. In this case, the OCB gets dissociated from the file descriptor and client only when the reference count reaches zero (i.e., when the same number of close()s have been called as open() and dup()s.)

As you might suspect, the OCB contains things that are important on a per-open or per-file-descriptor basis. Here are the contents (from <sys/iofunc.h>):

typedef struct _iofunc_ocb {
  IOFUNC_ATTR_T *attr;
  int32_t       ioflag;
  SEE_BELOW!!!  offset;
  uint16_t      sflag;
  uint16_t      flags;
} iofunc_ocb_t;

Ignore the comment about the offset field for now; we'll come back to it immediately after this discussion.

The iofunc_ocb_t members are:

attr

A pointer to the attributes structure related to this OCB. A common coding idiom you'll see in the I/O functions is “ocb->attr,” used to access a member of the attributes structure.

ioflag

The open mode; how this resource was opened (e.g., read only). The open modes (as passed to open() on the client side) correspond to the ioflag values as follows:

Open mode	ioflag value
O_RDONLY	_IO_FLAG_RD
O_RDWR	_IO_FLAG_RD | _IO_FLAG_WR
O_WRONLY	_IO_FLAG_WR

offset

The current lseek() offset into this resource.

sflag

The sharing flag (see <share.h>) used with the client's sopen() function call. These are the flags SH_COMPAT, SH_DENYRW, SH_DENYWR, SH_DENYRD, and SH_DENYNO.

flags

System flags. The flags currently supported are IOFUNC_OCB_PRIVILEGED, which indicates whether a privileged process issued the connect message that resulted in this OCB, IOFUNC_OCB_MMAP, which indicates whether this OCB is in use by a mmap() call on the client side, and IOFUNC_OCB_MMAP_UNIQUE, which is a hint for the mmap() handler to provide a unique mapping. No other flags are defined at this time. You can use the bits defined by IOFUNC_OCB_FLAGS_PRIVATE for your own private flags.

If you wish to store additional data along with the “normal” OCB, rest assured that you can “extend” the OCB. We'll discuss this in the “Advanced topics” section.