221 lines
8.5 KiB
HTML
221 lines
8.5 KiB
HTML
<!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>Semaphore Set Functions</title>
|
|
<!-- 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. -->
|
|
<!-- Begin Header Records ========================================= -->
|
|
<!-- 050119 JETAYLOR new for V5R4 -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="Top_Of_Page"></a>
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
|
|
|
|
<h2><a name="semaphoresets">Semaphore Set Functions</a></h2>
|
|
|
|
<p>A <strong>semaphore</strong> is a synchronization mechanism similar to a
|
|
mutex or a machine interface (MI) lock. It can be used to control access to
|
|
shared resources, or used to notify other threads of the availability of
|
|
resources. It differs from a mutex in the following ways:</p>
|
|
|
|
<ul>
|
|
<li>A semaphore set is not a single value, but has a set of values. It is
|
|
referred to through a <strong>semaphore set</strong> containing multiple
|
|
semaphores. Each semaphore set is identified by a <em>semid</em>, which
|
|
identifies the semaphore set, and a <em>semnum</em>, which identifies the
|
|
semaphore within the set. Multiple semaphore operations may be specified on one
|
|
<strong>semop()</strong> call. These operations are atomic on multiple
|
|
semaphores within a semaphore set.<br><br></li>
|
|
|
|
<li>Semaphore values can range from 0 to 65535.<br><br></li>
|
|
|
|
<li>Semaphores have <strong>permissions</strong> associated with them. A thread
|
|
must have appropriate authorities to perform an operation on a semaphore.<br><br></li>
|
|
|
|
<li>A semaphore can have a <strong>semaphore adjustment value</strong>
|
|
associated with it. This value represents resource allocations which can be
|
|
automatically undone by the system when the thread ends, representing the
|
|
releasing of resources. The adjustment value can range from -32767 to
|
|
32767.</li>
|
|
</ul>
|
|
|
|
<p>Thus, a semaphore can be used as a resource counter or as a lock.</p>
|
|
|
|
<p>A process gets a semaphore set identifier by calling the <strong>
|
|
semget()</strong> function. Depending on the <em>key</em> and <em>semflg</em>
|
|
parameters passed in, either a new semaphore set is created or an existing
|
|
semaphore set is accessed. When a new semaphore set is created, a data
|
|
structure is also created to contain information about the semaphore set. This
|
|
structure is defined in the <strong><sys/sem.h></strong> header file as
|
|
follows:</p>
|
|
|
|
<pre>
|
|
typedef struct semid_ds {
|
|
struct ipc_perm sem_perm; /* Permissions structure */
|
|
unsigned short sem_nsems; /* Number of sems in set */
|
|
time_t sem_otime; /* Last sem op time */
|
|
time_t sem_ctime; /* Last change time */
|
|
} semtablentry_t;
|
|
</pre>
|
|
|
|
<p>A thread performs operations on one or more of the semaphores in a set by
|
|
calling the <strong>semop()</strong> function. The following parameters are
|
|
passed in:</p>
|
|
|
|
<ul>
|
|
<li>Semaphore ID</li>
|
|
|
|
<li>Pointer to an array of <samp>sembuf</samp> structures</li>
|
|
|
|
<li>Number of <samp>sembuf</samp> structures in the array.</li>
|
|
</ul>
|
|
|
|
<p>The <samp>sembuf</samp> structure is defined in the <strong>
|
|
<sys/sem.h></strong> header file as follows:</p>
|
|
|
|
<pre>
|
|
struct sembuf {
|
|
unsigned short sem_num; /* Semaphore number */
|
|
short sem_op; /* Semaphore operation */
|
|
short sem_flg; /* Operation flags */
|
|
};
|
|
|
|
</pre>
|
|
|
|
<p>The operation performed on a semaphore is specified by the <samp>sem_op</samp>
|
|
field, which can be positive, negative, or zero:</p>
|
|
|
|
<ul>
|
|
<li>If <samp>sem_op</samp> is positive, the value of <samp>sem_op</samp> is added to
|
|
the semaphore's current value.</li>
|
|
|
|
<li>If <samp>sem_op</samp> is zero, the caller will wait until the semaphore's
|
|
value becomes zero.</li>
|
|
|
|
<li>If <samp>sem_op</samp> is negative, the caller will wait until the semaphore's
|
|
value is greater than or equal to the absolute value of <samp>sem_op</samp>. Then
|
|
the absolute value of <samp>sem_op</samp> is subtracted from the semaphore's
|
|
current value.</li>
|
|
</ul>
|
|
|
|
<p>The <samp>sem_flg</samp> value specifies whether or not the thread is willing to
|
|
wait, and also whether or not the thread wants the system to keep a semaphore
|
|
adjustment value for the semaphore.</p>
|
|
|
|
<p>Semaphore waits are visible from the Work with Active Jobs display. A thread
|
|
waiting on a semaphore in a semaphore set appears to be in a semaphore wait
|
|
state (SEMW) on the Work with Threads display (requested using the WRKJOB
|
|
command and taking option 20). Displaying the call stack of the thread shows
|
|
the <strong>semop()</strong> function near the bottom of the stack.</p>
|
|
|
|
<p>A thread removes a semaphore set ID by calling the <strong>semctl()</strong>
|
|
function. The thread also can use the <strong>semctl()</strong> function to
|
|
change the data structure values associated with the semaphore set ID or to
|
|
retrieve the data structure values associated with the semaphore set ID. The
|
|
following parameters are passed in:</p>
|
|
|
|
<ul>
|
|
<li>Semaphore set ID</li>
|
|
|
|
<li>Command the thread wants to perform (remove ID, set data structure values,
|
|
receive data structure values),</li>
|
|
|
|
<li>Pointer to a buffer from which to set data structure values, or in which to
|
|
receive data structure values.</li>
|
|
</ul>
|
|
|
|
<p>In addition, the <strong>semctl()</strong> function can perform various
|
|
other control operations on a specific semaphore within a set, or on an entire
|
|
semaphore set:</p>
|
|
|
|
<ul>
|
|
<li>Set or retrieve a semaphore value.</li>
|
|
|
|
<li>Retrieve the process ID of the last thread to operate on a semaphore.</li>
|
|
|
|
<li>Retrieve the number of threads waiting for a semaphore value to
|
|
increase.</li>
|
|
|
|
<li>Retrieve the number of threads waiting for a semaphore value to become
|
|
zero.</li>
|
|
|
|
<li>Retrieve the value of every semaphore in a semaphore set.</li>
|
|
|
|
<li>Set the value of every semaphore in a semaphore set.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
<h4>Semaphore Set Differences and Restrictions</h4>
|
|
|
|
<p>i5/OS semaphore sets differ from the definition in the Single
|
|
UNIX Specification in the following ways:</p>
|
|
|
|
<ul>
|
|
<li>The Single UNIX Specification does not define threads. Consequently,
|
|
Single UNIX Specification semaphores are defined in terms of processes and the semaphore:
|
|
|
|
<ul>
|
|
<li>Causes the entire process to wait</li>
|
|
|
|
<li>Releases resources when the process ends</li>
|
|
</ul>
|
|
|
|
i5/OS handles semaphores at the thread level. An i5/OS semaphore:<br>
|
|
|
|
<ul>
|
|
<li>Causes only a single thread to wait</li>
|
|
|
|
<li>Releases resources when the thread ends</li>
|
|
</ul><br>
|
|
</li>
|
|
|
|
<li>The maximum number of semaphore sets that can be created (system-wide) is
|
|
2 147 483 646.<br><br></li>
|
|
|
|
<li>The maximum number of semaphores per semaphore set is 65535.<br><br></li>
|
|
|
|
<li>Semaphores values are limited to the range from 0 to 65535. Adjustment
|
|
values associated with a semaphore are limited to the range -32767 to
|
|
32767.</li>
|
|
</ul>
|
|
|
|
<p>The semaphore set functions are:</p>
|
|
<!-- ***** NOTE ***** Do not manually update text or links in this section. -->
|
|
<!-- Updates made in this section *will* be overlaid by automated tools -->
|
|
<!-- Notify User Technologies of needed updates to be made in XML for API finder.-->
|
|
<!--***************API BEGIN PASTE***************-->
|
|
<ul>
|
|
<li><A HREF="ipcsemct.htm">semctl()</A> (Perform Semaphore Control Operations) provides semaphore control operations as specified by cmd on the semaphore specified by semnum in the semaphore set specified by semid.</li>
|
|
<li><A HREF="ipcsemgt.htm">semget()</A> (Get Semaphore Set with Key) returns the semaphore ID associated with the specified semaphore key.</li>
|
|
<li><A HREF="ipcsemop.htm">semop()</A> (Perform Semaphore Operations on Semaphore Set) performs operations on semaphores in a semaphore set. These operations are supplied in a user-defined array of operations.</li>
|
|
</ul>
|
|
<!--***************API END PASTE***************-->
|
|
|
|
<p>See also <a href="unix3a4.htm">IPC Key Generation Functions</a> for additional semaphore set functions.</p>
|
|
|
|
<br>
|
|
|
|
<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>
|
|
|