unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



semget(2)							    semget(2)



NAME

  semget - Returns (and	possibly creates) a semaphore ID

SYNOPSIS

  #include <&lt;sys/sem.h>&gt;

  int semget(
	  key_t	key,
	  int nsems,
	  int semflg);

  Application developers may want to specify #include statements for
  <&lt;sys/types.h>&gt;	and <&lt;sys/ipc.h>&gt;	before the one for <&lt;sys/sem.h>&gt; if programs
  are being developed for multiple platforms. The additional #include state-
  ments	are not	required on Tru64 UNIX systems or by ISO or X/Open standards,
  but may be required on other vendors'	systems	that conform to	these stan-
  dards.

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  semget():  XPG4, XPG4-UNIX

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  key	    Specifies the key that identifies the semaphore set.  The value
	    for	the key	parameter can be IPC_PRIVATE or	a random number	other
	    than 0 (zero).  To ensure that you receive a new, unused entry in
	    the	semaphore table, specify IPC_PRIVATE as	the value of key.

  nsems	    Specifies the number of semaphores to create in the	semaphore
	    set.

  semflg    Specifies the creation flags.  Possible values are as follows:

	    IPC_CREAT If the key specified does	not exist, the semget func-
		      tion creates a semaphore ID using	the specified key.

		      If the specified key exists, and IPC_EXCL	is not set,
		      the semaphore id for the specified key is	returned.

		      If the specified key exists and IPC_EXCL is set, the
		      semget function fails and	returns	an error.

	    IPC_EXCL  Specifies	that you want exclusive	access to the sema-
		      phore set.

		      If the specified key already exists, the semget func-
		      tion fails and returns an	error notification.



DESCRIPTION

  The system defines sets of semaphores	in a system-wide table,	with each set
  being	an entry in the	table.	The semget() function returns an ID that
  identifies the semaphore set's entry in the table.  You determine which
  semaphore set's ID is	returned by specifying the key parameter.

  The semget() function	creates	a semaphore set	containing nsems semaphores
  and returns its ID in	the following situations:

    +  The key parameter is IPC_PRIVATE.

    +  The key parameter does not already exist	as an entry in the semaphore
       table and the IPC_CREAT flag is set.

  To create a semaphore	set, the semget() function creates and initializes a
  structure of type semid_ds, which is defined as follows:

  struct semid_ds {
	  struct ipc_perm     sem_perm;
	  struct sem	      *sem_base;
	  ushort_t	      sem_nsems;
	  time_t	      sem_otime;
	  time_t	      sem_ctime;
  };

  For a	complete description of	this structure,	see semid_ds(4).  The
  semget() function initializes	the structure as follows:

    +  The sem_perm.cuid and sem_perm.uid fields are set equal to the effec-
       tive user ID of the calling process.

    +  The sem_perm.cgid and sem_perm.gid fields are set equal to the effec-
       tive group ID of	the calling process.

    +  The low-order nine bits of sem_perm.mode	are set	equal to the low-
       order nine bits of semflg.

    +  The sem_nsems field is set equal	to the value of	nsems.

    +  The sem_otime field is set equal	to zero	(0) and	the sem_ctime field
       is set equal to the current time.

  The individual semaphores within a set are implemented using the sem struc-
  ture.	(For more information about this structure, see	the <&lt;sys/sem.h>&gt;
  header file.)	The semget function does not initialize	the sem	structure
  associated with each semaphore in the	set.  The individual semaphores	are
  initialized when you call the	semctl function	with the SETVAL	or SETALL
  command.

RETURN VALUES

  Upon successful completion, the semget() function returns a semaphore	iden-
  tifier.  If the semget function fails, it returns a value of -1 and sets
  errno	to indicate the	error.

ERRORS

  The semget function sets errno to the	specified values for the following
  conditions:

  [EACCES]  A semaphore	ID already exists for the key parameter, but opera-
	    tion permission as specified by the	low-order nine bits of the
	    semflg parameter was not granted.

  [EEXIST]  A semaphore	ID already exists for the key parameter, but
	    IPC_CREAT and IPC_EXCL were	used for the semflg parameter.

  [EINVAL]  The	value of the nsems parameter is	less than or equal to 0
	    (zero) or greater than the system-defined limit.  Or, a semaphore
	    ID already exists for the key parameter, but the number of sema-
	    phores in the set is less than the nsems parameter,	and the	nsems
	    parameter is not equal to 0	(zero).

  [ENOENT]  A semaphore	ID does	not exist for the key parameter	and IPC_CREAT
	    was	not set.

  [ENOSPC]  An attempt to create a new semaphore ID exceeded the system-wide
	    limit on the size of the semaphore table.

RELATED	INFORMATION

  Functions: semctl(2),	semop(2), table(2), ftok(3)

  Files: semid_ds(4), sysconfigtab(4)

  Standards: standards(5)