home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / mmap-177.zip / MMAP.TXT < prev   
Text File  |  1999-08-21  |  10KB  |  226 lines
  1.                   Memory Mapped Files Emulation Layer v1.77
  2.                (c) 1998, 1999 Maurilio Longo - md2520@mclink.it
  3.  
  4.                                    - * -
  5.  
  6. This is a brief document about mmap.dll, if you don't know what memory mapped
  7. files are then this .dll is not for you :-)
  8.  
  9. This .dll is freeware (you can use and redistribute it whitout any charge) but
  10. I retain all rights upon it. Standard disclaimer applies :-) i.e. I'm not
  11. responsible for any damages arising from its use or misuse.
  12.  
  13.                            USE IT AT YOUR OWN RISK.
  14.  
  15. This .dll provides mmap() services to OS/2 processes. It is intended as a tool
  16. for programmers porting unix software to OS/2 and / or for programmers 
  17. developing native OS/2 programs.
  18.  
  19. It is already used on mSLQ/2 (actually it was developed for mSQL/2). You can find
  20. more info about mSQL at this address: http://blnet.com/msqlpc/
  21.  
  22.  
  23. In this package you'll find several files:
  24.  
  25. mmap.dll    :  the emulation layer, it should go on a directory listed on your
  26.                LIBPATH;
  27. mmap.lib    :  import library for OMF linker (like link386.exe);
  28. mmap.a      :  import library for EMX/GCC ld.exe (a.out format);
  29. mman.h      :  include file for C programmers;
  30. mmap.txt    :  this text file you're already reading :-)
  31. history.txt :  list of changes.
  32. ealib.h        :  Extended Attribute Library include file, added since this version
  33.            uses it and copyright requires its presence.
  34.  
  35.  
  36. Since it is an *emulation* of mmap() services it has a few restrictions/limits
  37. that you should be aware of and care:
  38.  
  39. 1) You can have only one mapped region per file, this is a limit which will be
  40.    raised on a future release.
  41.  
  42. 2) You cannot share a mapped region between processes (or address spaces), this
  43.    is a permanent restriction arising from the fact that mmap.dll runs with
  44.    user privileges and needs to be able to commit / decommit memory pages.
  45.  
  46. 2b)Starting with version 1.75 MAP_SHARED is supported inside same address space, 
  47.    ie you  can have, for example, more than one thread which issues a mmap() call 
  48.    with MAP_SHARED for the same file descriptor.
  49.  
  50. 3) On Warp Server Advanced SMP and Aurora HighMemory is used so you can map up 
  51.    to 2Gb of address space. 
  52.    On Warp 3 and 4 you cannot mmap() more than 300 / 350 Mb per process, this is 
  53.    a limit of OS/2.
  54.    On WSA SMP and Aurora you can have VIRTUALADDRESSLIMIT=3072 in your config.sys, 
  55.    but be aware of the fact that mmap.dll can handle a maximum of 2Gb of addresses. 
  56.    So if OS/2 returns an address > 2Gb behaviour is unpredictable.
  57.  
  58. 4) All standard flags of mman.h are defined but only a few are used. You cannot 
  59.    protect or lock memory regions and you should not rely on access flags. 
  60.    All mapped pages are read only until a write access occurs. 
  61.    This is a permanent restriction.
  62.  
  63. 5) Starting with version 1.77 msync() can be synchronous or asynchronous and should be 
  64.    called from time to time to sync modified pages to disk. 
  65.    If you never call it syncing will be done at the time of munmap() call. 
  66.    MS_INVALIDATE is supported and causes all pages to be discarded without writing
  67.    modified ones to disk.
  68.    
  69. 6) There is a non-standard constant MS_MUNMAP (0x10) which is used by munmap()
  70.    to signal to msync() that it has been called by munmap(). This makes msync()
  71.    faster.
  72.  
  73. 7) There is a non-standard function merror() which returns last error of calling
  74.    thread (and resets it).
  75.  
  76. 8) Starting with version 1.75 there are two functions to register/deregister mmap()
  77.    services on a per thread basis. 
  78.    To succeed in registering mmap() you should define a variable of type mmap_reg_t
  79.    on the stack of the calling thread.
  80.  
  81.    ie, in C pseudo code :-)
  82.  
  83.    void main() 
  84.    {
  85.    ...
  86.    mmap_reg_t mmap_reg
  87.    ...
  88.    if (mregister(&mmap_reg) == 0) {
  89.     ...
  90.     ... mmap(....)
  91.     ... munmap(...)
  92.     ...
  93.     mderegister(&mmap_reg)
  94.    }
  95.    ...
  96.    return 0
  97.    }
  98.  
  99. 8b) mmap() works using an exception handler, so if you register your own exception handler
  100.     mregister() should be called AFTER your call to register your own exception handler
  101.     or mmap() could never be called to handle access to mmapped pages. mmap() gives
  102.     control back to OS/2 exceptions handling chain if the exception is not an access 
  103.     violation and the address is not inside a mmapped object.
  104.  
  105. 9) MAP_SHARED support uses EAs to keep track of mappings. Every effort has been made to
  106.    try to clean mmapped files from EA used by mmap(). If, nonetheless, the process using
  107.    mmap() is killed or the PC running it is reset EAs may remain. 
  108.    The EA used is MMAP.HFILE and is of type ASCII. Every time a file is mmapped with 
  109.    MAP_SHARED this EA is added to it and the value is a string of the form NNNNN:FFFF 
  110.    were NNNNN: is the number of milliseconds since last reboot at the time of mmap.dll 
  111.    initialization and FFFF is the file handle of first mmapping.
  112.    Since EAs are used the filesystem holding mmapped files has to support them 
  113.    (ext2, for example, has no support for them, while JFS is OK). 
  114.    Mmap.dll makes no test to ensure that EAs are supported. So you (the programmer 
  115.    using this .dll) have to make this test and complain if something is wrong.
  116.  
  117. The mmap() emulation dll exports the following functions (here listed using 
  118. pascal notation since this library has been developed with VirtualPascal/2 v1.1):
  119.  
  120. Type
  121.    caddr_t      =  Pointer;             // C types for mmap functions
  122.    off_t        =  longint;
  123.    size_t       =  longint;
  124.    int          =  longint;
  125.    mmap_reg_t    =  ExceptionRegistrationRecord;
  126.  
  127. // Returns size in bytes of a memory page
  128. function getpagesize: int;
  129.  
  130. // Stub function, returns -1 and sets merror to EAGAIN
  131. function mprotect(pAddr: caddr_t;  cbLen, fProtection: int): int;
  132.  
  133. // Stub function, returns -1 and sets merror to EAGAIN
  134. function mlockall(fFlags: int): int;
  135.  
  136. // Maps a file to a range of addresses in memory.
  137. // pAddr must be 0, otherwise call fails
  138. // cbLen is dimension of region of file to map
  139. // fProtection is here only for compatibility, all pages are readonly and become read/write after a
  140. //             write access to them
  141. // hFile is the handle of mapping file; only one mapping region is available as of version 1.0 of mmap.dll
  142. // cbOffest position in file from which mapping starts
  143. // if something goes wrong it returns -1 and sets merror to appropriate error code
  144. function mmap(pAddr: caddr_t; cbLen: size_t; fProtection, fFlags, hFile: int; cbOffset: off_t): caddr_t;
  145.  
  146. // Synchronizes pages accessed with a write operation to file, after synchronization pages are converted to
  147. // readonly access; pages with readonly access are decomitted.
  148. // It accepts starting address and len of a mapped region. fFlags is not used but for value
  149. // MS_UNMAP which tells msync that is being called by munmap and so decommitting of readonly pages
  150. // is not necessary.
  151. function msync(pAddr: caddr_t; cbLen: size_t; fFlags: int): int;
  152.  
  153. // Stub function, always returns 0
  154. function munlockall: int;
  155.  
  156. // Unmaps a previously mapped region and syncs it to file if necessary
  157. function munmap(pAddr: caddr_t; cbLen: size_t): int;
  158.  
  159. // Returns, and clears, last error of calling thread
  160. function merror: int;
  161.  
  162. // Registers mmap services on a per thread basis
  163. function mregister(var Reg: mmap_reg_t): int;
  164.  
  165. // Deregisters them
  166. function mderegister(var Reg: mmap_reg_t): int;
  167.  
  168.  
  169. merror() returns last error occurred to calling thread and clears it; defined
  170. errors are as follows:
  171.  
  172. EPERM          =     1;              // Operation not permitted
  173. EIO            =     5;              // Input/output error
  174. ENXIO          =     6;              // Device not configured
  175. EBADF          =     9;              // Bad file descriptor
  176. ENOMEM         =     12;             // Cannot allocate memory
  177. EACCES         =     13;             // Permission denied
  178. EBUSY          =     16;             // Device busy
  179. ENODEV         =     19;             // Operation not supported by device
  180. EINVAL         =     22;             // Invalid argument
  181. EMFILE         =     24;             // Too many open files
  182. EAGAIN         =     35;             // Resource temporarily unavailable
  183.  
  184.  
  185. This library defines standard flags for mmap(), msync() and munmap() but does
  186. use only a few; so you should not rely on them but at the same time they are
  187. reserved for future use.
  188.  
  189. HAVE_MSYNC     =     $1;         // msync available
  190. PROT_READ      =     $0001;      // read only access - not used
  191. PROT_WRITE     =     $0002;      // write access     - not used
  192. PROT_EXEC      =     $0004;      // execute access   - not used
  193. PROT_NONE      =     $0000;      // no access        - not used
  194.  
  195. MAP_SHARED     =     $1;         // shared mapping   - supported inside same address space
  196. MAP_PRIVATE    =     $2;         // private mapping  
  197. MAP_FIXED      =     $10;        // fixed address    - not supported
  198.  
  199. MCL_CURRENT    =     $1;         // locking options are not supported
  200. MCL_FUTURE     =     $2;
  201.  
  202. MS_ASYNC       =     $1;         // asynchronous syncing
  203. MS_INVALIDATE  =     $2;         // invalidate pages
  204. MS_SYNC           =     $4;     // synchronous syncing
  205.  
  206. MS_MUNMAP      =     $10;        // Used by munmap() when calling msync()
  207.  
  208.  
  209. It's possible to set an environment variable to force the mmap.dll to show infos 
  210. about its inner workings. To enable this capability use
  211.  
  212. SET MMAPDLL=DEBUG
  213.  
  214. before starting any process which will use mmap() services.
  215.  
  216. It's possible to find a more detailed documentation about memory mapped files
  217. at this address http://hoth.stsci.edu/man/man2/mmap.html but please bear in
  218. mind that those are pages about linux / freebsd memory mapped services so they
  219. list capabilities and functions not available with my emulation.
  220.  
  221. I would like to thank Yuri Dario (mc6530@mclink.it) for his help and tests 
  222. of my .dll. 
  223.  
  224. Ok, that's all. Please bear with my poor english and happy mmapping :-)) 
  225. I'd like to be informed if you decide to use my library in a program of yours.
  226.