iofunc_mmap_ext()

#include <sys/iofunc.h>

int iofunc_mmap_ext ( resmgr_context_t * ctp,
                      io_mmap_ext_t * msg,
                      iofunc_ocb_t * ocb,
                      iofunc_attr_t * attr
                      uint32_t const flags,
                      struct stat const * const stat );

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_ext_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.

flags

Flags that the resource manager wants to pass back to the memory manager via the extended.flags member of the _io_mmap_reply_ext structure; a bitwise OR of zero or more of the following:

• _IO_MMAP_REPLY_FLAGS_USE_EXTENDED — the resource manager must set this bit to indicate that it's using the extended functionalities.

  The memory manager sets the flags field to 0 before sending the message; if a reply is of the size of the original _io_mmap_reply, bit 0 of the flags field will still be 0 when the reply comes back.

• _IO_MMAP_REPLY_FLAGS_CACHE_DEFAULT — let the memory manager decide how to invalidate the cache
• _IO_MMAP_REPLY_FLAGS_CACHE_FORCE_INVALIDATE — invalidate the cache
• _IO_MMAP_REPLY_FLAGS_CACHE_READ_FROM_CACHE — read from the cache as it is
• _IO_MMAP_REPLY_FLAGS_CACHE_DEFER_TO_MEMMGR — let the memory manager decide how to invalidate the cache
• _IO_MMAP_REPLY_FLAGS_STAT_FORM_TO_FLAGS(form) — bits that specify the type of stat structure that the resource manager is providing in the extended.stat member. Specify _STAT_FORM_T32_2001, _STAT_FORM_T32_2008, _STAT_FORM_T64_2008, or _STAT_FORM_PREFERRED for form.

  There's also an _IO_MMAP_REPLY_FLAGS_STAT_FORM(flags) macro for extracting a _STAT_FORM_* value from the flags member.

• _IO_MMAP_REPLY_FLAGS_BYPASS_FSTATVFS — bypass fstatvfs() call
• _IO_MMAP_REPLY_FLAGS_REMOVABLE — the media is removable, so reads might not always work
• _IO_MMAP_REPLY_FLAGS_SERVER_SHMEM_OBJECT — the server wants the client to map one of its shared memory objects; the value is in the base.fd field

stat

A pointer to a stat structure that holds information to include in the reply to the memory 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_ext() 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).

The iofunc_mmap_ext() function is an extended version of iofunc_mmap().

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() or iofunc_mmap_ext() function.

io_mmap_ext_t structure

The io_mmap_ext_t structure holds the extended _IO_MMAP message received by the resource manager:

struct _io_mmap_reply {
	_Uint32t					zero;
	_Uint32t					allowed_prot;
	_Uint64t					offset;
	_Int32t						coid;
	_Int32t						fd;
};

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[3];
    uint64_t                    requested_len;
};

union _io_mmap_reply_ext_stat {
        struct stat stat;
        struct __stat_t32_2001  t32_2001;
        struct __stat_t32_2008  t32_2008;
        struct __stat_t64_2008  t64_2008;
#if __PTR_BITS__ == 32
        struct __stat_t32_2001  preferred;
#else
        struct __stat_t64_2008  preferred;
#endif
};

struct _io_mmap_reply_ext {
        struct _io_mmap_reply           base;
        struct {
                _Uint32t                                flags;
                _Uint32t                                zero32;
                _Uint64t                                zero64[4];
                union _io_mmap_reply_ext_stat stat;
        } extended;
};

typedef union {
        struct _io_mmap                 i;
        struct _io_mmap_reply_ext       o;
} io_mmap_ext_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 memory manager in this case).

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_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

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.

requested_len

The length requested in the call to mmap().

The o member of the io_mmap_ext_t structure is a structure of type _io_mmap_reply_ext that contains the following members:

base.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.

base.offset

Reserved for future use.

base.coid

A file descriptor that the process manager can use to access the mapped file.

base.fd

Reserved for future use.

extended.flags

Flags that the resource manager wants to pass back to the memory manager; see the flags argument, above.

extended.stat

Information about the file, in various forms of the stat structure.

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