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