Return to shm.doc CVS log

Up to [Atari MiNT] / MiNT / doc

MiNT 0.96 pl14

Shared Memory and How To Use It



MiNT has a special directory, U:\SHM, which provides a place for

programs to advertise memory that they are offering to share.

To create a shared memory file, a program uses the Fcreate call

to create a file in U:\SHM, e.g.:



fd = Fcreate("U:\\SHM\\MY.SHARE", 0);



It then uses an Fcntl call to attach a block of memory (previously

allocated by Malloc or Mxalloc) to the file:



blk = Malloc(128L);

Fcntl(fd, blk, SHMSETBLK);





Several things should be noted when creating a shared memory

file:



(1) The file's attributes must be 0. Read-only shared memory, or

shared memory with other attributes, is not yet implemented,

but may be in the future.



(2) Two shared memory files cannot have the same name. An attempt

to create a new shared memory file with the same name as an

existing one will fail with an access denied error (EACCDN).



(3) Once the block of memory has been attached to the file, it

may be accessed by any application that opens the file.



(4) A shared memory file (and associated block) remain allocated

even after the program which created it terminates. It can be

deleted (and the associated memory freed) with an Fdelete()

system call.



(5) The size of the shared memory file will be the actual size

of the memory block. This may be somewhat larger than the

size requested in the Malloc or Mxalloc request, due to memory

rounding.





To use a shared memory block, a client application must open

the file and use the SHMGETBLK Fcntl to gain access to it.

For example:



fd = Fopen("U:\\SHM\\MY.SHARE", 2);

blk = Fcntl(fd, 0L, SHMGETBLK);

Fclose(fd); /* optional -- see below */



Things to note:



(1) The address of the shared memory block is returned by the

Fcntl call. NOTE THAT THIS ADDRESS MAY BE DIFFERENT FOR

DIFFERENT PROGRAMS. That is, a shared memory block that appears

at address 0x01000100 in one program may appear at address

0x0007f000 in another. In particular, shared memory blocks

should not contain absolute addresses (e.g. pointers).



(2) The extra argument passed to Fcntl is reserved for future

expansion; use 0L for now to ensure compatibility with

future versions of MiNT.



(3) The mode argument in the Fopen function must be an accurate

reflection of how the program plans to use the memory; read and

write access permissions will be enforced in future versions

of MiNT.



(4) If no SHMSETBLK has been made for the file, a SHMGETBLK Fcntl

will return a NULL pointer to indicate an error.



(5) If a program is finished with a shared memory block and no

longer wishes to use it, it should call Mfree() with the address

of the block (i.e. the address returned by Fcntl(fd, 0L, SHMGETBLK)).





Deleting a Shared Memory File



The Fdelete() system call may be used to delete a shared memory

file. This will *not* necessarily free the associated memory;

the memory will actually be freed only after (1) the file has

been deleted, and (2) all processes using the memory have

freed the memory, either directly or as a result of the process

terminating.



Fdelete() will fail if the shared memory file is still open.

Processes may omit the Fclose() call if they wish this to happen;

it's a way of informing the process trying to delete the file

that people are still interested in it. Note that it is *not*

harmful to allow the Fdelete to occur, since (as noted above)

the memory will not actually be freed until everyone is finished

with it; but sometimes it may be useful for programs to know that

the memory is still in use.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.