unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



semctl(2)							    semctl(2)



NAME

  semctl - Performs semaphore control operations

SYNOPSIS

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

  int semctl(
	  int semid,
	  int semnum,
	  int cmd,
	  ...);

  Application developers might 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:

  semctl(): XSH4.2

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

PARAMETERS

  semid	    Specifies the ID of	the semaphore set.

  semnum    Specifies the number of the	semaphore to be	processed.

  cmd	    Specifies the type of command.  See	DESCRIPTION for	a list of
	    available commands.

  The fourth argument is optional and depends on the operation requested.  If
  required, it is of the type union semun, which the application program must
  explicitly declare as	follows:

	  union	semun {
		  int val;
		  struct semid_ds *buf;
		  u_short *array;
	  } arg	);

  The members of this structure	are described as follows:


  val	    Contains the semaphore value to which semval is set	when the SET-
	    VAL	command	is performed.

  buf	    Points to a	structure of type semid_ds. For	information about
	    this structure, see	semid_ds(4).  When you specify the IPC_STAT
	    command, semctl() copies the contents of the semid_ds structure
	    identified by semid	into arg.buf.  When you	specify	the IPC_SET
	    command, semctl() copies the contents of the arg.buf parameter
	    into the semid_ds structure	identified by the semid	parameter.

  array	    Points to an array of semval values.  These	semval values are
	    returned by	the GETALL command and set by the SETALL command.

DESCRIPTION

  The semctl() function	allows a process to perform various operations on an
  individual semaphore within a	semaphore set, on all semaphores within	a
  semaphore set, and on	the semid_ds structure associated with the semaphore
  set.	It also	allows a process to remove the semaphore set's ID and its
  associated semid_ds structure.

  The cmd value	determines which operation is performed.  The following	com-
  mands	operate	on the specified semaphore (that is, the one specified by the
  semnum parameter) within the semaphore set identified	by semid:

  GETVAL    Returns the	value of semval. This command requires read permis-
	    sion.

  SETVAL    Sets the value of semval to	arg.val.  When this command success-
	    fully executes, the	kernel clears the semaphore's adjust-on-exit
	    value in all processes.  This command requires modify permission.

  GETPID    Returns the	value of sempid. This command requires read permis-
	    sion.

  GETNCNT   Returns the	value of semncnt. This command requires	read permis-
	    sion.

  GETZCNT   Returns the	value of semzcnt. This command requires	read permis-
	    sion.

  The following	commands operate on all	the semaphores in the semaphore	set:

  GETALL    Returns all	the semval values and places them in the array
	    pointed to by arg.array.  This command requires read permission.

  SETALL    Sets all the semval	values according to the	array pointed to by
	    arg.array.	When this command successfully executes, the kernel
	    clears the semaphore's adjust-on-exit value	in all processes.
	    This command requires modify permission.

  You can also use the following IPC commands:

  IPC_STAT  Queries the	semaphore ID by	copying	the contents of	its associ-
	    ated semid_ds structure into the structure pointed to by arg.buf.
	    This command requires read permission.

  IPC_SET   Sets the semaphore set by copying the values in the	arg.buf
	    structure into corresponding fields	in the semid_ds	structure
	    associated with the	semaphore ID.  This operation is restricted.
	    The	effective user ID of the calling process must have superuser
	    privilege or must be equal to the value of sem_perm.cuid or
	    sem_perm.uid in the	structure associated with the semaphore	ID.
	    The	fields are set as follows:

	      +	 The sem_perm.uid field	is set to the owner's user ID.

	      +	 The sem_perm.gid field	is set to the owner's group ID.

	      +	 The sem_perm.mode field is set	to the access modes for	the
		 semaphore set.	 Only the low-order nine bits are set.

	      +	 The sem_ctime field is	set to the time	of the last IPC_SET
		 operation.

  IPC_RMID  Removes the	semaphore ID and destroys the set of semaphores	and
	    the	semid_ds data structure	associated with	it.  This operation
	    is restricted.  The	effective user ID of the calling process must
	    have superuser privilege or	be equal to the	value of
	    sem_perm.cuid or sem_perm.uid in the associated semid_ds struc-
	    ture.

RETURN VALUES

  Upon successful completion, the value	returned depends on the	cmd parameter
  as follows:

  GETVAL    Returns the	value of semval.

  GETPID    Returns the	value of sempid.

  GETNCNT   Returns the	value of semncnt.

  GETZCNT   Returns the	value of semzcnt.

  All other commands return a value of 0 (zero).

  If the semctl() function fails, it returns a value of	-1 and sets errno to
  indicate the error.

ERRORS

  The semctl() function	sets errno to the specified values for the following
  conditions:

  [EACCES]  The	calling	process	does not have the required permission.

  [EFAULT]  [Tru64 UNIX]  The cmd parameter is IPC_STAT	or IPC_SET and an
	    error occurred in accessing	the arg	structure.

  [EINVAL]  The	semid parameter	is not a valid semaphore ID; the value of
	    semnum is less than	0 (zero) or greater than sem_nsems; or cmd is
	    not	a valid	command.

  [ENOMEM]  [Tru64 UNIX]  The system does not have enough memory to complete
	    the	function.

  [EPERM]   Either the cmd parameter is	equal to IPC_RMID and the effective
	    user ID of the calling process does	not have appropriate
	    privilege, or the cmd parameter is equal to	IPC_SET	and the
	    effective user ID of the calling process is	not equal to the
	    value of sem_perm.cuid or sem_perm.uid in the semid_ds structure
	    associated with the	semaphore ID.

  [ERANGE]  The	cmd parameter is SETVAL	or SETALL and the value	to which sem-
	    val	is to be set is	greater	than the system-defined	maximum.

SEE ALSO

  Functions: semget(2),	semop(2)


  Data structures: semid_ds(4)

  Standards: standards(5)