Index for Section 2

Alphabetical listing for S

Bottom of page

semctl(2)
NAME
  semctl - Perform semaphore control operations

SYNOPSIS
  #include <sys/sem.h>

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

  Application developers might want to specify #include statements for
  <sys/types.h> and <sys/ipc.h> before the one for <sys/sem.h> if programs
  are being developed for multiple platforms.  The additional #include
  statements are not required on Tru64 UNIX systems or by ISO or XSH
  specifications, but may be required on other vendors' systems that conform
  to these standards.

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

  semctl(): XSH4.0, XSH4.2, XSH5.0

  Refer to the standards(5) reference page for more information about
  industry 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 SETVAL
      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
  commands 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 permission.

  SETVAL
      Sets the value of semval to arg.val. When this command successfully
      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 permission.

  GETNCNT
      Returns the value of semncnt. This command requires read permission.

  GETZCNT
      Returns the value of semzcnt. This command requires read permission.

  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 associated
      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 structure.

NOTES
  The librt library contains alternative interfaces for interprocess
  communication. The names of these routines adhere to the format sem_* and
  their reference pages are listed in SEE ALSO.

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 semval is
      to be set is greater than the system-defined maximum.

SEE ALSO
  Functions: semget(2), semop(2), sem_close(3), sem_destroy(3),
  sem_getvalue(3), sem_init(3), sem_open(3), sem_post(3), sem_unlink(3),
  sem_wait(3)

  Data structures: semid_ds(4)

  Standards: standards(5)

Index for Section 2

Alphabetical listing for S

Top of page