Handle an _IO_MMAP message
Synopsis:
#include <sys/iofunc.h>
int iofunc_mmap ( resmgr_context_t * ctp,
io_mmap_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_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 microkernel's
procnto).
This helper function checks that the requested mapping permissions don't conflict with the open
mode for the file descriptor and that the mountpoint isn't read only.
It also checks that the file is executable before setting PROT_EXEC in allowed_prot.
The helper obtains an exclusive write lock on the file if it's being mapped with execute permissions.
Note that if you write your own handler for _IO_MMAP messages, and you want the process manager
to be able to execute binaries from the resource, then your handler 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_info32 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.
For more information, see
Combine Messages
chapter of Writing a Resource Manager.
- 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_info32,
structure that contains information about the message received by the resource manager.
- required_prot
- (QNX Neutrino 6.6 or later)
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.
To determine whether the version of procnto your resource manager is talking to
supports this field, look at the prot field:
- If (prot & ~PROT_MASK) is nonzero, procnto supports the
required_prot field, so the code should pay attention to it.
- If (prot & ~PROT_MASK) is zero, procnto doesn't support
required_prot, so 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
- (QNX Neutrino 6.6 or later)
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., less than or equal to 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 |