Lock a resource
Synopsis:
#include <sys/iofunc.h>
int iofunc_lock( resmgr_context_t * ctp,
io_lock_t * msg,
iofunc_ocb_t * ocb,
iofunc_attr_t * attr );
Arguments:
- ctp
- A pointer to a
resmgr_context_t
structure that the resource-manager library uses to pass context information
between functions.
- msg
- A pointer to the
io_lock_t
structure that contains the message that the resource manager received; see below.
- ocb
- A pointer to the
iofunc_ocb_t
structure for the Open Control Block that was created when the
client opened the resource.
- attr
- A pointer to the
iofunc_attr_t
structure that describes the characteristics of the device that's
associated with your resource manager.
Library:
libc
Use the -l c option to
qcc
to link against this library.
This library is usually included automatically.
Description:
The function iofunc_lock() does what is required for POSIX locks.
For more information, see
lockf().
io_lock_t structure
The io_lock_t structure holds the _IO_LOCK
message received by the resource manager:
struct _io_lock {
uint16_t type;
uint16_t combine_len;
uint32_t subtype;
uint32_t nbytes;
/* char data[1]; */ /* for F_*LK this will be flock_t */
};
struct _io_lock_reply {
uint32_t zero [3];
/* char data[1]; */ /* for F_*LK this will be flock_t */
};
typedef union {
struct _io_lock i;
struct _io_lock_reply o;
} io_lock_t;
The I/O message structures are unions of an input message (coming to the
resource manager) and an output or reply message (going back to the client).
The i member is a structure of type _io_read that
contains the following members:
- type
- _IO_LOCK.
- combine_len
- If the message is a combine message, _IO_COMBINE_FLAG
is set in this member.
For more information, see
Combine Messages
chapter of Writing a Resource Manager.
- subtype
- One of the following:
- F_GETLK
- F_GETLK64
- F_SETLK
- F_SETLK64
- F_SETLKW
- F_SETLKW64
For more information, see
fcntl().
- nbytes
- The number of bytes of data included in the message.
The commented-out declaration for data indicates that
nbytes bytes of data (a flock_t structure) immediately follow the
io_lock_t structure.
For information about this structure, see
flock structure
in the entry for fcntl().
QNX Neutrino uses this structure for both
flock()
and the F_GETLK* and F_SETLK* commands for
fcntl().
In QNX Neutrino 7.0 or later, and as a QNX Neutrino extension,
if the structure is for a call to flock(), the l_type member
of this structure has F_FLOCK ORed into it.
Your resource manager can check this bit and behave appropriately:
- For fcntl(), the basis of locking is the process;
all file descriptors for a file within a process are considered to be the same when deciding
whether to allow or block the lock.
- For flock(), the basis is the open control block; a
dup()'d
file descriptor—even if in a different process—is treated
the same as the original for locking purposes, but a second
open() of the file—even in the same process—is a different beast.
Returns:
- -1
- Success; the resource manager library should return a one-part IOV to the client.
- EACCES or EAGAIN
- The operation is F_TLOCK or F_TEST,
and the section is already locked by another process.
- EAGAIN
- The operation is F_LOCK or
F_TLOCK, and the file is mapped with
mmap().
- EBADF
- The file descripter isn't valid, or the operation is
F_LOCK or F_TLOCK,
and the file descriptor isn't open for writing.
- EDEADLK
- The operation is F_LOCK, and a deadlock was detected.
- EINTR
- A signal was caught during execution of the function.
- EINVAL
- The operation isn't one of F_LOCK,
F_TLOCK, F_TEST, or F_ULOCK,
or the size plus the current file offset is less than 0.
- ENOMEM
- The system can't allocate sufficient memory to store lock resources.
- EOPNOTSUPP or EINVAL
- The implementation doesn't support the locking of files of the type
indicated by the file descriptor.
- EOVERFLOW
- The offset of the first, or if the size isn't 0 then the last,
byte in the requested section can't be represented correctly in an object
of type off_t.
Classification:
QNX Neutrino
Safety: |
|
Cancellation point |
No |
Interrupt handler |
No |
Signal handler |
Yes |
Thread |
Yes |