iofunc_lock()

Updated: October 28, 2024

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:

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