143 lines
9.6 KiB
HTML
143 lines
9.6 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>Pointer Based Services</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 ========================================= -->
|
||
|
|
<!-- UNIX3 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB at -->
|
||
|
|
<!-- RCHVMW2 on 1 Jun 1999 at 16:14:49 -->
|
||
|
|
<!-- File created for V5R2 -->
|
||
|
|
<!-- 031112 JETAYLOR replaced API and/or Exit listings with -->
|
||
|
|
<!-- pagegenerator output from javascript array -->
|
||
|
|
<!-- 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>Pointer Based Services</h2>
|
||
|
|
|
||
|
|
<p>The pointer based services consist of named and unnamed semaphores.
|
||
|
|
The named and unnamed semaphores on i5/OS<SUP>(R)</SUP> differ from the other IPC
|
||
|
|
mechanisms in that they do not have an IPC identifier
|
||
|
|
associated with them. Instead, pointers to the semaphore are used to operate on
|
||
|
|
the semaphore. Before using a semaphore, a process must obtain a pointer to the
|
||
|
|
semaphore. Unlike a semaphore set, a named or unnamed semaphore refers to
|
||
|
|
a single semaphore only. A semaphore contains a value, a maximum value, and a
|
||
|
|
title.</p>
|
||
|
|
|
||
|
|
<p>There are two types of semaphores: named semaphores and unnamed semaphores. Once a
|
||
|
|
semaphore is created and a pointer to the semaphore is obtained, the same
|
||
|
|
operations are used to manipulate the values of both types of semaphores. Like
|
||
|
|
the semaphores in a semaphore set, a named or unnamed semaphore has a nonzero
|
||
|
|
value. A semaphore can be used as a resource counter or as a lock. A thread
|
||
|
|
decrements a semaphore to obtain one or more associated resources, and
|
||
|
|
increments the semaphore to release the resource. A semaphore also has a
|
||
|
|
maximum value associated with it. An attempt to increment the value of a
|
||
|
|
semaphore above its maximum value results in an error.</p>
|
||
|
|
|
||
|
|
<p>Besides a value, named and unnamed semaphores contain a maximum value and a
|
||
|
|
title. The maximum value sets the highest value that the semaphore value may
|
||
|
|
obtain. The title is a null-terminated string with a maximum size of 16
|
||
|
|
characters that are associated with the semaphore and may be used to contain
|
||
|
|
debugging information. The titles associated with named and unnamed semaphores
|
||
|
|
may be obtained by using the <strong>QP0ZOLIP()</strong> API.</p>
|
||
|
|
|
||
|
|
<p>A process obtains a pointer to a named semaphore by calling the <strong>
|
||
|
|
sem_open()</strong> or <strong>sem_open_np()</strong> functions. These
|
||
|
|
functions find the semaphore associated with a name. The name is a character
|
||
|
|
string, interpreted in the CCSID of the job. The name may be structured so that
|
||
|
|
it looks like a pathname. This name, however, has no relationship to any file
|
||
|
|
system. If the semaphore exists and the process has permission to use the
|
||
|
|
semaphore, then the system allocates memory for the semaphore and returns a
|
||
|
|
pointer to the caller. If the semaphore does not exist, it will be created if
|
||
|
|
the appropriate flags are set. When a new named semaphore is created, the
|
||
|
|
permissions of the semaphore are set using the information provided by the <em>
|
||
|
|
mode</em> parameter. These permissions are the same as those used by the
|
||
|
|
identifier- based IPC services. The <strong>sem_open_np()</strong> function
|
||
|
|
permits the caller to set the maximum value and title of a semaphore when
|
||
|
|
creating a named semaphore. When a process is finished using a named semaphore,
|
||
|
|
it should call <strong>sem_close()</strong> to close the semaphore. The
|
||
|
|
semaphore is also explicitly closed when a process terminates. When a named
|
||
|
|
semaphore will no longer be needed, it can be removed from the system using
|
||
|
|
<strong>sem_unlink()</strong>.</p>
|
||
|
|
|
||
|
|
<p>A process obtains a pointer to an unnamed semaphore calling the <strong>
|
||
|
|
sem_init()</strong> or <strong>sem_init_np()</strong> functions. These
|
||
|
|
functions initialize a semaphore at the specified memory location. The <strong>
|
||
|
|
sem_init_np()</strong> function permits the caller to set the maximum value and
|
||
|
|
title of a unnamed semaphore when it is created. When a process is finished
|
||
|
|
using an unnamed semaphore, it should call <strong>sem_destroy()</strong> to
|
||
|
|
destroy the semaphore and release system resources associated with that
|
||
|
|
semaphore.</p>
|
||
|
|
|
||
|
|
<p>A process decrements by one the value of a semaphore using the <strong>
|
||
|
|
sem_wait()</strong> and <strong>sem_wait_np()</strong> functions. If the value
|
||
|
|
of the semaphore is currently zero, then the thread is blocked until the value
|
||
|
|
of the semaphore is incremented or until the time specified on the <strong>
|
||
|
|
sem_wait_np()</strong> has expired. The <strong>sem_trywait()</strong> call may
|
||
|
|
be used to decrement the value of the semaphore if it is greater than zero. If
|
||
|
|
the current value of the semaphore is zero, then <strong>sem_trywait()</strong>
|
||
|
|
will return an error. The <strong>sem_post()</strong>and <strong>
|
||
|
|
sem_post_np()</strong>functions are used to increment the value of a semaphore.
|
||
|
|
After the value of the semaphore is incremented, it may be decremented
|
||
|
|
immediately by threads that have blocked trying to decrement the semaphore.</p>
|
||
|
|
|
||
|
|
<p>Named and unnamed semaphore waits are visible from the Work with Active Jobs
|
||
|
|
display. A thread waiting on a named or unnamed semaphore will be in a
|
||
|
|
semaphore wait state (SEMW).</p>
|
||
|
|
|
||
|
|
<p>The <strong>sem_getvalue()</strong>function returns the value of the
|
||
|
|
semaphore if the value is greater than or equal to zero. If there are threads
|
||
|
|
waiting on the semaphore, <strong>sem_getvalue()</strong> returns a negative
|
||
|
|
number whose absolute value is the number of threads waiting on the
|
||
|
|
semaphore.</p>
|
||
|
|
|
||
|
|
<p>For details on the semaphore functions, see the following:</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="ipcsemou.htm">QlgSem_open()</A> (Open Named Semaphore (using NLS-enabled path name)) opens a named semaphore and returns a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close().</li>
|
||
|
|
<li><A HREF="ipcsemonu.htm">QlgSem_open_np()</A> (Open Named Semaphore with Maximum Value (using NLS-enabled path name)) opens a named semaphore and returns a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close().</li>
|
||
|
|
<li><A HREF="ipcsemunu.htm">QlgSem_unlink()</A> (Unlink Named Semaphore (using NLS-enabled path name)) unlinks a named semaphore.</li>
|
||
|
|
<li><A HREF="ipcsemcl.htm">sem_close()</A> (Close Named Semaphore) closes a named semaphore that was previously opened by a thread of the current process using sem_open() or sem_open_np().</li>
|
||
|
|
<li><A HREF="ipcsemde.htm">sem_destroy()</A> (Destroy Unnamed Semaphore) destroys an unnamed semaphore that was previously initialized using sem_init() or sem_init_np().</li>
|
||
|
|
<li><A HREF="ipcsemge.htm">sem_getvalue()</A> (Get Semaphore Value) retrieves the value of a named or unnamed semaphore.</li>
|
||
|
|
<li><A HREF="ipcsemi.htm">sem_init()</A> (Initialize Unnamed Semaphore) initializes an unnamed semaphore and sets its initial value.</li>
|
||
|
|
<li><A HREF="ipcsemin.htm">sem_init_np()</A> (Initialize Unnamed Semaphore with Maximum Value) initializes an unnamed semaphore and sets its initial value.</li>
|
||
|
|
<li><A HREF="ipcsemo.htm">sem_open()</A> (Open Named Semaphore) opens a named semaphore, returning a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close().</li>
|
||
|
|
<li><A HREF="ipcsemon.htm">sem_open_np()</A> (Open Named Semaphore with Maximum Value) opens a named semaphore, returning a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close().</li>
|
||
|
|
<li><A HREF="ipcsemp.htm">sem_post()</A> (Post to Semaphore) posts to a semaphore, incrementing its value by one.</li>
|
||
|
|
<li><A HREF="ipcsempn.htm">sem_post_np()</A> (Post Value to Semaphore) posts to a semaphore, incrementing its value by the increment specified in the options parameter.</li>
|
||
|
|
<li><A HREF="ipcsemtr.htm">sem_trywait()</A> (Try to Decrement Semaphore) attempts to decrement the value of the semaphore.</li>
|
||
|
|
<li><A HREF="ipcsemun.htm">sem_unlink()</A> (Unlink Named Semaphore) unlinks a named semaphore.</li>
|
||
|
|
<li><A HREF="ipcsemw.htm">sem_wait()</A> (Wait for Semaphore) decrements by one the value of the semaphore.</li>
|
||
|
|
<li><A HREF="ipcsemwn.htm">sem_wait_np()</A> (Wait for Semaphore with Timeout) attempts to decrement by one the value of the semaphore.</li>
|
||
|
|
</ul>
|
||
|
|
<!--***************API END PASTE***************-->
|
||
|
|
<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>
|
||
|
|
|