shmsub

NAME

  shmsub - shared memory handling routines

DESCRIPTION

   shmsub.doc
	   Kazuro Furukawa (kazuro.furukawa@kek.jp)
	   Jul.8., Aug.28., Sep.25.1993.

   @(#)shmsub.doc v1.2.2 K.Furukawa, Jul.1993-Aug.1993

   File shmsub.c containes cm_xxx functions for shared memory handling.
   These routines are based on shmtest and swmodule programs (see
   ~furukawa/work/shmtest).  These routines are available in
   the hecomsub package, shmsem.tar.Z.

   It supports shared memory handling on unix and OS9 systems.
   On OS9 shared memory is called as data modules.

   The file shmsub.c defines cm_check, cm_create, cm_map, cm_unmap,
   cm_remove and cm_info routines.

   These routines run on Sony/News, Sun, VAX/Ultrix, DecStation/Ultrix,
   Hpux, NEC/SXA, Apple/AUX, LynxOS, and OS9/68K.
   They don't run on NeXT, Mitsubishi/Umx, MSDOS and MacOS/MacTCP.

   BASIC USAGE:
    The basic usage below describes data exchange between two processes.
     process A:
      cm_create( 123, 1024, CM_PALL, CM_OERR );	   /* create common memory
      mem = (int *)cm_map( 123, CM_OERR ); /* map memory
      *mem = data;			   /* write data
      *(mem+1) = data2;
      ...
      cm_unmap( cm_desc, CM_OERR );		   /* unmap memory
     process B:
      mem = (int *)cm_map( 123, CM_OERR ); /* map memory
      data = *mem;			   /* read data
      data2 = *(mem+1);
      ...
      cm_unmap( cm_desc, CM_OERR );		   /* unmap memory
      cm_remove( 123, CM_OERR );		   /* remove common memory

   EXAMPLE PROGRAMS:
    cm_test : included in shmsub.c

   BUGS:
    cm_map_or_create() is not yet implemented.
    On OS9, cm_remove() may leave the shared memory in the system, if a
    process forgot to call cm_unmap().	If you like you may modify
    cm_remove() to remove completely.

   REFERENCE MANUAL:
    Reference manual below is generated from source file with the command
    "comment shmsub.c".

   /**
    * shmsub  --  shared (common) memory handling subroutines
    *		   Kazuro Furukawa, KEK, Japan (furukawa@kek.jp)
    *		   (if you modified this code, please inform furukawa)
    *
    *	   K.Furukawa, Aug.29.1988. swmodule programs for osk
    *	   K.Furukawa, Jun.3.1992.  shmtest programs for unix
    *	   K.F, Apr.27.1993.	    rewritten for os9 as well as unix
    *	   K.F, Jul.8.1993.	    make library
    *	   K.F, Aug.28.1993.	    add cm_info
    *
    * This package contains shared memory handling routines for unix/os9.
    * (on os9 shared memory is called as a data module.)
    * This module defines these routines.
    *  (int cm_check( key, size, option );)
    *  int cm_create( key, size, option );
    *  void * cm_map_or_create( key, size, option );
    *  void * cm_map( key, option );
    *  int cm_unmap( desc, option );
    *  int cm_remove( key, option );
    *  int cm_info( key, info, option );
    *
    * The basic usage below describes data exchange between two processes.
    *  process A:
    *	cm_create( 123, 1024, CM_PALL, CM_OERR );  /* create common memory
    *	mem = (int *)cm_map( 123, CM_OERR );	   /* map memory
    *	*mem = data;				   /* write data
    *	*(mem+1) = data2;
    *	...
    *	cm_unmap( cm_desc, CM_OERR );		   /* unmap memory
    *  process B:
    *	mem = (int *)cm_map( 123, CM_OERR );	   /* map memory
    *	data = *mem;				   /* read data
    *	data2 = *(mem+1);
    *	...
    *	cm_unmap( cm_desc, CM_OERR );		   /* unmap memory
    *	cm_remove( 123, CM_OERR );		   /* remove common memory
    *
    * shmsub cm_xxx routines are successfully built and executed on
    * ultrix, sun-os, hp-ux sony-os, and os9-68k.
    */

   char	   shmsub_what[] =
   "@(#)shmsub.c v2.3.2 shared memory, K.Furukawa,Kek, Jun.1992-Aug.1993"; /*
   **/

   /**
    *  cm_check
    *	   cm_check examines shared memory existence
    *
    *	 int cm_check( key, option )
    *
    *	   key is the key integer to distinguish from other shared memory
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   -2 CM_OTHER	   other system failure
    *		   -3 CM_EXIST	   memory with key is already existent
    *		   -4 CM_NOEXIST   memory with key is non existent
    */
   int
    cm_check( key, option )
   int key;			   /* key value for the shared memory */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  cm_info
    *	   cm_info examines information on shared memory
    *
    *	 int cm_info( key, info, option )
    *
    *	   key is the key integer to distinguish from other shared memory
    *	   info is the pointer to four long array, which will receive
    *	   size, permission mode, uid, gid
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0		   success
    *		   -2 CM_OTHER	   other system failure
    *		   -4 CM_NOEXIST   memory with key is non existent
    */
   int
    cm_info( key, info, option )
   int key;			   /* key value for the shared memory */
   long info[4];		   /* information of the memory to be returned */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  cm_create
    *	   cm_create allocate new shared memory
    *
    *	 int cm_create( key, size, perm, option )
    *
    *	   key is the key integer to distinguish from other shared memory
    *	   size is the size of the shared memory in byte
    *	   perm is the permisson codes (CM_POWNER, CM_PGRUOP or CM_POTHER)
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0  CM_SUCCESS   success
    *		   -1 CM_NOMEM	   no memory available
    *		   -2 CM_OTHER	   other system failure
    *		   -3 CM_EXIST	   memory with key is already existent
    */
   int
    cm_create( key, size, perm, option )
   int key;			   /* key value for the shared memory */
   int size;			   /* size of the memory to be allocated */
   int perm;			   /* permissions */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  cm_map
    *	   cm_map maps shared memory to user address space
    *
    *	 void * cm_map( key, option )
    *
    *	   key is the key integer to distinguish from other shared memory
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   address	   success
    *		   0		   failure
    *		   global integer cm_errno will contain
    *		   -2 CM_OTHER	   other system failure
    *		   -3 CM_EXIST	   memory with key is already existent
    *		   global void * cm_desc will contain shared memory descriptor
    *		   which will be required to unmap memory
    */
   void *
    cm_map( key, option )
   int key;			   /* key value for the shared memory */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  cm_unmap
    *	   cm_unmap removes shared memory mapping from user address space
    *
    *	 int cm_unmap( desc, option )
    *
    *	   desc is the descriptor which was return from cm_map in cm_desc
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0  CM_SUCCES	   success
    *		   -2 CM_OTHER	   other system failure
    */
   int
    cm_unmap( desc, option )
   void * desc;			   /* shared memory descriptor */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  cm_remove
    *	   cm_remove removes specified shared memory from system
    *
    *	 int cm_remove( key, option )
    *
    *	   key is the key integer to distinguish from other shared memory
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0  CM_SUCCES	   success
    *		   -2 CM_OTHER	   other system failure
    */
   int
    cm_remove( key, option )
   int key;			   /* key value for the shared memory */
   int option;			   /* option 1: error message output */
   /*
   **/