Return to shm.doc CVS log

Up to [Atari MiNT] / MiNT / doc

Annotation of MiNT/doc/shm.doc, revision 1.1

1.1     ! root        1: Shared Memory and How To Use It
        !             2: 
        !             3: 
        !             4: 
        !             5: MiNT has a special directory, U:\SHM, which provides a place for
        !             6: 
        !             7: programs to advertise memory that they are offering to share.
        !             8: 
        !             9: To create a shared memory file, a program uses the Fcreate call
        !            10: 
        !            11: to create a file in U:\SHM, e.g.:
        !            12: 
        !            13: 
        !            14: 
        !            15: fd = Fcreate("U:\\SHM\\MY.SHARE", 0);
        !            16: 
        !            17: 
        !            18: 
        !            19: It then uses an Fcntl call to attach a block of memory (previously
        !            20: 
        !            21: allocated by Malloc or Mxalloc) to the file:
        !            22: 
        !            23: 
        !            24: 
        !            25: blk = Malloc(128L);
        !            26: 
        !            27: Fcntl(fd, blk, SHMSETBLK);
        !            28: 
        !            29: 
        !            30: 
        !            31: 
        !            32: 
        !            33: Several things should be noted when creating a shared memory
        !            34: 
        !            35: file:
        !            36: 
        !            37: 
        !            38: 
        !            39: (1) The file's attributes must be 0. Read-only shared memory, or
        !            40: 
        !            41: shared memory with other attributes, is not yet implemented,
        !            42: 
        !            43: but may be in the future.
        !            44: 
        !            45: 
        !            46: 
        !            47: (2) Two shared memory files cannot have the same name. An attempt
        !            48: 
        !            49: to create a new shared memory file with the same name as an
        !            50: 
        !            51: existing one will fail with an access denied error (EACCDN).
        !            52: 
        !            53: 
        !            54: 
        !            55: (3) Once the block of memory has been attached to the file, it
        !            56: 
        !            57: may be accessed by any application that opens the file.
        !            58: 
        !            59: 
        !            60: 
        !            61: (4) A shared memory file (and associated block) remain allocated
        !            62: 
        !            63: even after the program which created it terminates. It can be
        !            64: 
        !            65: deleted (and the associated memory freed) with an Fdelete()
        !            66: 
        !            67: system call.
        !            68: 
        !            69: 
        !            70: 
        !            71: (5) The size of the shared memory file will be the actual size
        !            72: 
        !            73: of the memory block. This may be somewhat larger than the
        !            74: 
        !            75: size requested in the Malloc or Mxalloc request, due to memory
        !            76: 
        !            77: rounding.
        !            78: 
        !            79: 
        !            80: 
        !            81: 
        !            82: 
        !            83: To use a shared memory block, a client application must open
        !            84: 
        !            85: the file and use the SHMGETBLK Fcntl to gain access to it.
        !            86: 
        !            87: For example:
        !            88: 
        !            89: 
        !            90: 
        !            91: fd = Fopen("U:\\SHM\\MY.SHARE", 2);
        !            92: 
        !            93: blk = Fcntl(fd, 0L, SHMGETBLK);
        !            94: 
        !            95: Fclose(fd); /* optional -- see below */
        !            96: 
        !            97: 
        !            98: 
        !            99: Things to note:
        !           100: 
        !           101: 
        !           102: 
        !           103: (1) The address of the shared memory block is returned by the
        !           104: 
        !           105: Fcntl call. NOTE THAT THIS ADDRESS MAY BE DIFFERENT FOR
        !           106: 
        !           107: DIFFERENT PROGRAMS. That is, a shared memory block that appears
        !           108: 
        !           109: at address 0x01000100 in one program may appear at address
        !           110: 
        !           111: 0x0007f000 in another. In particular, shared memory blocks
        !           112: 
        !           113: should not contain absolute addresses (e.g. pointers).
        !           114: 
        !           115: 
        !           116: 
        !           117: (2) The extra argument passed to Fcntl is reserved for future
        !           118: 
        !           119: expansion; use 0L for now to ensure compatibility with
        !           120: 
        !           121: future versions of MiNT.
        !           122: 
        !           123: 
        !           124: 
        !           125: (3) The mode argument in the Fopen function must be an accurate
        !           126: 
        !           127: reflection of how the program plans to use the memory; read and
        !           128: 
        !           129: write access permissions will be enforced in future versions
        !           130: 
        !           131: of MiNT.
        !           132: 
        !           133: 
        !           134: 
        !           135: (4) If no SHMSETBLK has been made for the file, a SHMGETBLK Fcntl
        !           136: 
        !           137: will return a NULL pointer to indicate an error.
        !           138: 
        !           139: 
        !           140: 
        !           141: (5) If a program is finished with a shared memory block and no
        !           142: 
        !           143: longer wishes to use it, it should call Mfree() with the address
        !           144: 
        !           145: of the block (i.e. the address returned by Fcntl(fd, 0L, SHMGETBLK)).
        !           146: 
        !           147: 
        !           148: 
        !           149: 
        !           150: 
        !           151: Deleting a Shared Memory File
        !           152: 
        !           153: 
        !           154: 
        !           155: The Fdelete() system call may be used to delete a shared memory
        !           156: 
        !           157: file. This will *not* necessarily free the associated memory;
        !           158: 
        !           159: the memory will actually be freed only after (1) the file has
        !           160: 
        !           161: been deleted, and (2) all processes using the memory have
        !           162: 
        !           163: freed the memory, either directly or as a result of the process
        !           164: 
        !           165: terminating.
        !           166: 
        !           167: 
        !           168: 
        !           169: Fdelete() will fail if the shared memory file is still open.
        !           170: 
        !           171: Processes may omit the Fclose() call if they wish this to happen;
        !           172: 
        !           173: it's a way of informing the process trying to delete the file
        !           174: 
        !           175: that people are still interested in it. Note that it is *not*
        !           176: 
        !           177: harmful to allow the Fdelete to occur, since (as noted above)
        !           178: 
        !           179: the memory will not actually be freed until everyone is finished
        !           180: 
        !           181: with it; but sometimes it may be useful for programs to know that
        !           182: 
        !           183: the memory is still in use.
        !           184: 

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