## NAME

ACE_Mem_Map - C++ interface OS memory mapping system call.

## SYNOPSIS

    #include <ace/Mem_Map.h>

    class ACE_Mem_Map
    {
      public:
        ACE_Mem_Map (void);
        ACE_Mem_Map (
            ACE_HANDLE handle,
            int length = -1,
            int prot = PROT_RDWR,
            int share = ACE_MAP_PRIVATE,
            void *addr = 0,
            off_t offset = 0,
            LPSECURITY_ATTRIBUTES sa = 0
            );
        ACE_Mem_Map (
            LPCTSTR filename,
            int len = -1,
            int flags = O_RDWR | O_CREAT,
            int mode = ACE_DEFAULT_FILE_PERMS,
            int prot = PROT_RDWR,
            int share = ACE_MAP_PRIVATE,
            void *addr = 0,
            off_t offset = 0,
            LPSECURITY_ATTRIBUTES sa = 0
            );
        int map (
            ACE_HANDLE handle,
            int length = -1,
            int prot = PROT_RDWR,
            int share = ACE_MAP_PRIVATE,
            void *addr = 0,
            off_t offset = 0,
            LPSECURITY_ATTRIBUTES sa = 0
            );
        int map (
            int length = -1,
            int prot = PROT_RDWR,
            int share = ACE_MAP_PRIVATE,
            void *addr = 0,
            off_t offset = 0,
            LPSECURITY_ATTRIBUTES sa = 0
            );
        int map (
            LPCTSTR filename,
            int len = -1,
            int flags = O_RDWR | O_CREAT,
            int mode = ACE_DEFAULT_FILE_PERMS,
            int prot = PROT_RDWR,
            int share = ACE_MAP_PRIVATE,
            void *addr = 0,
            off_t offset = 0,
            LPSECURITY_ATTRIBUTES sa = 0
            );
        ~ACE_Mem_Map (void);
        int open (
            LPCTSTR filename,
            int flags = O_RDWR | O_CREAT,
            int mode = ACE_DEFAULT_FILE_PERMS,
            LPSECURITY_ATTRIBUTES sa = 0
            );
        int close (void);
        int close_handle (void);
        int close_filemapping_handle (void);
        int operator () (void *&addr);
        void *addr (void) const;
        size_t size (void) const;
        int unmap (int len = -1);
        int unmap (void *addr, int len);
        int sync (ssize_t len = -1, int flags = MS_SYNC);
        int sync (void *addr, size_t len, int flags = MS_SYNC);
        int protect (ssize_t len = -1, int prot = PROT_RDWR);
        int protect (void *addr, size_t len, int prot = PROT_RDWR);
        int remove (void);
        int advise (int behavior, int len = -1);
        ACE_HANDLE handle (void) const;
        const TCHAR *filename (void) const;
        void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
      private:
        void *base_addr_;
        TCHAR filename_[MAXPATHLEN + 1];
        size_t length_;
        ACE_HANDLE handle_;
        ACE_HANDLE file_mapping_;
        int write_enabled_;
        int close_handle_;
        int map_it (
            ACE_HANDLE handle,
            int len = -1,
            int prot = PROT_RDWR,
            int share = MAP_SHARED,
            void *addr = 0,
            off_t offset = 0,
            LPSECURITY_ATTRIBUTES sa = 0
            );
        inline ACE_UNIMPLEMENTED_FUNC (ACE_Mem_Map (const ACE_Mem_Map &));
    };

## DESCRIPTION

This class works with both the mmap(2) UNIX system and the Win32 family of memory mapping system calls.

## Initialization and termination methods.

    ACE_Mem_Map (void);

Default constructor.

    ACE_Mem_Map (
        ACE_HANDLE handle,
        int length = -1,
        int prot = PROT_RDWR,
        int share = ACE_MAP_PRIVATE,
        void *addr = 0,
        off_t offset = 0,
        LPSECURITY_ATTRIBUTES sa = 0
        );

Map a file from an open file descriptor `handle`. This function will lookup the length of the file if it is not given.

    ACE_Mem_Map (
        LPCTSTR filename,
        int len = -1,
        int flags = O_RDWR | O_CREAT,
        int mode = ACE_DEFAULT_FILE_PERMS,
        int prot = PROT_RDWR,
        int share = ACE_MAP_PRIVATE,
        void *addr = 0,
        off_t offset = 0,
        LPSECURITY_ATTRIBUTES sa = 0
        );

Map a file specified by `file_name`.

    int map (
        ACE_HANDLE handle,
        int length = -1,
        int prot = PROT_RDWR,
        int share = ACE_MAP_PRIVATE,
        void *addr = 0,
        off_t offset = 0,
        LPSECURITY_ATTRIBUTES sa = 0
        );

Map a file from an open file descriptor `handle`. This function will lookup the length of the file if it is not given.

    int map (
        int length = -1,
        int prot = PROT_RDWR,
        int share = ACE_MAP_PRIVATE,
        void *addr = 0,
        off_t offset = 0,
        LPSECURITY_ATTRIBUTES sa = 0
        );

Remap the file associated with `handle_`.

    int map (
        LPCTSTR filename,
        int len = -1,
        int flags = O_RDWR | O_CREAT,
        int mode = ACE_DEFAULT_FILE_PERMS,
        int prot = PROT_RDWR,
        int share = ACE_MAP_PRIVATE,
        void *addr = 0,
        off_t offset = 0,
        LPSECURITY_ATTRIBUTES sa = 0
        );

Map a file specified by `filename`.

    ~ACE_Mem_Map (void);

Destructor.

    int open (
        LPCTSTR filename,
        int flags = O_RDWR | O_CREAT,
        int mode = ACE_DEFAULT_FILE_PERMS,
        LPSECURITY_ATTRIBUTES sa = 0
        );

Open the file without mapping it.

    int close (void);

Close down the `handle_` if necessary and unmap the mapping.

    int close_handle (void);

Close down the `handle_` if necessary.

    int close_filemapping_handle (void);

Close down the internal `file_mapping_` if necessary. This is mostly necessary on Win32, which has a different handle for file-mapping kernel object.

    int operator () (void *&addr);

This operator passes back the starting address of the mapped file.

    void *addr (void) const;

Return the base address.

    size_t size (void) const;

This function returns the number of bytes currently mapped in the file.

    int unmap (int len = -1);

Unmap the region starting at `base_addr_`.

    int unmap (void *addr, int len);

Unmap the region starting at `addr_`.

    int sync (ssize_t len = -1, int flags = MS_SYNC);

Sync `len` bytes of the memory region to the backing store starting at `base_addr_`. If `len` == -1 then sync the whole region.

    int sync (void *addr, size_t len, int flags = MS_SYNC);

Sync `len` bytes of the memory region to the backing store starting at `addr_`.

    int protect (ssize_t len = -1, int prot = PROT_RDWR);

Change the protection of the pages of the mapped region to `prot` starting at `base_addr_` up to `len` bytes. If `len` == -1 then change protection of all pages in the mapped region.

    int protect (void *addr, size_t len, int prot = PROT_RDWR);

Change the protection of the pages of the mapped region to `prot` starting at `addr` up to `len` bytes.

    int remove (void);

Close and remove the file from the file system.

    int advise (int behavior, int len = -1);

Hook into the underlying VM system.

    ACE_HANDLE handle (void) const;

Return the underlying `handle_`.

    const TCHAR *filename (void) const;

Return the name of file that is mapped (if any).

    void dump (void) const;

Dump the state of an object.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

## Disallow copying and assignment.

    inline ACE_UNIMPLEMENTED_FUNC (ACE_Mem_Map (const ACE_Mem_Map &));

## AUTHOR

Doug Schmidt

## LIBRARY

ace