System Calls                                                     mmapobj(2)

NAME
    mmapobj - map a file object in the appropriate manner.

SYNOPSIS
    #include <sys/mman.h>

    int mmapobj(int fd, uint_t flags, mmapobj_result_t *storage,
        uint_t *elements, void *arg)

DESCRIPTION
    The mmapobj() function establishes a set of mappings between a process's
    address space and a file.  By default, mmapobj() maps the whole file as a
    single, private, read-only mapping.  The MMOBJ_INTERPRET flag instructs
    mmapobj() to attempt to interpret the file and map the file according to
    the rules for that file format.  Currently only the following ELF and
    AOUT formats are supported.

    ET_EXEC and AOUT executables
         Result in one or more mappings whose size, alignment and protections
         are as described by the files program header information.  The
         address of each mapping is explicitly defined by the files program
         headers.

   ET_DYN and AOUT shared objects
         Result in one or more mappings whose size, alignment and protections
         are as described by the files program header information.  The base
         address of the initial mapping is obtained by mapobj().  The address
         of adjacent mappings are based off of this base address as explicitly
         defined by the files program headers.

   ET_REL and ET_CORE
         Result in a single, read-only  mapping.  The base address of this
         mapping is obtained by mmapobj().

   mmapobjd() will not map over any currently used mappings within the process
   except for the case of an ELF file for which a previous reservation has
   been made via /dev/null.

   Mappings created via mmapobj() can be processed individually by other
   system calls such as munmap(2).

PARAMETERS
   fd    The open file descriptor for the file to be mapped.

   flags Indicates that the default behavior of mmapobj() should be modified
         accordingly.  Available flags are MMOBJ_INTERPRET and MMOBJ_PADDING.

   storage
         A pointer to the mmapobj_result_t array where the mapping
         data will be copied out after a successful mapping of fd.

   elements
         A pointer to the number of mmapobj_result_t elements pointed to by
         storage.  On return, elements contains the number of mappings
         required to fully map the requested object.  If the original value of
         elements is too small, an error is returned, and elements is modified
         to contain the number of mappings necessary.

   arg   A pointer to additional information that might be associated with the
         specific request.  Presently, only the MMOBJ_PADDING request uses
         this argument.  In this case, args should be a pointer to size_t that
         indicates how much padding is requested.  This amount of padding is
         added before the first mapping and immediately after the last mapping.

FLAGS
   MMOBJ_INTERPRET
         Interpret the contents of the file descriptor instead of just mapping
         a single image.  Can only be used with ELF and AOUT files.

   MMOBJ_PADDING
         When mapping in the file descriptor, padding of the amount pointed to
         by arg is requested before the lowest mapping and after the highest
         mapping.


TYPES USED
   typedef struct {
         caddr_t         mr_addr;         /* mapping address */
         size_t          mr_msize;        /* mapping size */
         size_t          mr_fsize;        /* file size */
         size_t          mr_offset;       /* offset into file */
         uint_t          mr_prot;         /* the protections provided */
         uint_t          mr_flags;        /* info on the mapping */
   } mmapobj_result_t;

   Values for mr_flags include:

   MOBJ_PADDING           0x1   /* this mapping represents requested padding */
   MOBJ_HDR_ELF           0x2   /* the ELF header is mapped at mr_addr */
   MOBJ_HDR_AOUT          0x3   /* the AOUT header is mapped at mr_addr */

RETURN VALUES
         -1 indicates an error occurred and errno will hold the reason.  No
         data is copied to storage.

         On success, 0 is returned and elements contains how many program
         headers are mapped for fd.  The data for these elements is copied
         to storage such that the first <elements> members of the storage
         array contain valid mapping data.

ERROR VALUES
         E2BIG   Elements was not large enough to hold the number of loadable
                 segments in fd.  elements will be modified to contain the
                 number of segments required.

         EBADF   fd was not a valid open file descriptor

         EPERM   fd was not open for reading

         EINVAL  MMOBJ_INTERPRET was specified and fd is not a valid file type
                 to be interpreted.

                 MMOBJ_PADDING was specified and arg is NULL.

                 flags contains and invalid flag.

         EACCES  The file system containing the fd to be interpreted does not
                 provide for execute access.

         ENOMEM  Insufficient memory is available to hold the program headers.

         EADDRINUSE
                 The mapping requirements overlap an object that is already
                 used by the process.

         EFAULT  storage or args, points to an invalid address.

         ENOTSUP The current user data model does not match the fd to be
                 interpreted.  Thus a 32-bit process that tried to use
		 mmapobj() to interpret a 64-bit object would return ENOTSUP.

                 fd is an ELF file whose type can not be interpreted.

  SEE ALSO
      ld.so.1(1), memcntl(2), madvise(2), mmap(2), mprotect(2), munmap(2),
      mlockall(3C), msync(3C), attributes(5)

      Linker and Libraries Guide