Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

resmgr_open_bind()

Associate an OCB with an open request

Synopsis:

#include <sys/resmgr.h>

int resmgr_open_bind(
       resmgr_context_t* ctp,
       void* ocb,
       const resmgr_io_funcs_t* iofuncs );

Arguments:

ctp
A pointer to a resmgr_context_t structure that the resource-manager library uses to pass context information between functions.
ocb
A pointer to the Open Control Block that you want to bind to the open request. An OCB is usually a structure of type iofunc_ocb_t, but you can define your own.
iofuncs
A pointer to the resmgr_io_funcs_t structure that defines the I/O functions for the resource manager.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The resmgr_open_bind() function is the lowest-level call in the resource manager library used for handling open messages. It associates the Open Control Block (OCB) with a process identified by the id and info members of ctp.


Note: You must use this function as part of the handling of an _IO_OPEN message. In practice, you don't call this function directly; you typically use either iofunc_open_default() or iofunc_ocb_attach(). (The iofunc_open_default() function calls iofunc_ocb_attach(), which in turn calls resmgr_open_bind()).

An internal data structure is allocated that maintains the number of links to the OCB. On a file descriptor dup(), the link count is incremented and on a close() it's decremented. When the count reaches zero, the close_ocb() callout specified in io_funcs is called.

In the most general case, the OCB is an arbitrary structure that you define that can hold information describing an open file, or just a simple int to hold the open mode for checking in the read() and write() callouts.

In the typical case, however, the OCB is a structure that contains at least the members as defined by the typedef iofunc_ocb_t. This typedef defines a common OCB structure that can then be used by the POSIX layer helper functions (all functions beginning with the name iofunc_*). The advantage of this approach is that your resource manager gets POSIX behavior for free, without any additional work on your part.

The attr argument to the open() callout is also typically saved in the OCB. The well defined iofunc_ocb_t has a member called attr to which you must assign the value of the attr argument. This lets the POSIX helper functions access information about the current open session (as stored in the OCB) as well as information about the device itself (as stored in the attributes structure, ocb -> attr).

For a detailed discussion, including several examples, see the Writing a Resource Manager chapter of the Neutrino Programmer's Guide.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EINVAL
The id and/or info members of ctp aren't valid.
ENOMEM
Insufficient memory to allocate an internal data structure.

Classification:

QNX Neutrino

Safety:
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes

See also:

iofunc_ocb_attach(), iofunc_ocb_t, iofunc_open_default(), resmgr_context_t, resmgr_io_funcs_t, resmgr_unbind()

Writing a Resource Manager chapter of the Neutrino Programmer's Guide

Resource Managers chapter of Getting Started with QNX Neutrino