753 lines
38 KiB
HTML
753 lines
38 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>General Concepts</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
|
|
<basefont size="3"> <!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h2><a name="tag_04"></a>General Concepts</h2>
|
|
|
|
<p>For the purposes of IEEE Std 1003.1-2001, the general concepts given in <a href="#tag_04">General Concepts</a> apply.
|
|
<basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>No shading to denote extensions or options occurs in this chapter. Where the terms and definitions given in this chapter are
|
|
used elsewhere in text related to extensions and options, they are shaded as appropriate.</dd>
|
|
</dl>
|
|
|
|
<basefont size="3">
|
|
|
|
<h3><a name="tag_04_01"></a>Concurrent Execution</h3>
|
|
|
|
<p>Functions that suspend the execution of the calling thread shall not cause the execution of other threads to be indefinitely
|
|
suspended.</p>
|
|
|
|
<h3><a name="tag_04_02"></a>Directory Protection</h3>
|
|
|
|
<p>If a directory is writable and the mode bit S_ISVTX is set on the directory, a process may remove or rename files within that
|
|
directory only if one or more of the following is true:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The effective user ID of the process is the same as that of the owner ID of the file.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The effective user ID of the process is the same as that of the owner ID of the directory.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The process has appropriate privileges.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>If the S_ISVTX bit is set on a non-directory file, the behavior is unspecified.</p>
|
|
|
|
<h3><a name="tag_04_03"></a>Extended Security Controls</h3>
|
|
|
|
<p>An implementation may provide implementation-defined extended security controls (see <a href=
|
|
"xbd_chap03.html#tag_03_159"><i>Extended Security Controls</i></a> ). These permit an implementation to provide security mechanisms
|
|
to implement different security policies than those described in IEEE Std 1003.1-2001. These mechanisms shall not alter
|
|
or override the defined semantics of any of the interfaces in IEEE Std 1003.1-2001.</p>
|
|
|
|
<h3><a name="tag_04_04"></a>File Access Permissions</h3>
|
|
|
|
<p>The standard file access control mechanism uses the file permission bits, as described below.</p>
|
|
|
|
<p>Implementations may provide <i>additional</i> or <i>alternate</i> file access control mechanisms, or both. An additional access
|
|
control mechanism shall only further restrict the access permissions defined by the file permission bits. An alternate file access
|
|
control mechanism shall:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Specify file permission bits for the file owner class, file group class, and file other class of that file, corresponding to the
|
|
access permissions.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Be enabled only by explicit user action, on a per-file basis by the file owner or a user with the appropriate privilege.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Be disabled for a file after the file permission bits are changed for that file with <a href=
|
|
"../functions/chmod.html"><i>chmod</i>()</a>. The disabling of the alternate mechanism need not disable any additional mechanisms
|
|
supported by an implementation.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Whenever a process requests file access permission for read, write, or execute/search, if no additional mechanism denies access,
|
|
access shall be determined as follows:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If a process has the appropriate privilege:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>If read, write, or directory search permission is requested, access shall be granted.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If execute permission is requested, access shall be granted if execute permission is granted to at least one user by the file
|
|
permission bits or by an alternate access control mechanism; otherwise, access shall be denied.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Otherwise:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The file permission bits of a file contain read, write, and execute/search permissions for the file owner class, file group
|
|
class, and file other class.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Access shall be granted if an alternate access control mechanism is not enabled and the requested access permission bit is set
|
|
for the class (file owner class, file group class, or file other class) to which the process belongs, or if an alternate access
|
|
control mechanism is enabled and it allows the requested access; otherwise, access shall be denied.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3><a name="tag_04_05"></a>File Hierarchy</h3>
|
|
|
|
<p>Files in the system are organized in a hierarchical structure in which all of the non-terminal nodes are directories and all of
|
|
the terminal nodes are any other type of file. Since multiple directory entries may refer to the same file, the hierarchy is
|
|
properly described as a "directed graph".</p>
|
|
|
|
<h3><a name="tag_04_06"></a>Filenames</h3>
|
|
|
|
<p>For a filename to be portable across implementations conforming to IEEE Std 1003.1-2001, it shall consist only of the
|
|
portable filename character set as defined in <a href="xbd_chap03.html#tag_03_276"><i>Portable Filename Character Set</i></a> .</p>
|
|
|
|
<p>The hyphen character shall not be used as the first character of a portable filename. Uppercase and lowercase letters shall
|
|
retain their unique identities between conforming implementations. In the case of a portable pathname, the slash character may also
|
|
be used.</p>
|
|
|
|
<h3><a name="tag_04_07"></a>File Times Update</h3>
|
|
|
|
<p>Each file has three distinct associated time values: <i>st_atime</i>, <i>st_mtime</i>, and <i>st_ctime</i>. The <i>st_atime</i>
|
|
field is associated with the times that the file data is accessed; <i>st_mtime</i> is associated with the times that the file data
|
|
is modified; and <i>st_ctime</i> is associated with the times that the file status is changed. These values are returned in the
|
|
file characteristics structure, as described in <a href="sys/stat.h.html"><i><sys/stat.h></i></a> .</p>
|
|
|
|
<p>Each function or utility in IEEE Std 1003.1-2001 that reads or writes data or changes file status indicates which of
|
|
the appropriate time-related fields shall be "marked for update". If an implementation of such a function or utility marks for
|
|
update a time-related field not specified by IEEE Std 1003.1-2001, this shall be documented, except that any changes
|
|
caused by pathname resolution need not be documented. For the other functions or utilities in IEEE Std 1003.1-2001 (those
|
|
that are not explicitly required to read or write file data or change file status, but that in some implementations happen to do
|
|
so), the effect is unspecified.</p>
|
|
|
|
<p>An implementation may update fields that are marked for update immediately, or it may update such fields periodically. At an
|
|
update point in time, any marked fields shall be set to the current time and the update marks shall be cleared. All fields that are
|
|
marked for update shall be updated when the file ceases to be open by any process, or when a <a href=
|
|
"../functions/stat.html"><i>stat</i>()</a>, <a href="../functions/fstat.html"><i>fstat</i>()</a>, or <a href=
|
|
"../functions/lstat.html"><i>lstat</i>()</a> is performed on the file. Other times at which updates are done are unspecified. Marks
|
|
for update, and updates themselves, are not done for files on read-only file systems; see <a href=
|
|
"xbd_chap03.html#tag_03_304"><i>Read-Only File System</i></a> .</p>
|
|
|
|
<h3><a name="tag_04_08"></a>Host and Network Byte Orders</h3>
|
|
|
|
<p>When data is transmitted over the network, it is sent as a sequence of octets (8-bit unsigned values). If an entity (such as an
|
|
address or a port number) can be larger than 8 bits, it needs to be stored in several octets. The convention is that all such
|
|
values are stored with 8 bits in each octet, and with the first (lowest-addressed) octet holding the most-significant bits. This is
|
|
called "network byte order".</p>
|
|
|
|
<p>Network byte order may not be convenient for processing actual values. For this, it is more sensible for values to be stored as
|
|
ordinary integers. This is known as "host byte order". In host byte order:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The most significant bit might not be stored in the first byte in address order.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Bits might not be allocated to bytes in any obvious order at all.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>8-bit values stored in <b>uint8_t</b> objects do not require conversion to or from host byte order, as they have the same
|
|
representation. 16 and 32-bit values can be converted using the <a href="../functions/htonl.html"><i>htonl</i>()</a>, <a href=
|
|
"../functions/htons.html"><i>htons</i>()</a>, <a href="../functions/ntohl.html"><i>ntohl</i>()</a>, and <a href=
|
|
"../functions/ntohs.html"><i>ntohs</i>()</a> functions. When reading data that is to be converted to host byte order, it should
|
|
either be received directly into a <b>uint16_t</b> or <b>uint32_t</b> object or should be copied from an array of bytes using <a
|
|
href="../functions/memcpy.html"><i>memcpy</i>()</a> or similar. Passing the data through other types could cause the byte order to
|
|
be changed. Similar considerations apply when sending data.</p>
|
|
|
|
<h3><a name="tag_04_09"></a>Measurement of Execution Time</h3>
|
|
|
|
<p>The mechanism used to measure execution time shall be implementation-defined. The implementation shall also define to whom the
|
|
CPU time that is consumed by interrupt handlers and system services on behalf of the operating system will be charged. See <a href=
|
|
"xbd_chap03.html#tag_03_117"><i>CPU Time (Execution Time)</i></a> .</p>
|
|
|
|
<h3><a name="tag_04_10"></a>Memory Synchronization</h3>
|
|
|
|
<p>Applications shall ensure that access to any memory location by more than one thread of control (threads or processes) is
|
|
restricted such that no thread of control can read or modify a memory location while another thread of control may be modifying it.
|
|
Such access is restricted using functions that synchronize thread execution and also synchronize memory with respect to other
|
|
threads. The following functions synchronize memory with respect to other threads:</p>
|
|
|
|
<table cellpadding="3">
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"><br>
|
|
<a href="../functions/fork.html"><i>fork</i>()</a><br>
|
|
<a href="../functions/pthread_barrier_wait.html"><i>pthread_barrier_wait</i>()</a><br>
|
|
<a href="../functions/pthread_cond_broadcast.html"><i>pthread_cond_broadcast</i>()</a><br>
|
|
<a href="../functions/pthread_cond_signal.html"><i>pthread_cond_signal</i>()</a><br>
|
|
<a href="../functions/pthread_cond_timedwait.html"><i>pthread_cond_timedwait</i>()</a><br>
|
|
<a href="../functions/pthread_cond_wait.html"><i>pthread_cond_wait</i>()</a><br>
|
|
<a href="../functions/pthread_create.html"><i>pthread_create</i>()</a><br>
|
|
<a href="../functions/pthread_join.html"><i>pthread_join</i>()</a><br>
|
|
<a href="../functions/pthread_mutex_lock.html"><i>pthread_mutex_lock</i>()</a><br>
|
|
</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><br>
|
|
<a href="../functions/pthread_mutex_timedlock.html"><i>pthread_mutex_timedlock</i>()</a><br>
|
|
<a href="../functions/pthread_mutex_trylock.html"><i>pthread_mutex_trylock</i>()</a><br>
|
|
<a href="../functions/pthread_mutex_unlock.html"><i>pthread_mutex_unlock</i>()</a><br>
|
|
<a href="../functions/pthread_spin_lock.html"><i>pthread_spin_lock</i>()</a><br>
|
|
<a href="../functions/pthread_spin_trylock.html"><i>pthread_spin_trylock</i>()</a><br>
|
|
<a href="../functions/pthread_spin_unlock.html"><i>pthread_spin_unlock</i>()</a><br>
|
|
<a href="../functions/pthread_rwlock_rdlock.html"><i>pthread_rwlock_rdlock</i>()</a><br>
|
|
<a href="../functions/pthread_rwlock_timedrdlock.html"><i>pthread_rwlock_timedrdlock</i>()</a><br>
|
|
<a href="../functions/pthread_rwlock_timedwrlock.html"><i>pthread_rwlock_timedwrlock</i>()</a><br>
|
|
</p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><br>
|
|
<a href="../functions/pthread_rwlock_tryrdlock.html"><i>pthread_rwlock_tryrdlock</i>()</a><br>
|
|
<a href="../functions/pthread_rwlock_trywrlock.html"><i>pthread_rwlock_trywrlock</i>()</a><br>
|
|
<a href="../functions/pthread_rwlock_unlock.html"><i>pthread_rwlock_unlock</i>()</a><br>
|
|
<a href="../functions/pthread_rwlock_wrlock.html"><i>pthread_rwlock_wrlock</i>()</a><br>
|
|
<a href="../functions/sem_post.html"><i>sem_post</i>()</a><br>
|
|
<a href="../functions/sem_trywait.html"><i>sem_trywait</i>()</a><br>
|
|
<a href="../functions/sem_wait.html"><i>sem_wait</i>()</a><br>
|
|
<a href="../functions/wait.html"><i>wait</i>()</a><br>
|
|
<a href="../functions/waitpid.html"><i>waitpid</i>()</a><br>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Unless explicitly stated otherwise, if one of the above functions returns an error, it is unspecified whether the invocation
|
|
causes memory to be synchronized.</p>
|
|
|
|
<p>Applications may allow more than one thread of control to read a memory location simultaneously.</p>
|
|
|
|
<h3><a name="tag_04_11"></a>Pathname Resolution</h3>
|
|
|
|
<p>Pathname resolution is performed for a process to resolve a pathname to a particular file in a file hierarchy. There may be
|
|
multiple pathnames that resolve to the same file.</p>
|
|
|
|
<p>Each filename in the pathname is located in the directory specified by its predecessor (for example, in the pathname fragment
|
|
<b>a/b</b>, file <b>b</b> is located in directory <b>a</b>). Pathname resolution shall fail if this cannot be accomplished. If the
|
|
pathname begins with a slash, the predecessor of the first filename in the pathname shall be taken to be the root directory of the
|
|
process (such pathnames are referred to as "absolute pathnames"). If the pathname does not begin with a slash, the predecessor of
|
|
the first filename of the pathname shall be taken to be the current working directory of the process (such pathnames are referred
|
|
to as "relative pathnames").</p>
|
|
|
|
<p>The interpretation of a pathname component is dependent on the value of {NAME_MAX} and _POSIX_NO_TRUNC associated with the path
|
|
prefix of that component. If any pathname component is longer than {NAME_MAX}, the implementation shall consider this an error.</p>
|
|
|
|
<p>A pathname that contains at least one non-slash character and that ends with one or more trailing slashes shall be resolved as
|
|
if a single dot character ( <tt>'.'</tt> ) were appended to the pathname.</p>
|
|
|
|
<p>If a symbolic link is encountered during pathname resolution, the behavior shall depend on whether the pathname component is at
|
|
the end of the pathname and on the function being performed. If all of the following are true, then pathname resolution is
|
|
complete:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>This is the last pathname component of the pathname.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The pathname has no trailing slash.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The function is required to act on the symbolic link itself, or certain arguments direct that the function act on the symbolic
|
|
link itself.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>In all other cases, the system shall prefix the remaining pathname, if any, with the contents of the symbolic link. If the
|
|
combined length exceeds {PATH_MAX}, and the implementation considers this to be an error, <i>errno</i> shall be set to
|
|
[ENAMETOOLONG] and an error indication shall be returned. Otherwise, the resolved pathname shall be the resolution of the pathname
|
|
just created. If the resulting pathname does not begin with a slash, the predecessor of the first filename of the pathname is taken
|
|
to be the directory containing the symbolic link.</p>
|
|
|
|
<p>If the system detects a loop in the pathname resolution process, it shall set <i>errno</i> to [ELOOP] and return an error
|
|
indication. The same may happen if during the resolution process more symbolic links were followed than the implementation allows.
|
|
This implementation-defined limit shall not be smaller than {SYMLOOP_MAX}.</p>
|
|
|
|
<p>The special filename dot shall refer to the directory specified by its predecessor. The special filename dot-dot shall refer to
|
|
the parent directory of its predecessor directory. As a special case, in the root directory, dot-dot may refer to the root
|
|
directory itself.</p>
|
|
|
|
<p>A pathname consisting of a single slash shall resolve to the root directory of the process. A null pathname shall not be
|
|
successfully resolved. A pathname that begins with two successive slashes may be interpreted in an implementation-defined manner,
|
|
although more than two leading slashes shall be treated as a single slash.</p>
|
|
|
|
<h3><a name="tag_04_12"></a>Process ID Reuse</h3>
|
|
|
|
<p>A process group ID shall not be reused by the system until the process group lifetime ends.</p>
|
|
|
|
<p>A process ID shall not be reused by the system until the process lifetime ends. In addition, if there exists a process group
|
|
whose process group ID is equal to that process ID, the process ID shall not be reused by the system until the process group
|
|
lifetime ends. A process that is not a system process shall not have a process ID of 1.</p>
|
|
|
|
<h3><a name="tag_04_13"></a>Scheduling Policy</h3>
|
|
|
|
<p>A scheduling policy affects process or thread ordering:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>When a process or thread is a running thread and it becomes a blocked thread</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>When a process or thread is a running thread and it becomes a preempted thread</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>When a process or thread is a blocked thread and it becomes a runnable thread</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>When a running thread calls a function that can change the priority or scheduling policy of a process or thread</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>In other scheduling policy-defined circumstances</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Conforming implementations shall define the manner in which each of the scheduling policies may modify the priorities or
|
|
otherwise affect the ordering of processes or threads at each of the occurrences listed above. Additionally, conforming
|
|
implementations shall define in what other circumstances and in what manner each scheduling policy may modify the priorities or
|
|
affect the ordering of processes or threads.</p>
|
|
|
|
<h3><a name="tag_04_14"></a>Seconds Since the Epoch</h3>
|
|
|
|
<p>A value that approximates the number of seconds that have elapsed since the Epoch. A Coordinated Universal Time name (specified
|
|
in terms of seconds (<i>tm_sec</i>), minutes (<i>tm_min</i>), hours (<i>tm_hour</i>), days since January 1 of the year
|
|
(<i>tm_yday</i>), and calendar year minus 1900 (<i>tm_year</i>)) is related to a time represented as seconds since the Epoch,
|
|
according to the expression below.</p>
|
|
|
|
<p>If the year is <1970 or the value is negative, the relationship is undefined. If the year is >=1970 and the value is
|
|
non-negative, the value is related to a Coordinated Universal Time name according to the C-language expression, where
|
|
<i>tm_sec</i>, <i>tm_min</i>, <i>tm_hour</i>, <i>tm_yday</i>, and <i>tm_year</i> are all integer types:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<i>tm_sec</i> <tt>+</tt> <i>tm_min</i><tt>*60 +</tt> <i>tm_hour</i><tt>*3600 +</tt> <i>tm_yday</i><tt>*86400 +
|
|
(</tt><i>tm_year</i><tt>-70)*31536000 + ((</tt><i>tm_year</i><tt>-69)/4)*86400 -
|
|
((</tt><i>tm_year</i><tt>-1)/100)*86400 + ((</tt><i>tm_year</i><tt>+299)/400)*86400
|
|
</tt>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>The relationship between the actual time of day and the current value for seconds since the Epoch is unspecified.</p>
|
|
|
|
<p>How any changes to the value of seconds since the Epoch are made to align to a desired relationship with the current actual time
|
|
are made is implementation-defined. As represented in seconds since the Epoch, each and every day shall be accounted for by exactly
|
|
86400 seconds. <basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>The last three terms of the expression add in a day for each year that follows a leap year starting with the first leap year
|
|
since the Epoch. The first term adds a day every 4 years starting in 1973, the second subtracts a day back out every 100 years
|
|
starting in 2001, and the third adds a day back in every 400 years starting in 2001. The divisions in the formula are integer
|
|
divisions; that is, the remainder is discarded leaving only the integer quotient.</dd>
|
|
</dl>
|
|
|
|
<basefont size="3">
|
|
|
|
<h3><a name="tag_04_15"></a>Semaphore</h3>
|
|
|
|
<p>A minimum synchronization primitive to serve as a basis for more complex synchronization mechanisms to be defined by the
|
|
application program.</p>
|
|
|
|
<p>For the semaphores associated with the Semaphores option, a semaphore is represented as a shareable resource that has a
|
|
non-negative integer value. When the value is zero, there is a (possibly empty) set of threads awaiting the availability of the
|
|
semaphore.</p>
|
|
|
|
<p>For the semaphores associated with the X/Open System Interface Extension (XSI), a semaphore is a positive integer (0 through
|
|
32767). The <a href="../functions/semget.html"><i>semget</i>()</a> function can be called to create a set or array of semaphores. A
|
|
semaphore set can contain one or more semaphores up to an implementation-defined value.</p>
|
|
|
|
<h5><a name="tag_04_15_00_01"></a>Semaphore Lock Operation</h5>
|
|
|
|
<p>An operation that is applied to a semaphore. If, prior to the operation, the value of the semaphore is zero, the semaphore lock
|
|
operation shall cause the calling thread to be blocked and added to the set of threads awaiting the semaphore; otherwise, the value
|
|
shall be decremented.</p>
|
|
|
|
<h5><a name="tag_04_15_00_02"></a>Semaphore Unlock Operation</h5>
|
|
|
|
<p>An operation that is applied to a semaphore. If, prior to the operation, there are any threads in the set of threads awaiting
|
|
the semaphore, then some thread from that set shall be removed from the set and becomes unblocked; otherwise, the semaphore value
|
|
shall be incremented.</p>
|
|
|
|
<h3><a name="tag_04_16"></a>Thread-Safety</h3>
|
|
|
|
<p>Refer to the System Interfaces volume of IEEE Std 1003.1-2001, <a href="../functions/xsh_chap02_09.html">Section 2.9,
|
|
Threads</a>.</p>
|
|
|
|
<h3><a name="tag_04_17"></a>Tracing</h3>
|
|
|
|
<p>The trace system allows a traced process to have a selection of events created for it. Traces consist of streams of trace event
|
|
types.</p>
|
|
|
|
<p>A trace event type is identified on the one hand by a trace event type name, also referenced as a trace event name, and on the
|
|
other hand by a trace event type identifier. A trace event name is a human-readable string. A trace event type identifier is an
|
|
opaque identifier used by the trace system. There shall be a one-to-one relationship between trace event type identifiers and trace
|
|
event names for a given trace stream and also for a given traced process. The trace event type identifier shall be generated
|
|
automatically from a trace event name by the trace system either when a trace controller process invokes <a href=
|
|
"../functions/posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a> or when an instrumented application
|
|
process invokes <a href="../functions/posix_trace_eventid_open.html"><i>posix_trace_eventid_open</i>()</a>. Trace event type
|
|
identifiers are used to filter trace event types, to allow interpretation of user data, and to identify the kind of trace point
|
|
that generated a trace event.</p>
|
|
|
|
<p>Each trace event shall be of a particular trace event type, and associated with a trace event type identifier. The execution of
|
|
a trace point shall generate a trace event if a trace stream has been created and started for the process that executed the trace
|
|
point and if the corresponding trace event type identifier is not ignored by filtering.</p>
|
|
|
|
<p>A generated trace event shall be recorded in a trace stream, and optionally also in a trace log if a trace log is associated
|
|
with the trace stream, except that:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>For a trace stream, if no resources are available for the event, the event is lost.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>For a trace log, if no resources are available for the event, or a flush operation does not succeed, the event is lost.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>A trace event recorded in an active trace stream may be retrieved by an application having the appropriate privileges.</p>
|
|
|
|
<p>A trace event recorded in a trace log may be retrieved by an application having the appropriate privileges after opening the
|
|
trace log as a pre-recorded trace stream, with the function <a href=
|
|
"../functions/posix_trace_open.html"><i>posix_trace_open</i>()</a>.</p>
|
|
|
|
<p>When a trace event is reported it is possible to retrieve the following:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>A trace event type identifier</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A timestamp</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The process ID of the traced process, if the trace event is process-dependent</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Any optional trace event data including its length</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the Threads option is supported, the thread ID, if the trace event is process-dependent</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The program address at which the trace point was invoked</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Trace events may be mapped from trace event types to trace event names. One such mapping shall be associated with each trace
|
|
stream. An active trace stream is associated with a traced process, and also with its children if the Trace Inherit option is
|
|
supported and also the inheritance policy is set to _POSIX_TRACE_INHERIT. Therefore each traced process has a mapping of the trace
|
|
event names to trace event type identifiers that have been defined for that process.</p>
|
|
|
|
<p>Traces can be recorded into either trace streams or trace logs.</p>
|
|
|
|
<p>The implementation and format of a trace stream are unspecified. A trace stream need not be and generally is not persistent. A
|
|
trace stream may be either active or pre-recorded:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>An active trace stream is a trace stream that has been created and has not yet been shut down. It can be of one of the two
|
|
following classes:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>An active trace stream without a trace log that was created with the <a href=
|
|
"../functions/posix_trace_create.html"><i>posix_trace_create</i>()</a> function</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the Trace Log option is supported, an active trace stream with a trace log that was created with the <a href=
|
|
"../functions/posix_trace_create_withlog.html"><i>posix_trace_create_withlog</i>()</a> function</p>
|
|
</li>
|
|
</ol>
|
|
</li>
|
|
|
|
<li>
|
|
<p>A pre-recorded trace stream is a trace stream that was opened from a trace log object using the <a href=
|
|
"../functions/posix_trace_open.html"><i>posix_trace_open</i>()</a> function.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>An active trace stream can loop. This behavior means that when the resources allocated by the trace system for the trace stream
|
|
are exhausted, the trace system reuses the resources associated with the oldest recorded trace events to record new trace
|
|
events.</p>
|
|
|
|
<p>If the Trace Log option is supported, an active trace stream with a trace log can be flushed. This operation causes the trace
|
|
system to write trace events from the trace stream to the associated trace log, following the defined policies or using an explicit
|
|
function call. After this operation, the trace system may reuse the resources associated with the flushed trace events.</p>
|
|
|
|
<p>An active trace stream with or without a trace log can be cleared. This operation shall cause all the resources associated with
|
|
this trace stream to be reinitialized. The trace stream shall behave as if it was returning from its creation, except that the
|
|
mapping of trace event type identifiers to trace event names shall not be cleared. If a trace log was associated with this trace
|
|
stream, the trace log shall also be reinitialized.</p>
|
|
|
|
<p>A trace log shall be recorded when the <a href="../functions/posix_trace_shutdown.html"><i>posix_trace_shutdown</i>()</a>
|
|
operation is invoked or during tracing, depending on the tracing strategy which is defined by a log policy. After the trace stream
|
|
has been shut down, the trace information can be retrieved from the associated trace log using the same interface used to retrieve
|
|
information from an active trace stream.</p>
|
|
|
|
<p>For a traced process, if the Trace Inherit option is supported and the trace stream's inheritance attribute is
|
|
_POSIX_TRACE_INHERIT, the initial targeted traced process shall be traced together with all of its future children. The
|
|
<i>posix_pid</i> member of each trace event in a trace stream shall be the process ID of the traced process.</p>
|
|
|
|
<p>Each trace point may be an implementation-defined action such as a context switch, or an application-programmed action such as a
|
|
call to a specific operating system service (for example, <a href="../functions/fork.html"><i>fork</i>()</a>) or a call to <a href=
|
|
"../functions/posix_trace_event.html"><i>posix_trace_event</i>()</a>.</p>
|
|
|
|
<p>Trace points may be filtered. The operation of the filter is to filter out (ignore) selected trace events. By default, no trace
|
|
events are filtered.</p>
|
|
|
|
<p>The results of the tracing operations can be analyzed and monitored by a trace controller process or a trace analyzer
|
|
process.</p>
|
|
|
|
<p>Only the trace controller process has control of the trace stream it has created. The control of the operation of a trace stream
|
|
is done using its corresponding trace stream identifier. The trace controller process is able to:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Initialize the attributes of a trace stream</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Create the trace stream</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Start and stop tracing</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Know the mapping of the traced process</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the Trace Event Filter option is supported, filter the type of trace events to be recorded</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Shut the trace stream down</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>A traced process may also be a trace controller process. Only the trace controller process can control its trace stream(s). A
|
|
trace stream created by a trace controller process shall be shut down if its controller process terminates or executes another
|
|
file.</p>
|
|
|
|
<p>A trace controller process may also be a trace analyzer process. Trace analysis can be done concurrently with the traced process
|
|
or can be done off-line, in the same or in a different platform.</p>
|
|
|
|
<h3><a name="tag_04_18"></a>Treatment of Error Conditions for Mathematical Functions</h3>
|
|
|
|
<p>For all the functions in the <a href="../basedefs/math.h.html"><i><math.h></i></a> header, an application wishing to check
|
|
for error situations should set <i>errno</i> to 0 and call <i>feclearexcept</i>(FE_ALL_EXCEPT) before calling the function. On
|
|
return, if <i>errno</i> is non-zero or <i>fetestexcept</i>( FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an
|
|
error has occurred.</p>
|
|
|
|
<p>The following error conditions are defined for all functions in the <a href="../basedefs/math.h.html"><i><math.h></i></a>
|
|
header.</p>
|
|
|
|
<h4><a name="tag_04_18_01"></a>Domain Error</h4>
|
|
|
|
<p>A "domain error" shall occur if an input argument is outside the domain over which the mathematical function is defined. The
|
|
description of each function lists any required domain errors; an implementation may define additional domain errors, provided that
|
|
such errors are consistent with the mathematical definition of the function.</p>
|
|
|
|
<p>On a domain error, the function shall return an implementation-defined value; if the integer expression (math_errhandling &
|
|
MATH_ERRNO) is non-zero, <i>errno</i> shall be set to [EDOM]; if the integer expression (math_errhandling & MATH_ERREXCEPT) is
|
|
non-zero, the "invalid" floating-point exception shall be raised.</p>
|
|
|
|
<h4><a name="tag_04_18_02"></a>Pole Error</h4>
|
|
|
|
<p>A "pole error" occurs if the mathematical result of the function is an exact infinity (for example, log(0.0)).</p>
|
|
|
|
<p>On a pole error, the function shall return the value of the macro HUGE_VAL, HUGE_VALF, or HUGE_VALL according to the return
|
|
type, with the same sign as the correct value of the function; if the integer expression (math_errhandling & MATH_ERRNO) is
|
|
non-zero, <i>errno</i> shall be set to [ERANGE]; if the integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, the
|
|
"divide-by-zero" floating-point exception shall be raised.</p>
|
|
|
|
<h4><a name="tag_04_18_03"></a>Range Error</h4>
|
|
|
|
<p>A "range error" shall occur if the finite mathematical result of the function cannot be represented in an object of the
|
|
specified type, due to extreme magnitude.</p>
|
|
|
|
<h5><a name="tag_04_18_03_01"></a>Result Overflows</h5>
|
|
|
|
<p>A floating result overflows if the magnitude of the mathematical result is finite but so large that the mathematical result
|
|
cannot be represented without extraordinary roundoff error in an object of the specified type. If a floating result overflows and
|
|
default rounding is in effect, then the function shall return the value of the macro HUGE_VAL, HUGE_VALF, or HUGE_VALL according to
|
|
the return type, with the same sign as the correct value of the function; if the integer expression (math_errhandling &
|
|
MATH_ERRNO) is non-zero, <i>errno</i> shall be set to [ERANGE]; if the integer expression (math_errhandling & MATH_ERREXCEPT)
|
|
is non-zero, the "overflow" floating-point exception shall be raised.</p>
|
|
|
|
<h5><a name="tag_04_18_03_02"></a>Result Underflows</h5>
|
|
|
|
<p>The result underflows if the magnitude of the mathematical result is so small that the mathematical result cannot be
|
|
represented, without extraordinary roundoff error, in an object of the specified type. If the result underflows, the function shall
|
|
return an implementation-defined value whose magnitude is no greater than the smallest normalized positive number in the specified
|
|
type; if the integer expression (math_errhandling & MATH_ERRNO) is non-zero, whether <i>errno</i> is set to [ERANGE] is
|
|
implementation-defined; if the integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero, whether the "underflow''
|
|
floating-point exception is raised is implementation-defined.</p>
|
|
|
|
<h3><a name="tag_04_19"></a>Treatment of NaN Arguments for the Mathematical Functions</h3>
|
|
|
|
<p>For functions called with a NaN argument, no errors shall occur and a NaN shall be returned, except where stated otherwise.</p>
|
|
|
|
<p>If a function with one or more NaN arguments returns a NaN result, the result should be the same as one of the NaN arguments
|
|
(after possible type conversion), except perhaps for the sign.</p>
|
|
|
|
<p>On implementations that support the IEC 60559:1989 standard floating point, functions with signaling NaN argument(s) shall
|
|
be treated as if the function were called with an argument that is a required domain error and shall return a quiet NaN result,
|
|
except where stated otherwise. <basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>The function might never see the signaling NaN, since it might trigger when the arguments are evaluated during the function
|
|
call.</dd>
|
|
</dl>
|
|
|
|
<basefont size="3">
|
|
|
|
<p>On implementations that support the IEC 60559:1989 standard floating point, for those functions that do not have a
|
|
documented domain error, the following shall apply:</p>
|
|
|
|
<blockquote>These functions shall fail if:
|
|
|
|
<dl compact>
|
|
<dt>Domain Error</dt>
|
|
|
|
<dd>Any argument is a signaling NaN.</dd>
|
|
</dl>
|
|
|
|
<p>Either, the integer expression (math_errhandling & MATH_ERRNO) is non-zero and <i>errno</i> shall be set to [EDOM], or the
|
|
integer expression (math_errhandling & MATH_ERREXCEPT) is non-zero and the invalid floating-point exception shall be
|
|
raised.</p>
|
|
</blockquote>
|
|
|
|
<h3><a name="tag_04_20"></a>Utility</h3>
|
|
|
|
<p>A utility program shall be either an executable file, such as might be produced by a compiler or linker system from computer
|
|
source code, or a file of shell source code, directly interpreted by the shell. The program may have been produced by the user,
|
|
provided by the system implementor, or acquired from an independent distributor.</p>
|
|
|
|
<p>The system may implement certain utilities as shell functions (see the Shell and Utilities volume of
|
|
IEEE Std 1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_09_05">Section 2.9.5, Function Definition Command</a>)
|
|
or built-in utilities, but only an application that is aware of the command search order described in the Shell and Utilities
|
|
volume of IEEE Std 1003.1-2001, <a href="../utilities/xcu_chap02.html#tag_02_09_01_01">Section 2.9.1.1, Command Search
|
|
and Execution</a> or of performance characteristics can discern differences between the behavior of such a function or built-in
|
|
utility and that of an executable file.</p>
|
|
|
|
<h3><a name="tag_04_21"></a>Variable Assignment</h3>
|
|
|
|
<p>In the shell command language, a word consisting of the following parts:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<i>varname</i><tt>=</tt><i>value</i>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>When used in a context where assignment is defined to occur and at no other time, the <i>value</i> (representing a word or
|
|
field) shall be assigned as the value of the variable denoted by <i>varname</i>. <basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>For further information, see the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href=
|
|
"../utilities/xcu_chap02.html#tag_02_09_01">Section 2.9.1, Simple Commands</a>.</dd>
|
|
</dl>
|
|
|
|
<basefont size="3">
|
|
|
|
<p>The <i>varname</i> and <i>value</i> parts shall meet the requirements for a name and a word, respectively, except that they are
|
|
delimited by the embedded unquoted equals-sign, in addition to other delimiters. <basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>Additional delimiters are described in the Shell and Utilities volume of IEEE Std 1003.1-2001, <a href=
|
|
"../utilities/xcu_chap02.html#tag_02_03">Section 2.3, Token Recognition</a>.</dd>
|
|
</dl>
|
|
|
|
<basefont size="3">
|
|
|
|
<p>When a variable assignment is done, the variable shall be created if it did not already exist. If <i>value</i> is not specified,
|
|
the variable shall be given a null value. <basefont size="2"></p>
|
|
|
|
<dl>
|
|
<dt><b>Note:</b></dt>
|
|
|
|
<dd>An alternative form of variable assignment:
|
|
|
|
<blockquote>
|
|
<pre>
|
|
<i>symbol</i><tt>=</tt><i>value</i>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>(where <i>symbol</i> is a valid word delimited by an equals-sign, but not a valid name) produces unspecified results. The form
|
|
<i>symbol</i>= <i>value</i> is used by the KornShell <i>name</i>[ <i>expression</i>]= <i>value</i> syntax.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<basefont size="3">
|
|
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|