ACE/ace/Mem_Map.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Mem_Map.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_MEM_MAP_H
  12 #define ACE_MEM_MAP_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Global_Macros.h"
  23 #include "ace/Copy_Disabled.h"
  24 #include "ace/os_include/sys/os_mman.h"
  25 #include "ace/os_include/os_limits.h"
  26 #include "ace/os_include/os_fcntl.h"
  27 #include "ace/Default_Constants.h"
  28
  29 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  30
  31 /**
  32  * @class ACE_Mem_Map
  33  *
  34  * @brief C++ interface OS memory mapping system call.
  35  *
  36  * This class works with both the mmap(2) UNIX system and the
  37  * Win32 family of memory mapping system calls.
  38  */
  39 class ACE_Export ACE_Mem_Map : private ACE_Copy_Disabled
  40 {
  41 public:
  42   /// Default constructor.
  43   ACE_Mem_Map (void);
  44
  45   /// Map a file from an open file descriptor @a handle.  This function
  46   /// will lookup the length of the file if it is not given.
  47   ACE_Mem_Map (ACE_HANDLE handle,
  48                size_t length = static_cast<size_t> (-1),
  49                int prot = PROT_RDWR,
  50                int share = ACE_MAP_PRIVATE,
  51                void *addr = 0,
  52                ACE_OFF_T offset = 0,
  53                LPSECURITY_ATTRIBUTES sa = 0);
  54
  55   /// Map a file specified by @a file_name.
  56   ACE_Mem_Map (const ACE_TCHAR *filename,
  57                size_t length = static_cast<size_t> (-1),
  58                int flags = O_RDWR | O_CREAT,
  59                mode_t mode = ACE_DEFAULT_FILE_PERMS,
  60                int prot = PROT_RDWR,
  61                int share = ACE_MAP_PRIVATE,
  62                void *addr = 0,
  63                ACE_OFF_T offset = 0,
  64                LPSECURITY_ATTRIBUTES sa = 0);
  65
  66   /// Map a file from an open file descriptor @a handle.  This function
  67   /// will lookup the length of the file if it is not given.
  68   int map (ACE_HANDLE handle,
  69            size_t length = static_cast<size_t> (-1),
  70            int prot = PROT_RDWR,
  71            int share = ACE_MAP_PRIVATE,
  72            void *addr = 0,
  73            ACE_OFF_T offset = 0,
  74            LPSECURITY_ATTRIBUTES sa = 0);
  75
  76   /// Remap the file associated with <handle_>.
  77   int map (size_t length = static_cast<size_t> (-1),
  78            int prot = PROT_RDWR,
  79            int share = ACE_MAP_PRIVATE,
  80            void *addr = 0,
  81            ACE_OFF_T offset = 0,
  82            LPSECURITY_ATTRIBUTES sa = 0);
  83
  84   /// Map a file specified by @a filename.
  85   int map (const ACE_TCHAR *filename,
  86            size_t length = static_cast<size_t> (-1),
  87            int flags = O_RDWR | O_CREAT,
  88            mode_t mode = ACE_DEFAULT_FILE_PERMS,
  89            int prot = PROT_RDWR,
  90            int share = ACE_MAP_PRIVATE,
  91            void *addr = 0,
  92            ACE_OFF_T offset = 0,
  93            LPSECURITY_ATTRIBUTES sa = 0);
  94
  95   /// Destructor.
  96   ~ACE_Mem_Map (void);
  97
  98   /// Open the file without mapping it.
  99   int open (const ACE_TCHAR *filename,
 100             int flags = O_RDWR | O_CREAT,
 101             mode_t perms = ACE_DEFAULT_FILE_PERMS,
 102             LPSECURITY_ATTRIBUTES sa = 0);
 103
 104   /// Close down the <handle_> if necessary and unmap the mapping.
 105   int close (void);
 106
 107   /// Close down the <handle_> if necessary.
 108   int close_handle (void);
 109
 110   /**
 111    * Close down the internal <file_mapping_> if necessary.  This is
 112    * mostly necessary on Win32, which has a different handle for
 113    * file-mapping kernel object.
 114    */
 115   int close_filemapping_handle (void);
 116
 117   /// This operator passes back the starting address of the mapped
 118   /// file.
 119   int operator () (void *&addr);
 120
 121   /// Return the base address.
 122   void *addr (void) const;
 123
 124   /// This function returns the number of bytes currently mapped in the
 125   /// file.
 126   size_t size (void) const;
 127
 128   /// Unmap the region starting at base_addr_.
 129   int unmap (ssize_t len = -1);
 130
 131   /// Unmap the region starting at addr_.
 132   int unmap (void *addr, ssize_t len);
 133
 134   /**
 135    * Sync @a len bytes of the memory region to the backing store
 136    * starting at base_addr_.  If @a len == -1 then sync the whole
 137    * region.
 138    */
 139   int sync (size_t len, int flags = MS_SYNC);
 140
 141   /**
 142    * Sync the whole memory region to the backing store
 143    * starting at base_addr_.
 144    */
 145   int sync (int flags = MS_SYNC);
 146
 147   /// Sync @a len bytes of the memory region to the backing store
 148   /// starting at addr_.
 149   int sync (void *addr, size_t len, int flags = MS_SYNC);
 150
 151   /**
 152    * Change the protection of the pages of the mapped region to @a prot
 153    * starting at base_addr_ up to @a len bytes.
 154    */
 155   int protect (size_t len, int prot = PROT_RDWR);
 156
 157   /**
 158    * Change the protection of all the pages of the mapped region to @a prot
 159    * starting at base_addr_.
 160    */
 161   int protect (int prot = PROT_RDWR);
 162
 163   /// Change the protection of the pages of the mapped region to @a prot
 164   /// starting at @a addr up to @a len bytes.
 165   int protect (void *addr, size_t len, int prot = PROT_RDWR);
 166
 167   /// Close and remove the file from the file system.
 168   int remove (void);
 169
 170   /// Hook into the underlying VM system.
 171   int advise (int behavior, int len = -1);
 172
 173   /// Return the underlying <handle_>.
 174   ACE_HANDLE handle (void) const;
 175
 176   /// Return the name of file that is mapped (if any).
 177   const ACE_TCHAR *filename (void) const;
 178
 179   /// Dump the state of an object.
 180   void dump (void) const;
 181
 182   /// Declare the dynamic allocation hooks.
 183   ACE_ALLOC_HOOK_DECLARE;
 184
 185 private:
 186
 187   /// This method does the dirty work of actually calling ::mmap to map
 188   /// the file into memory.
 189   int map_it (ACE_HANDLE handle,
 190               size_t len = static_cast<size_t> (-1),
 191               int prot = PROT_RDWR,
 192               int share = MAP_SHARED,
 193               void *addr = 0,
 194               ACE_OFF_T offset = 0,
 195               LPSECURITY_ATTRIBUTES sa = 0);
 196
 197 private:
 198
 199   /// Base address of the memory-mapped file.
 200   void *base_addr_;
 201
 202   /// Name of the file that is mapped.
 203   ACE_TCHAR filename_[MAXPATHLEN + 1];
 204
 205   /// Length of the mapping.
 206   size_t length_;
 207
 208   /// HANDLE for the open file.
 209   ACE_HANDLE handle_;
 210
 211   /// HANDLE for the open mapping.
 212   ACE_HANDLE file_mapping_;
 213
 214   /// Keeps track of whether we need to close the handle.  This is set
 215   /// if we opened the file.
 216   bool close_handle_;
 217
 218 };
 219
 220 ACE_END_VERSIONED_NAMESPACE_DECL
 221
 222 #if defined (__ACE_INLINE__)
 223 #include "ace/Mem_Map.inl"
 224 #endif /* __ACE_INLINE__ */
 225
 226 #include /**/ "ace/post.h"
 227
 228 #endif /* ACE_MEM_MAP_H */