<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>semctl()-Perform Semaphore Control Operations</title> <!-- Begin Header Records ========================================== --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 --> <!-- Edited by Kersten Feb 02 --> <!-- This file has undergone error condition cleanup on 05/01/02 by JET --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <!--End Header Records --> <!-- Java sync-link --> <script type="text/javascript" language="Javascript" src="../rzahg/synch.js"> </script> <a name="Top_Of_Page"></a> <h2>semctl()--Perform Semaphore Control Operations</h2> <div class="box" style="width: 70%;"> <br> Syntax<br> <pre> #include <sys/sem.h> int semctl(int <em>semid</em>, int <em>semnum</em>, int <em>cmd</em>, ...); </pre> <br> Service Program Name: QP0ZCPA<br> <!-- iddvc RMBR --> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Threadsafe: Yes<br> <!-- iddvc RMBR --> <br> </div> <p>The <strong>semctl()</strong> function allows the caller to control the semaphore set specified by the <em>semid</em> parameter.</p> <p>A semaphore set is controlled by setting the <em>cmd</em> parameter to one of the following values: <dl> <dt><strong>IPC_RMID (0x00000000)</strong></dt> <dd>Remove the semaphore set identifier <em>semid</em> from the system and destroy the set of semaphores. Any threads that are waiting in <strong>semop()</strong> are woken up and <strong>semop()</strong> returns with a return value of -1 and <em>errno</em> set to EIDRM. <p>The IPC_RMID command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the semaphore set. <p></dd> <dt><strong>IPC_SET (0x00000001)</strong></dt> <dd>Set the user ID of the owner, the group ID of the owner, and the permissions for the semaphore set to the values in the <samp>sem_perm.uid</samp>, <samp>sem_perm.gid</samp>, and <samp>sem_perm.mode</samp> members of the <samp>semid_ds</samp> data structure pointed to by the fourth parameter. <p>The IPC_SET command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the semaphore set.</p> <p></dd> <dt><strong>IPC_STAT (0x00000002)</strong></dt> <dd>Store the current value of each member of the <samp>semid_ds</samp> data structure into the structure pointed to by the fourth parameter. The IPC_STAT command requires read permission to the semaphore set. <p></dd> <dt><strong>GETNCNT (0x00000003)</strong></dt> <dd>Return the number of threads waiting for the value of semaphore <em>semnum</em> to increase. This value is the <samp>semncnt</samp> value in the <samp>semaphore_t</samp> data structure associated with the specified semaphore. The GETNCNT command requires read permission to the semaphore set. <p></dd> <dt><strong>GETPID (0x00000004)</strong></dt> <dd>Return the process ID of the last thread to operate on semaphore <em>semnum</em>. This value is the <samp>sempid</samp> value in the <samp>semaphore_t</samp> data structure associated with the specified semaphore. The GETPID command requires read permission to the semaphore set. <p></dd> <dt><strong>GETVAL (0x00000005)</strong></dt> <dd>Return the current value of semaphore <em>semnum</em>. This value is the <samp>semval</samp> value in the <samp>semaphore_t</samp> data structure associated with the specified semaphore. The GETVAL command requires read permission to the semaphore set. <p></dd> <dt><strong>GETALL (0x00000006)</strong></dt> <dd>Return the values of each semaphore in the semaphore set into the array pointed to by the fourth parameter, which is a pointer to an array of type <samp>unsigned short</samp>. The values are the <samp>semval</samp> value in the <samp>semaphore_t</samp> data structure associated with each semaphore in the semaphore set. The GETALL command requires read permission to the semaphore set. <p></dd> <dt><strong>GETZCNT (0x00000007)</strong></dt> <dd>Return the number of threads waiting for the value of semaphore <em>semnum</em> to reach zero. This value is the <samp>semzcnt</samp> value in the <samp>semaphore_t</samp> data structure associated with the specified semaphore. The GETZCNT command requires read permission to the semaphore set. <p></dd> <dt><strong>SETVAL (0x00000008)</strong></dt> <dd>Set the value of semaphore <em>semnum</em> to the integer value of type <samp>int</samp> specified in the fourth parameter and clear the associated per-thread semaphore adjustment value. The SETVAL command requires write permission to the semaphore set. <p></dd> <dt><strong>SETALL (0x00000009)</strong></dt> <dd>Set the values of each semaphore in the semaphore set to the values contained in the array pointed to by the fourth parameter, which is a pointer to an array of type <samp>unsigned short</samp>. In addition, the associated per-thread semaphore-adjustment value is cleared for each semaphore. The SETALL command requires write permission to the semaphore set. <p></dd> </dl> <br> <h3>Parameters</h3> <dl> <dt><strong>semid</strong></dt> <dd>(Input) Semaphore set identifier, a positive integer. It is returned by the <a href="ipcsemgt.htm">semget()</a> function and used to identify the semaphore set on which to perform the control operation.<br> <br> </dd> <dt><strong>semnum</strong></dt> <dd>(Input) Semaphore number, a non-negative integer. It identifies a semaphore within the semaphore set on which to perform the control operation.<br> <br> </dd> <dt><strong>cmd</strong></dt> <dd>(Input) Command, the control operation to perform on the semaphore set. Valid values are listed above.<br> <br> </dd> <dt><strong>...</strong></dt> <dd>(Input/output) An optional fourth parameter whose type depends on the value of <em>cmd</em>. For the <em>cmd</em> SETVAL, this parameter must be an integer of type <samp>int</samp>. For the <em>cmd</em> IPC_STAT or IPC_SET, this parameter must be a pointer to a <samp>semid_ds</samp> structure. For the <em>cmd</em> GETALL or SETALL, this parameter must be a pointer to an array of type <samp> unsigned short</samp>. For all other values of <em>cmd</em>, this parameter is not required. <p>The members of the <samp>semid_ds</samp> structure are as follows:</p> </dd> </dl> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em>struct ipc_perm sem_perm</em> </td> <td align="left" valign="top">The members of the <samp>ipc_perm</samp> structure are as follows: <table cellpadding="5"> <tr> <td align="left" valign="top"><em>uid_t uid</em> </td> <td align="left" valign="top">The user ID of the owner of the semaphore set.</td> </tr> <tr> <td align="left" valign="top"><em>gid_t gid</em> </td> <td align="left" valign="top">The group ID of the owner of the semaphore set.</td> </tr> <tr> <td align="left" valign="top"><em>uid_t cuid</em> </td> <td align="left" valign="top">The user ID of the creator of the semaphore set.</td> </tr> <tr> <td align="left" valign="top"><em>gid_t cgid</em> </td> <td align="left" valign="top">The group ID of the creator of the semaphore set.</td> </tr> <tr> <td align="left" valign="top"><em>mode_t mode</em> </td> <td align="left" valign="top">The permissions for the semaphore set.</td> </tr> </table> </td> </tr> <tr> <td align="left" valign="top"><em>unsigned short sem_nsems</em> </td> <td align="left" valign="top">The number of semaphores in the set.</td> </tr> <tr> <td align="left" valign="top"><em>time_t sem_otime</em> </td> <td align="left" valign="top">The time the last thread operated on the semaphore set using <strong>semop()</strong>.</td> </tr> <tr> <td align="left" valign="top"><em>time_t sem_ctime</em> </td> <td align="left" valign="top">The time the last thread changed the semaphore set using <strong>semctl()</strong>.</td> </tr> </table> <br> <br> <h3>Authorities</h3> <p><strong><a name="TBLASCTL1">Authorization Required for semctl()</a></strong></p> <table border cellpadding="5"> <!-- cols="60 20 20" --> <tr> <th align="left" valign="bottom">Object Referred to</th> <th align="left" valign="bottom">Authority Required</th> <th align="left" valign="bottom">errno</th> </tr> <tr> <td align="left" valign="top">Semaphore, get the value of (<em>cmd</em> = GETVAL)</td> <td align="left" valign="top">Read</td> <td align="left" valign="top">EACCES</td> </tr> <tr> <td align="left" valign="top">Semaphore, set the value of (<em>cmd</em> = SETVAL)</td> <td align="left" valign="top">Write</td> <td align="left" valign="top">EACCES</td> </tr> <tr> <td align="left" valign="top">Semaphore, get last process to operate on (<em>cmd</em> = GETPID)</td> <td align="left" valign="top">Read</td> <td align="left" valign="top">EACCES</td> </tr> <tr> <td align="left" valign="top">Semaphore, get number of threads waiting for value to increase (<em>cmd</em> = GETNCNT)</td> <td align="left" valign="top">Read</td> <td align="left" valign="top">EACCES</td> </tr> <tr> <td align="left" valign="top">Semaphore, get number of threads waiting for value to reach zero (<em>cmd</em> = GETZCNT)</td> <td align="left" valign="top">Read</td> <td align="left" valign="top">EACCES</td> </tr> <tr> <td align="left" valign="top">Semaphore set, get value of each semaphore (<em>cmd</em> = GETALL)</td> <td align="left" valign="top">Read</td> <td align="left" valign="top">EACCES</td> </tr> <tr> <td align="left" valign="top">Semaphore set, set value of each semaphore (<em>cmd</em> = SETALL)</td> <td align="left" valign="top">Write</td> <td align="left" valign="top">EACCES</td> </tr> <tr> <td align="left" valign="top">Semaphore set, retrieve state information (<em>cmd</em> = IPC_STAT)</td> <td align="left" valign="top">Read</td> <td align="left" valign="top">EACCES</td> </tr> <tr> <td align="left" valign="top">Semaphore set, set state information (<em>cmd</em> = IPC_SET)</td> <td align="left" valign="top">See Note</td> <td align="left" valign="top">EPERM</td> </tr> <tr> <td align="left" valign="top">Semaphore set, remove (<em>cmd</em> = IPC_RMID)</td> <td align="left" valign="top">See Note</td> <td align="left" valign="top">EPERM</td> </tr> </table> <p><strong>Note:</strong> To set semaphore set information or to remove a semaphore set, the thread must be the owner or creator of the semaphore set, or have appropriate privileges.</p> <br> <h3>Return Value</h3> <table cellpadding="5"> <!-- cols="15 85" --> <tr> <td align="left" valign="top"><em>value</em></td> <td align="left" valign="top"><strong>semctl()</strong> was successful. Depending on the control operation specified in <em>cmd</em>, <strong> semctl()</strong> returns the following values:<br> <table cellpadding="5"> <tr> <td align="left" valign="top"><em>GETVAL</em></td> <td align="left" valign="top">The value of the specified semaphore.</td> </tr> <tr> <td align="left" valign="top"><em>GETPID</em></td> <td align="left" valign="top">The process ID of the last thread that performed a semaphore operation on the specified semaphore.</td> </tr> <tr> <td align="left" valign="top"><em>GETNCNT</em></td> <td align="left" valign="top">The number of threads waiting for the value of the specified semaphore to increase.</td> </tr> <tr> <td align="left" valign="top"><em>GETZCNT</em></td> <td align="left" valign="top">The number of threads waiting for the value of the specified semaphore to reach zero.</td> </tr> <tr> <td align="left" valign="top"><em>For all other values of</em> cmd:</td> <td align="left" valign="top">The value is 0.</td> </tr> </table> <br> </td> </tr> <tr> <td align="left" valign="top"><em>-1</em></td> <td align="left" valign="top"><strong>semctl()</strong> was not successful. The <em>errno</em> variable is set to indicate the error.</td> </tr> </table> <br> <br> <h3>Error Conditions</h3> <p>If <strong>semctl()</strong> is not successful, <em>errno</em> usually indicates one of the following errors. Under some conditions, <em>errno</em> could indicate an error other than those listed here.</p> <dl compact> <dt><em>[EACCES]</em></dt> <dd> <p>Permission denied.</p> <p>An attempt was made to access an object in a way forbidden by its object access permissions.</p> <p>The thread does not have access to the specified file, directory, component, or path.</p> <p>The <em>cmd</em> parameter is IPC_STAT, GETVAL, GETPID, GETNCNT, GETZCNT, or GETALL and the calling thread does not have read permission to the semaphore set.</p> <p>The <em>cmd</em> parameter is SETVAL, or SETALL and the calling thread does not have write permission to the semaphore set.</p> </dd> <dt><em>[EDAMAGE]</em></dt> <dd> <p>A damaged object was encountered.</p> <p>A referenced object is damaged. The object cannot be used.</p> <p>The semaphore set has been damaged by a previous semaphore operation.</p> </dd> <dt><em>[EFAULT]</em></dt> <dd> <p>The address used for an argument is not correct.</p> <p>In attempting to use an argument in a call, the system detected an address that is not valid.</p> <p>While attempting to access a parameter passed to this function, the system detected an address that is not valid.</p> </dd> <dt><em>[EINVAL]</em></dt> <dd> <p>The value specified for the argument is not correct.</p> <p>A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.</p> <p>An argument value is not valid, out of range, or NULL.</p> <p>One of the following has occurred:</p> <ul> <li>The <em>semid</em> parameter is not a valid semaphore identifier.</li> <li>The <em>semnum</em> parameter is less than zero or greater than or equal to <samp>sem_nsems</samp>.</li> <li>The <em>cmd</em> parameter is not a valid command.<p></li> </ul> </dd> <dt><em>[EPERM]</em></dt> <dd> <p>Operation not permitted.</p> <p>You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.</p> <p>The <em>cmd</em> parameter is IPC_RMID or IPC_SET and both of the following are true:</p> <ul> <li>the calling thread does not have appropriate privileges.</li> <li>the effective user ID of the calling thread is not equal to the user ID of the owner or the user ID of the creator of the semaphore set.</li> </ul> <p></dd> <dt><em>[ERANGE]</em></dt> <dd> <p>A range error occurred.</p> <p>The value of an argument is too small, or a result too large.</p> <p>The <em>cmd</em> parameter is SETVAL, and the value to which <samp> semval</samp> is to be set is greater than the system-imposed maximum.</p> </dd> <dt><em>[EUNKNOWN]</em></dt> <dd> <p>Unknown system state.</p> <p>The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.</p> </dd> </dl> <br> <h3>Error Messages</h3> <p>None.</p> <br> <h3><a name="USAGE_NOTES">Usage Notes</a></h3> <ol> <li>"Appropriate privileges" is defined to be *ALLOBJ special authority. If the user profile under which the thread is running does not have *ALLOBJ special authority, the thread does not have appropriate privileges.<p></li> <li>Take care when using a union for the optional fourth parameter. If the optional fourth parameter is an integer, <strong>semctl()</strong> expects it to directly follow the third parameter in storage. But a union that contains a pointer is aligned on a 16-byte boundary, which might not directly follow the third parameter. Therefore, the value used by <strong>semctl()</strong> for the fourth parameter might not be the value intended by the caller, and unexpected results could occur.<p></li> </ol> <br> <h3>Related Information</h3> <ul> <li>The <<strong>sys/sem.h</strong>> file (see <a href="unix13.htm"> Header Files for UNIX-Type Functions</a>)<br> <br> </li> <li><a href="ipcsemgt.htm">semget()</a>--Get Semaphore Set with Key<br> <br> </li> <li><a href="ipcsemop.htm">semop()</a>--Perform Semaphore Operations on Semaphore Set</li> </ul> <br> <h3>Example</h3> <p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a> for information pertaining to code examples.</p> <p>For an example of using this function, see <a href="../apiref/apiexusmem.htm"> Using Semaphores and Shared Memory</a> in Examples: APIs.</p> <br> <hr> API introduced: V3R6 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </center> </body> </html>