iofunc_mmap()

Handle an _IO_MMAP message

Synopsis:

#include <sys/iofunc.h>

int iofunc_mmap ( resmgr_context_t * hdr,
                  io_mmap_t * msg,
                  iofunc_ocb_t * ocb,
                  iofunc_attr_t * attr );

Since:

BlackBerry 10.0.0

Arguments:

hdr
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_mmap_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 iofunc_mmap() helper function provides functionality for the _IO_MMAP message. The _IO_MMAP message is an outcall from the Memory Manager (a part of the QNX Neutrino microkernel's procnto ).

Note that if the Process Manager is to be able to execute from this resource, then you must use the iofunc_mmap() function.

io_mmap_t structure

The io_mmap_t structure holds the _IO_MMAP message received by the resource manager:

struct _io_mmap {
    uint16_t                    type;
    uint16_t                    combine_len;
    uint32_t                    prot;
    uint64_t                    offset;
    struct _msg_info            info;
    uint32_t                    required_prot;
    uint32_t                    zero[5];
};

struct _io_mmap_reply {
    uint32_t                    zero;
    uint32_t                    allowed_prot;
    uint64_t                    offset;
    int32_t                     coid;
    int32_t                     fd;
};

typedef union {
    struct _io_mmap             i;
    struct _io_mmap_reply       o;
} io_mmap_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_mmap that contains the following members:

type
_IO_MMAP.
combine_len
If the message is a combine message, _IO_COMBINE_FLAG is set in this member.
prot
The set of protection bits that procnto would like to have for the memory-mapped file. This can be a combination of at least the following protection bits, as defined in <sys/mman.h>:
  • PROT_EXEC — the region can be executed.
  • PROT_NOCACHE — disable caching of the region (e.g., so it can be used to access dual-ported memory).
  • PROT_NONE — the region can't be accessed.
  • PROT_READ — the region can be read.
  • PROT_WRITE — the region can be written.

See the required_prot field, below.

offset
The offset into shared memory of the location that the client wants to start mapping.
info
A pointer to a _msg_info , structure that contains information about the message received by the resource manager.
required_prot
The set of permission bits that procnto must have for the memory-mapped file. Typically the difference between prot and required_prot is that prot may specify PROT_WRITE while required_prot omits it. This means that procnto would like to have write permissions on the file, but it's OK if it isn't present.

The resource manager can tell whether a new or old procnto is talking to it by looking at the required_prot field. If it's nonzero, it's a new procnto, and the code should pay attention to the field. If required_prot is zero, it's an old procnto, and the code should use prot as the required permissions.

The o member of the io_mmap_t structure is a structure of type _io_mmap_reply that contains the following members:

allowed_prot
The allowed protections for the file: PROT_READ is always present, PROT_WRITE is present if the file is opened for writing, and PROT_EXEC is present if the client process that opened the file has execute permissions specified for the file.
offset
Reserved for future use.
coid
A file descriptor that the process manager can use to access the mapped file.
fd
Reserved for future use.

Returns:

A nonpositive value (i.e., ≤ 0)
Successful completion.
EROFS
An attempt was made to memory map (mmap) a read-only file, using the PROT_WRITE page protection mode.
EACCES
The client doesn't have the appropriate permissions.
ENOMEM
Insufficient memory exists to allocate internal resources required to effect the mapping.

Classification:

QNX Neutrino

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

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus