semsub



NAME

  semsub - simple binary semaphore handling routines

DESCRIPTION

   semsub.doc
	   Kazuro Furukawa (kazuro.furukawa@kek.jp)
	   Aug.14., Sep.14,25.1993.

   @(#)semsub.doc v1.0.3 K.Furukawa, Aug.1993-Sep.1993

   File semsub.c containes fs_xxx functions for binary semaphore handling.
   These routines are based on swevent programs. These routines are
   available in the hecomsub package, shmsem.tar.Z.

   It supports binary semaphore handling on Unix and OS9 systems.
   On OS9 semaphore is called as event.

   The file semsub.c defines fs_check, fs_create, fs_attach, fs_detach,
   fs_release, fs_wait, fs_remove and fs_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 resource locking between two processes.
     process A:
      fs_create( 123, FS_PALL, FS_OERR );	   /* create semaphore
      id = fs_attach( 123, FS_OERR );		   /* attach semaphore
      ...
      fs_release( id, FS_OERR );		   /* release resource
      ...
      fs_detach( 123, FS_OERR );		   /* detach semaphore
     process B:
      id = fs_attach( 123, FS_OERR );		   /* attach semaphore
      fs_wait( id, FS_OERR );			   /* wait resource
      ...
      fs_remove( 123, FS_OERR );		   /* remove common memory

   EXAMPLE PROGRAMS:
    fs_test : included in semsub.c

   BUGS:
    On OS9, fs_remove() may leave the semaphore in the system, if a
    process forgot to call fs_detach().	 If you like, you may modify
    fs_remove() to remove completely.
    On OS9, fs_info() returns semaphore value only.  The fields for
    permission mode, uid and gid are always zero, since os9 does not
    have such concept for semaphore.

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

   /**
    * semsub  --  simple binary semaphore handling subroutines
    *		   Kazuro Furukawa, KEK, Japan (furukawa@kek.jp)
    *		   (if you modified this code, please inform furukawa)
    *
    *	   K.Furukawa, Jan.6.1987. swevent programs for os9
    *	   K.F, Aug.14.1993.(2)	   semsub for unix and os9
    *	   K.F, Sep.15.1993.	   fs_reset function
    *
    * This package contains simple semaphore handling routines for unix/os9.
    * (on os9 semaphore is called as event.)
    * This module defines these routines.
    *  (int fs_check( key, option );)
    *  int fs_create( key, perm, option );
    *  int fs_attach( key, option );
    *  int fs_detach( key, option );
    *  int fs_release( id, option );
    *  int fs_wait( id, option );
    *  int fs_remove( key, option );
    *  int fs_info( key, info, option );
    *  int fs_reset( key, option );
    *
    * The basic usage below describes wait for resource and release.
    *	fs_create( 123, FS_PALL, FS_OERR );	   /* create semaphore
    *	id = fs_attach( 123, FS_OERR );		   /* use semaphore
    *	fs_release( id, FS_OERR );		   /* release resource
    *	...
    *	fs_wait( id, FS_OERR );			   /* wait resource
    *	...
    *	fs_release( id, FS_OERR );		   /* release resource
    *	...
    *	fs_detach( 123, FS_OERR );		   /* no more use
    *
    * semsub fs_xxx routines are successfully built and executed on
    * ultrix, sun-os, hp-ux sony-os, and os9-68k.
    */

   char	   semsub_what[] =
   "@(#)semsub.c v1.1.0 simple binary semaphore, K.Furukawa,Kek, Aug.1993"; /*
   **/

   /**
    *  fs_check
    *	   fs_check examines semaphore existence
    *
    *	 int fs_check( key, option )
    *
    *	   key is the key integer to distinguish from other semaphore
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   -2 FS_OTHER	   other system failure
    *		   -3 FS_EXIST	   semaphore with key is already existent
    *		   -4 FS_NOEXIST   semaphore with key is non existent
    */
   int
    fs_check( key, option )
   int key;			   /* key value for the semaphore */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  fs_info
    *	   fs_info examines information on semaphore
    *
    *	 int fs_info( key, info, option )
    *
    *	   key is the key integer to distinguish from other semaphore
    *	   info is the pointer to four long array, which will receive
    *	   event value, permission mode, uid, gid
    *	   on OS9 permission mode, uid and gid are are always zero
    *	   (meaningless)
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0		   success
    *		   -2 FS_OTHER	   other system failure
    *		   -3 FS_EXIST	   semaphore with key is already existent
    *		   -4 FS_NOEXIST   semaphore with key is non existent
    */
   int
    fs_info( key, info, option )
   int key;			   /* key value for the semaphore */
   long info[4];		   /* information of the memory to be returned */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  fs_create
    *	   fs_create allocates new semaphore
    *
    *	 int fs_create( key, perm, option )
    *
    *	   key is the key integer to distinguish from other semaphore
    *	   size is the size of the semaphore in byte
    *	   perm is the permisson codes (FS_POWNER, FS_PGRUOP or FS_POTHER)
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0  FS_SUCCESS   success
    *		   -1 FS_NORES	   no memory available
    *		   -2 FS_OTHER	   other system failure
    *		   -3 FS_EXIST	   semaphore with key is already existent
    */
   int
    fs_create( key, perm, option )
   int key;			   /* key value for the semaphore */
   int perm;			   /* permissions */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  fs_attach
    *	   fs_attach returns semaphore id to be used with fs_release or fs_wait
    *
    *	 int fs_attach( key, option )
    *
    *	   key is the key integer to distinguish from other semaphore
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   id		   success
    *		   -2 FS_OTHER	   other system failure
    *		   -4 FS_NOEXIST   semaphore with key is not existent
    */
   int
    fs_attach( key, option )
   int key;			   /* key value for the semaphore */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  fs_detach
    *	   fs_detach terminate to use the semaphore
    *
    *	 int fs_detach( key, option )
    *
    *	   key is the key integer to distinguish from other semaphore
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0		   success
    *		   -2 FS_OTHER	   other system failure
    *		   -4 FS_NOEXIST   semaphore with key is not existent
    */
   int
    fs_detach( key, option )
   int key;			   /* key value for the semaphore */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  fs_release
    *	   fs_release releases (signals) semaphore
    *
    *	 int fs_release( id, option )
    *
    *	   id is the semaphore id which was returned from fs_attach
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0  FS_SUCCES	   success
    *		   -2 FS_OTHER	   other system failure
    */
   int
    fs_release( id, option )
   int id;			   /* semaphore id */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  fs_wait
    *	   fs_wait waits for semaphore to be released
    *
    *	 int fs_wait( id, option )
    *
    *	   id is the semaphore id which was returned from fs_attach
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0  FS_SUCCES	   success
    *		   -2 FS_OTHER	   other system failure
    */
   int
    fs_wait( id, option )
   int id;			   /* semaphore id */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  fs_reset
    *	   fs_reset sets semaphore to initial value
    *
    *	 int fs_reset( id, option )
    *
    *	   id is the semaphore id which was returned from fs_attach
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0  FS_SUCCES	   success
    *		   -2 FS_OTHER	   other system failure
    */
   int
    fs_reset( id, option )
   int id;			   /* semaphore id */
   int option;			   /* option 1: error message output */
   /*
   **/

   /**
    *  fs_remove
    *	   fs_remove removes specified semaphore from system
    *
    *	 int fs_remove( key, option )
    *
    *	   key is the key integer to distinguish from other semaphore
    *	   if option is 1, error message is sent to stderr
    *
    *	 return:   0  FS_SUCCES	   success
    *		   -2 FS_OTHER	   other system failure
    *		   -4 FS_NOEXIST   semaphore with key is not existent
    */
   int
    fs_remove( key, option )
   int key;			   /* key value for the semaphore */
   int option;			   /* option 1: error message output */
   /*
   **/


Man(1) output converted with man2html