semaphore.h

在SCO UNIX制定界面程序 可根据文件配制菜单,而不必修改源程序,非常方便

/*---------------------------------------------------------------------------*\

  <<Begin Documentation>>
  <<Keyword: semaphore>>

  NAME
      semaphore.h - semaphore routines

  SYNOPSIS
      #include <sys/types.h>
      #include "semaphore.h"

      semaphore sem_create (key, count, permission)
      sem_key key;
      unsigned int count;
      int permission;

      semaphore sem_xlatkey (key)
      sem_key key;

      char *sem_key2str (key)
      sem_key key;

      sem_key sem_str2key (sKey)
      char *sKey;

      sem_key sem_path2key (pathname, discriminant)
      char *pathname;
      int discriminant;

      semaphore sem_str2sem (sSem)
      char *sSem;

      char *sem_sem2str (sem)
      semaphore sem;

      int sem_destroy (sem)
      semaphore sem;

      int sem_access (sem)
      semaphore sem;

      int sem_pend (sem)
      semaphore sem;

      int sem_release (sem)
      semaphore sem;

      int sem_post (sem)
      semaphore sem;

      unsigned int sem_query (sem)
      semaphore sem;

  OPERATING SYSTEM
      This version of the semaphore package is specific to System V-based
      Unix systems.  It can be safely used on any system that provides the
      System V semop(2), semget(2) and semctl(2) IPC primitives.

  DESCRIPTION
      These routines provide an interface to whatever semaphore facilities
      exist on the current operating system.   On System V environments, they
      simplify the interface to the extremely strange System V semaphore
      primitives.  On other operating system, these routines may simply be
      implemented as macros, or they may call local Rabbit routines that
      "build" semaphores from other O/S primitives such as file locking.

      1. sem_create:

      sem_create() creates a semaphore resource.  The "key" parameter specifies
      an interprocess communication (IPC) resource key used to create the
      semaphore. Using a well-known key, one process can create a semaphore
      on behalf of another process; the second process will then convert the
      well-known key to the same semaphore ID to gain access to the semaphore.
      (See the sem_xlatkey() routine.) If you don't care about the key, use
      the "SEM_NO_KEY" macro defined by this header file; this will result in
      the creation of a "private" semaphore.  The "count" parameter specifies
      the desired initial value of the semaphore.  The "permission" parameter
      specifies the desired permission setting of the semaphore; it is
      effectively the same as a file permission mode.  sem_create() returns
      the identifier of the created semaphore or NO_SEM on failure.

      2. sem_xlatkey:

      sem_xlatkey() translates an IPC resource key to a semaphore identifer
      for a previously created semaphore.  The "key" parameter specifies the
      IPC resource key that was used to create the semaphore.  (Note that the
      "SEM_NO_KEY" value is not permitted in a sem_xlatkey() call.)
      sem_xlatkey() returns the identifier of the existing semaphore
      associated with the key, or NO_SEM if no semaphore exists.

      3. sem_str2key:

      sem_str2key() converts a string version of a key to its internal
      representation.  The "sKey" parameter specifies the string to be
      converted.  sem_str2key() returns the converted key, or SEM_NO_KEY
      if the string does not represent a legal key.

      4. sem_key2str:

      sem_key2str() converts an internal (hidden) IPC key to a canonical string
      value which can be safely written to a file.  It returns a pointer to a
      static buffer that is overwritten the next time the routine is called.
      It returns pNULL if the key is in error.

      5. sem_path2key:

      sem_path2key() converts a pathname to an IPC key.  The "pathname"
      parameter specifies the relative or absolute pathname of an existing
      file or directory.  The "discriminant" parameter is used to qualify
      a pathname with an instance identifier.  It is typically used when
      more than one instance of a process exists; all processes use the same
      pathname, but different discriminator values, resulting in different
      keys.   The "discriminator" parameter is defined as an integer for
      portability reasons; it's possible that only part of the value will
      actually be used.  sem_path2key() returns the converted key or SEM_NO_KEY
      on error.

      6. sem_str2sem:

      sem_str2sem() converts a string version of a semaphore to its internal
      representation.  The "sSem" parameter specifies the string to be
      converted.  sem_str2sem() returns the converted semaphore ID, or
      NO_SEM if the string does not represent a legal semaphore ID.  This
      routine exists primarily to hide internal representation of the
      semaphore ID.
      
      7. sem_sem2str:
      
      sem_sem2str() converts an internal (hidden) semaphore ID to a canonical
      string value which can be safely written to a file.  It returns a
      pointer to a static buffer that is overwritten the next time the
      routine is called. It returns pNULL if the semaphore ID is in error.

      8. sem_destroy:

      sem_destroy() destroys a previously created semaphore resource.  It
      returns SUCCEED or FAIL.

      9. sem_access, sem_pend:

      sem_access() attempts to access semaphore resource "sem".  If the
      semaphore value is greater than 0 it is decremented by 1, and
      sem_access() returns immediately.  If the value is 0, the calling
      routine is put to sleep until the semaphore value is incremented by a
      call to sem_release() (presumably by another routine).  sem_access()
      returns SUCCEED or FAIL.

      sem_pend() is a synonym for sem_access(), providing another semantic
      view of the same functionality.

      10. sem_release, sem_post:

      sem_release() attempts to increment semaphore resource "sem".  If any
      processes are pending on the semaphore (because its value was 0), the
      first such process in the semaphore's internal queue will be awakened
      as a result of this call.  sem_release() returns SUCCEED or FAIL.

      sem_post() is a synonym for sem_release(), providing another semantic
      view of the same functionality.

      11. sem_query:

      sem_query() returns the value of semaphore resource "sem" (i.e., the
      count associated with the semaphore) without changing that count.  In
      effect, sem_query() allows a caller to "peek" at a semaphore without
      affecting it in any way.  The return value will either be a non-negative
      number representing the value of the semaphore, or FAIL.

  NOTES
      1. A FAIL return value can result from a variety of operating
      system-dependent errors; errno will be set appropriately if FAIL is
      returned.

      2. Interprocess communication resource keys don't exist on some versions
      of Unix; nevertheless, this interface embodies a world view that assumes
      the existence of such critters.  The assumption is that even if the
      underlying operating system semaphore mechanism doesn't have the concept
      of an IPC key, it will have some way of globally identifying a semaphore
      resource (e.g., a pathname).  From such a global identifier, a key can
      be implemented.  The intent is to keep a common interface regardless of
      the underlying semaphore semantics.

      3. The Rabbit portability header, "rabbit.h", should be included before
      this header file.

  <<End Documentation>>

  Copyright (c) 1992 by Rabbit Software Corporation
\*---------------------------------------------------------------------------*/

#ifndef _SEMAPHORE_H_
#define _SEMAPHORE_H_

#ifdef HEADERVERSIONS
static char * _semaphore_h = "@(#)semaphore.h	1.10 !R2";
#endif /* HEADERVERSIONS */

/*---------------------------------------------------------------------------*\
				 Includes
\*---------------------------------------------------------------------------*/
#include "rtypes.h"
#include "r_sys_ipc.h"

/*---------------------------------------------------------------------------*\
		       Types and Related Definitions
\*---------------------------------------------------------------------------*/

   /*
     Define (1) an opaque semaphore type, (2) an opaque key type, and (3) an
     illegal key value to isolate callers from the port-specific values
     actually used.  SEM_NO_KEY must be set to the value returned by ftok(3)
     on error. Note: If the "key_t" type is unsigned, either the "sem_key"
     typedef or the SEM_NO_KEY value will have to change!
   */
typedef int		semaphore;           /* semaphore ID */
#define NO_SEM		-1                   /* bad semaphore ID */
typedef key_t		sem_key;             /* semaphore resource key */
#define SEM_NO_KEY	-1                   /* illegal key */

/*---------------------------------------------------------------------------*\
	External References for the Functions that Actually Exist.
\*---------------------------------------------------------------------------*/

extern semaphore	sem_create   ( /* sem_key      key,
					  unsigned int count,
					  int          permission */ );
extern semaphore	sem_xlatkey  ( /* sem_key key */ );
extern sem_key		sem_str2key  ( /* char *sKey */ );
extern char	       *sem_key2str  ( /* sem_key key */ );
extern semaphore	sem_str2sem  ( /* char *sSem */ );
extern char	       *sem_sem2str  ( /* semaphore sem */ );
extern int		sem_destroy  ( /* semaphore sem */ );
extern int		sem_query    ( /* semaphore sem */ );
extern int		sem_access   ( /* semaphore sem */ );
extern int		sem_release  ( /* semaphore sem */ );

extern key_t		ftok ();             /* see ftok(3) */

/*---------------------------------------------------------------------------*\
		      Macros for the Other Functions
\*---------------------------------------------------------------------------*/

#define sem_path2key(pathname, discriminant) \
    (ftok (pathname, LOBYTE(discriminant)))

#define sem_pend	sem_access
#define sem_post	sem_release

#endif