semctl(2)							System Calls Manual							 semctl(2)

NAME

       semctl - Performs semaphore control operations

SYNOPSIS

       #include <sys/sem.h>

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

       Application developers may 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  X/Open
       standards, 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.2

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

PARAMETERS

       Specifies  the  ID  of  the semaphore set.  Specifies the number of the semaphore to be processed.  Specifies the type of command.  See the
       DESCRIPTION section 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:

       Contains  the  semaphore  value	to which semval is set when the SETVAL command is performed.  Points to a structure of type semid_ds. (For
       information about this structure, semid_ds(4).)	When you specify the IPC_STAT command, semctl() copies the contents of the semid_ds struc-
       ture  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.  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 speci-
       fied by the semnum parameter) within the semaphore set identified by semid:

       Returns the value of semval.  This command requires read permission.  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.  Returns the
       value of sempid.  This command requires read permission.  Returns the value of semncnt.	This command requires  read  permission.   Returns
       the value of semzcnt.  This command requires read permission.

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

       Returns	all  the semval values and places them in the array pointed to by arg.array.  This command requires read permission.  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:

       Queries	the semaphore ID by copying the contents of its associated semid_ds structure into the structure pointed to by arg.buf.  This com-
       mand requires read permission.  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.  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 equal to the value of sem_perm.cuid or sem_perm.uid in the  associated  semid_ds
       structure.

RETURN VALUES

       Upon  successful completion, the value returned depends on the cmd parameter as follows: Returns the value of semval.  Returns the value of
       sempid.	Returns the value of semncnt.  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: The calling process does not have the required  per-
       mission.  [Tru64 UNIX]  The cmd parameter is IPC_STAT or IPC_SET and an error occurred in accessing the arg structure.  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.   [Tru64
       UNIX]  The  system  does  not have enough memory to complete the function.  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.
       The cmd parameter is SETVAL or SETALL and the value to which semval is to be set is greater than the system-defined maximum.

RELATED INFORMATION

       Functions: semget(2), semop(2)

       Data structures: semid_ds(4)

       Standards: standards(5) delim off

																	 semctl(2)