intro_prm2(2) intro_prm2(2)
NAME
introprm2, introprm3, introprm3m - introduction to library func-
tions
DESCRIPTION
Notes on conversion to XPG4
The introduction of XPG4 has brought with it changes in some library
functions. This can, in certain circumstances, lead to modified
behavior of existing programs and libraries. To limit the resultant
problems to a minimum, the functions involved run as standard in XPG3
mode, and therefore behave just as before. Please note the following
should you wish to use XPG4 functionality with these functions:
- The c89 compiler [see cc(1)] must be used for generation purposes,
as this activates XPG4 mode automatically.
- The XPGIV environment variable must be exported to the environ-
ment at runtime.
The following functions behave differently in the two compilation
modes. In the mathematical functions input and results are checked
more strictly for the occurrence of NaN and under/overflow in XPG4
mode, and appropriate errno values are set.
acos(), asin(), atan(), atan2(), ceil(), cosh(), erf(), erfc(), exp(),
fabs(), floor(), fprintf(), fscanf(), gamma(), hypot(), j0(), j1(),
jn(), lgamma(), log(), log10(), modf(), nllanginfo(), pow(),
printf(), scanf(), sinh(), sprintf(), sqrt(), sscanf(), strftime(),
sysconf(), system(), y0(), y1(), yn().
The XPG4 functionality of the sigaction routine can only be imple-
mented with the new c89 compiler [see sigaction(2)]
C LIBRARIES AND FUNCTION GROUPS
Each function is assigned to a function group, according to the
library in which it occurs. The function group is indicated by the
number in parentheses after the function name.
The functions identified by (2), (3C) and (3S) form the C standard
library. Those marked with (3E) comprise the ELF library, and those
marked with (3M) the math library. These three libraries are described
in detail below.
Page 1 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
The functions marked with (3G) comprise the "general-purpose" library
libgen. This library is not implemented as a shared library and is not
automatically linked by the C compilation system. Specify -lgen when
calling the compiler in order to link this library.
The functions marked with (3X) occur in various special libraries. The
files in which these libraries can be found are specified in the
appropriate sections.
The function declarations are provided in the #include files specified
in each section.
If you redefine these functions, external variables or macros, the new
definitions (and not those predefined in the system) are used when
they are called. All other names can be redefined without affecting
the behavior of other library functions. Note however that new defini-
tions can cause conflicts with declarations in other header files.
The header files in INCDIR make prototypes (function declarations
including the types of arguments) available for most of the functions
described in this manual. Function prototypes enable the compiler to
check the correct usage of these functions in the user program. You
can also use lint, a program checker, which reports discrepancies even
if the header files involved are not linked. Definitions for the func-
tions marked with (2), (3C) and (3S) are checked automatically. Other
definitions can be included in the lint check by specifying the -l
option; for example, -lm includes definitions for libm. You should
therefore always use the lint program checker to check your programs
for syntax and semantics.
The C standard library
The C standard library which comprises the functions labeled with (2),
(3C) and (3S) is automatically loaded by the C compilation system. It
is implemented as a shared library named libc.so, and is also avail-
able as a static library under the name libc.a. Unless instructions to
the contrary are given in the compiler command line, C programs are
linked with the shared version of the C standard library. To invoke
static linking you should specify the option -dn in the compiler com-
mand line (see description of the cc(1) command).
libelf
Using the functions in the ELF access library, a program can manipu-
late object files, archive files, and archive members which are in the
ELF format (Executable and Linking Format). The header file libelf.h
provides type and function declarations for all library services.
Specify -lelf when calling the compiler in order to link this library.
Page 2 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
Programs communicate with many of the higher-level routines using an
ELF descriptor. That is, when the program starts working with a file,
elfbegin() creates an ELF descriptor through which the program mani-
pulates the structures and information in the file. These ELF descrip-
tors can be used both to read and to write files. After the program
establishes an ELF descriptor for a file, it may then obtain section
descriptors to manipulate the sections of the file [see
elfgetscn(3E)]. Sections hold the bulk of an object file's real
information, such as text, data, the symbol table, and so on. A sec-
tion descriptor "belongs" to a particular ELF descriptor, just as a
section belongs to a file. Finally, data descriptors are available
through section descriptors, allowing the program to manipulate the
information associated with a section. A data descriptor "belongs" to
a section descriptor.
Descriptors provide private handles to a file and its pieces. In other
words, a data descriptor is associated with one section descriptor,
which is associated with one ELF descriptor, which is associated with
one file. Although descriptors are private, they also give access to
shared data. Consider programs that combine input files, using incom-
ing data to create or update another file. Such a program might get
data descriptors for an input and an output section. To update the
output descriptor, the data obtained via the input descriptor could be
reused. That is, the descriptors are distinct, but they could share
the associated data bytes. This sharing avoids the space overhead for
duplicate buffers and the performance overhead for copying data
unnecessarily.
File classes
ELF provides a framework in which to define a family of object files,
supporting multiple processors and architectures. An important dis-
tinction among object files is the class, or capacity, of the file.
The 32-bit class supports architectures in which a 32-bit object can
represent addresses, file sizes, etc., as in the following.
___________________________________________
| Name | Purpose |
|______________|___________________________|
| Elf32Addr | Address (unsigned) |
|______________|___________________________|
| Elf32Half | Medium integer (unsigned)|
|______________|___________________________|
| Elf32Off | File offset (unsigned) |
|______________|___________________________|
| Elf32Sword | Large integer with sign |
|______________|___________________________|
| Elf32Word | Large integer (unsigned) |
|______________|___________________________|
| unsigned char| Small integer (unsigned) |
|______________|___________________________|
Page 3 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
Other classes will be defined as necessary to support larger (or
smaller) machines. Some library services deal only with data objects
for a specific class, while others are class-independent. To make this
distinction clear, library function names reflect their status, as
described below.
Data representations
Conceptually, two parallel sets of objects support cross compilation
environments. One set corresponds to file contents, while the other set
corresponds to the native memory image of the program manipulating the
file. Type definitions supplied by the header files work on the native
machine, which may have different data encodings (size, byte order,
etc.) than the target machine. Although native memory objects should be
at least as big as the file objects (to avoid information loss), they
may be bigger if that is more natural for the host machine.
Translation facilities exist to convert between file and memory repre-
sentations. Some library routines convert data automatically, while
others leave conversion as the program's responsibility. Either way,
programs that create object files must write file-typed objects to
those files; programs that read object files must take a similar view.
See elfxlate(3E) and elffsize(3E) for more information.
Programs may translate data explicitly, taking full control over the
object file layout and semantics. If the program prefers not to have
and exercise complete control, the library provides a higher-level
interface that hides many object file details. elfbegin() and related
functions let a program deal with the native memory types, converting
between memory objects and their file equivalents automatically when
reading or writing an object file.
Elf versions
Object file versions allow ELF to adapt to new requirements. Three
(independent) versions can be important to a program. First, an appli-
cation program knows about a particular version by virtue of being
compiled with certain header files. Second, the access library simi-
larly is compiled with header files that control what versions it
understands. Third, an ELF object file holds a value identifying its
version, determined by the ELF version known by the file's creator.
Ideally, all three versions would be the same, but they may differ.
- If a program's version is newer than the access library, the pro-
gram might use information unknown to the library. Translation rou-
tines might not work properly, leading to undefined behavior. This
condition merits installing a new library.
- The library's version might be newer than the program's and the
file's. The library understands old versions, thus avoiding compa-
tibility problems in this case.
Page 4 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
- Finally, a file's version might be newer than either the program or
the library understands. The program might or might not be able to
process the file properly, depending on whether the file has extra
information and whether that information can be safely ignored.
Again, the safe alternative is to install a new library that under-
stands the file's version.
To accommodate these differences, a program must use elfversion() to
pass its version to the library, thus establishing the working version
for the process. Using this, the library accepts data from and
presents data to the program in the proper representations. When the
library reads object files, it uses each file's version to interpret
the data. When writing files or converting memory types to the file
equivalents, the library uses the program's working version for the
file data.
System services
As mentioned above, elfbegin() and related routines provide a
higher-level interface to ELF files, performing input and output on
behalf of the application program. These routines assume a program can
hold entire files in memory, without explicitly using temporary files.
When reading a file, the library routines bring the data into memory
and perform subsequent operations on the memory copy. Programs that
wish to read or write large object files with this model must execute
on a machine with a large process virtual address space. If the under-
lying operating system limits the number of open files, a program can
use elfcntl() to retrieve all necessary data from the file, allowing
the program to close the file descriptor and reuse it.
Although the elfbegin() interfaces are convenient and efficient for
many programs, they might be inappropriate for some. In those cases,
an application may invoke the elfxlate() data translation routines
directly. These routines perform no input or output, leaving that as
the application's responsibility. By assuming a larger share of the
job, an application controls its input and output model.
Library names
Names associated with the library take several forms:
elfname These class-independent names perform some service,
name, for the program.
elf32name Service names with an embedded class, 32 here, indi-
cate they work only for the designated class of files.
ElfType Data types can be class-independent as well, dis-
tinguished by Type.
Elf32Type Class-dependent data types have an embedded class
name, 32 here.
Page 5 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
ELFCCMD Several functions take commands that control their
actions. These values are members of the ElfCmd
enumeration; they range from zero through ELFCNUM-1.
ELFFFLAG Several functions take flags that control library
status and/or actions. Flags are bits that may be com-
bined.
ELF32FSZTYPE These constants give the file sizes in bytes of the
basic ELF types for the 32-bit class of files. See
elffsize() for more information.
ELFKKIND The function elfkind() identifies the KIND of file
associated with an ELF descriptor. These values are
members of the ElfKind enumeration; they range from
zero through ELFKNUM-1.
ELFTTYPE When a service function, such as elfxlate(), deals
with multiple types, names of this form specify the
desired TYPE. Thus, for example, ELFTEHDR is
directly related to Elf32Ehdr. These values are
members of the ElfType enumeration; they range from
zero through ELFTNUM-1.
Information in the ELF header files is separated into common parts and
processor-specific parts. A program can make a processor's information
available by including the appropriate header file: sys/elfNAME.h
where NAME matches the processor name as used in the ELF file header.
_________________________
| Symbol| Processor |
|_______|________________|
| M32 | AT&T WE 32100 |
|_______|________________|
| SPARC | SPARC |
|_______|________________|
| 386 | Intel 80386 |
|_______|________________|
| 486 | Intel 80486 |
|_______|________________|
| 860 | Intel 80860 |
|_______|________________|
| 68K | Motorola 68000|
|_______|________________|
| 88K | Motorola 88000|
|_______|________________|
Other processors will be added to this table as necessary. For exam-
ple, a program could use the following code to "see" the processor-
specific information for the WE 32100.
include <libelf.h>
#include <sys/elfM32.h>
Page 6 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
Without the sys/elfM32.h definition, only the common ELF information
would be visible.
The math library libm
Declarations for the mathematical functions are obtained by linking
the header file math.h into your source text. Several generally useful
mathematical constants are also defined there.
The math library is not automatically loaded by the C Development Sys-
tem. When calling the compiler, specify option -l in order to use the
above library (-lm).
libm contains the full set of double-precision routines and some
single-precision routines (designated by the suffix f) that give
better performance with less precision. Selected routines are optim-
ized for performance. The optimized routines are sin(), cos(), tan(),
atan(), atan2(), exp(), log(), log10(), pow() and sqrt(), and their
single-precision equivalents.
GLOSSARY OF TERMS
This section defines some of the terms used in the further course of
this manual. The terms are listed alphabetically.
Background process group
Any process group that is not the foreground process group of a ses-
sion that has established a connection with a controlling terminal.
Controlling process
A controlling process is a session leader that established a connec-
tion to a controlling terminal.
Controlling terminal
A terminal that is associated with a session. Each session may have,
at most, one controlling terminal associated with it and a controlling
terminal may be associated with only one session. Certain input
sequences from the controlling terminal cause signals to be sent to
process groups in the session associated with the controlling terminal
[see termio(7)].
Directory
Directories organize files into a hierarchical system where directories
are the nodes in the hierarchy. A directory is a file that catalogs the
list of files, including directories (sub-directories), that are
directly beneath it in the hierarchy. Entries in a directory file are
called links. A link associates a file identifier with a filename. A
directory contains at least two links, "." and "..". The link "." refers
to the directory itself while ".." refers to its parent directory. The
Page 7 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
root directory, which is the top-most node of the hierarchy, has itself
as its parent directory. The pathname of the root directory is / and the
parent directory of the root directory is /.
Driver
In a stream, the driver provides the interface between peripheral
hardware and the stream. A driver can also be a pseudo-driver, such as
a multiplexer or log driver [see log(7)], which is not associated with
a hardware device.
Effective user ID and effective group ID
An active process has an effective user ID and an effective group ID
that are used to determine file access permissions (see below). The
effective user ID and effective group ID are equal to the process'
real user ID and real group ID respectively, unless the process or one
of its ancestors evolved from a file that had the s bit (the set-
user-ID bit or set-group ID bit) set [see also exec(2)].
File access permissions
Permissions to read, write, and execute/search through a file are
granted to a process if one or more of the following are true:
- The effective user ID of the process is superuser.
- The effective user ID of the process matches the user ID of the
owner of the file and the appropriate access bit of the "owner"
portion (0700) of the file mode is set.
- The effective user ID of the process does not match the user ID of
the owner of the file, but the effective group ID of the process
matches the group ID of the file and the appropriate access bit of
the "group" portion (0070) of the file mode is set.
- The effective user ID of the process does not match the user ID of
the owner of the file, the effective group ID of the process does
not match the group ID of the file, but the appropriate access bit
of the "other" portion (0007) of the file mode is set.
File descriptor
A file descriptor is a small integer used to do I/O on a file. The
value of a file descriptor is from 0 to (NOFILES-1). A process may
have no more than NOFILES file descriptors open simultaneously. A file
descriptor is returned by system calls such as open() or pipe(). The
file descriptor is used as an argument by calls such as read(),
write(), ioctl(), and close().
Page 8 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
Filename
Names consisting of 1 to NAMEMAX characters may be used to name an
ordinary file, special file or directory.
These characters may be selected from the set of all character values
excluding \0 (null) and the ASCII code for / (slash).
Note that it is generally unwise to use *, ?, [, or ] as part of
filenames because of the special meaning attached to these characters
by the shell [see sh(1)]. The use of unprintable characters in
filenames should also be avoided.
A filename is sometimes referred to as a pathname component. The
interpretation of a pathname component is dependent on the value of
NAMEMAX associated with the path prefix of that component. If any
pathname component is longer than NAMEMAX, it shall be considered an
error condition in that implementation. Otherwise, the implementation
shall use the first NAMEMAX bytes of the pathname component.
Foreground process group
Each session that has established a connection with a controlling ter-
minal will distinguish one process group of the session as the fore-
ground process group of the controlling terminal. This group has cer-
tain privileges when accessing its controlling terminal that are
denied to background process groups.
Message
In a stream, one or more blocks of data or information, with associ-
ated STREAMS control structures. Messages can be of several defined
types, which identify the message contents. Messages are used to
transfer communication data within a stream.
Message queue
In a stream, a linked list of messages awaiting processing by a module
or driver.
Message queue access permissions
In the msgop and msgctl system call descriptions, the permission
required for an operation is interpreted as follows:
Page 9 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
00400 Read by user
00200 Write by user
00040 Read by group
00020 Write by group
00004 Read by others
00002 Write by others
Read and write permissions on a msqid are granted to a process if one
or more of the following are true:
- The effective user ID of the process is superuser.
- The effective user ID of the process matches msgperm.cuid or
msgperm.uid in the data structure associated with msqid and the
appropriate bit of the "user" portion (0600) of msgperm.mode is
set.
- The effective group ID of the process matches msgperm.cgid or
msgperm.gid and the appropriate bit of the "group" portion (060)
of msgperm.mode is set.
- The appropriate bit of the "other" portion (006) of msgperm.mode
is set.
Otherwise, the corresponding permissions are denied.
Message queue identifier
A message queue identifier (msqid) is a positive integer created by a
msgget() system call. Each msqid has a message queue and a data struc-
ture associated with it. The data structure is referred to as msqidds
and contains the following members:
struct ipcperm msgperm;
struct msg *msgfirst;
struct msg *msglast;
ulong msgcbytes;
ulong msgqnum;
ulong msgqbytes;
pidt msglspid;
pidt msglrpid;
timet msgstime;
long msgpad1; /* reserved */
timet msgrtime;
long msgpad2; /* reserved */
timet msgctime;
long msgpad3; /* reserved */
long msgpad4[4]; /* reserved */
Page 10 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
There follows a description of the fields of the msqidds structure:
msgperm Is an ipcperm structure that specifies the message opera-
tion permissions (see below). This structure includes the
following members:
uidt cuid; /* creator user id */
gidt cgid; /* creator group id */
uidt uid; /* user id */
gidt gid; /* group id */
modet mode; /* r/w permission */
ulong seq; /* slot usage sequence # */
keyt key; /* key */
long pad[4] /* reserved */
*msgfirst Pointer to the first message on the queue.
*msglast Pointer to the last message on the queue.
msgcbytes Current number of bytes on the queue.
msgqnum Number of messages currently on the queue.
msgqbytes Maximum number of bytes allowed on the queue.
msglspid Process ID of the last process that performed a msgsnd
operation.
msglrpid Process ID of the last process that performed a msgrcv
operation.
msgstime Time of the last msgsnd operation.
msgrtime Time of the last msgrcv operation
msgctime Time of the last msgctl operation that changed a member of
the above structure.
Module
A module is an entity containing processing routines for input and
output data. It always exists in the middle of a stream, between the
stream's head and a driver. A module is the STREAMS counterpart to the
commands in a shell pipeline except that a module contains a pair of
functions which allow independent bidirectional (downstream and
upstream) data flow and processing.
Page 11 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
Multiplexer
A multiplexer is a driver that allows streams associated with several
user processes to be connected to a single driver, or several drivers
to be connected to a single user process. STREAMS does not provide a
general multiplexing driver, but does provide the facilities for con-
structing them and for connecting multiplexed configurations of
streams.
Parent process ID
A new process is created by a currently active process [see also
fork(2)]. The parent process ID of a process is the process ID of its
creator.
Pathname
A pathname is a null-terminated character string starting with an
optional slash /, followed by zero or more directory names separated
by slashes, optionally followed by a filename.
If a pathname begins with a slash, the path search begins at the root
directory. Otherwise, the search begins from the current working
directory.
A slash by itself names the root directory.
Process group
Each process in the system is a member of a process group that is
identified by a process group ID. Any process that is not a process
group leader may create a new process group and become its leader. Any
process that is not a process group leader may join an existing pro-
cess group that shares the same session as the process. A newly
created process joins the process group of its parent.
Process group ID
Each active process is a member of a process group and is identified
by a positive integer called the process group ID. This ID is the pro-
cess ID of the group leader. This grouping permits the signaling of
related processes [see kill(2)].
Process group leader
A process group leader is a process whose process ID is the same as
its process group ID.
Page 12 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
Process group lifetime
A process group lifetime begins when the process group is created by
its process group leader, and ends when the lifetime of the last pro-
cess in the group ends or when the last process in the group leaves
the group.
Process ID
Each process in the system is uniquely identified during its lifetime
by a positive integer called a process ID. A process ID may not be
reused by the system until the process lifetime, process group life-
time and session lifetime ends for any process ID, process group ID
and session ID equal to that process ID.
Process lifetime
A process lifetime begins when the process is forked and ends after it
exits, when its termination has been acknowledged by its parent pro-
cess [see wait(2)].
Read queue
In a stream, the message queue in a module or driver containing mes-
sages moving upstream.
Real user ID and real group ID
Each user allowed on the system is identified by a positive integer (0
to MAXUID) called a real user ID.
Each user is also a member of a group. The group is identified by a
positive integer called the real group ID.
An active process has a real user ID and real group ID that are set to
the real user ID and real group ID, respectively, of the user respon-
sible for the creation of the process.
Root directory and current working directory
Each process has associated with it a concept of a root directory and
a current working directory for the purpose of resolving pathname
searches. The root directory of a process need not be the root direc-
tory of the root file system.
Semaphore identifier
A semaphore identifier (semid) is a positive integer created by a
semget() system call. Each semid has a set of semaphores and a data
structure associated with it. The data structure is referred to as
semidds and contains the following members:
Page 13 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
struct ipcperm semperm; /* operation permission struct */
struct sem *sembase; /* ptr to first semaphore in set */
ushort semnsems; /* number of sems in set */
timet semotime; /* last operation time */
long sempad1; /* reserved */
timet semctime; /* last change time */
/* Times measured in secs since */
/* 00:00:00 GMT, Jan. 1, 1970 */
long sempad2; /* reserved */
long sempad3[4]; /* reserved */
semperm Is an ipcperm structure that specifies the semaphore
operation permission (see below). This structure includes
the following members:
uidt uid; /* user id */
gidt gid; /* group id */
uidt cuid; /* creator user id */
gidt cgid; /* creator group id */
modet mode; /* read/amend permission */
ulong seq; /* slot usage sequence number */
keyt key; /* key */
long pad[4]; /* reserved */
semnsems The number of semaphores in the set. Each semaphore in the
set is referenced by a positive integer referred to as a
semnum. semnum values run sequentially from 0 to the
value of semnsems minus 1.
semotime Time of the last semop operation.
semctime Time of the last semctl operation that changed a member of
the above structure.
A semaphore is a data structure called sem that contains the following
members:
ushort semval; /* semaphore value */
pidt sempid; /* pid of last operation */
ushort semncnt; /* # awaiting semval > cval */
ushort semzcnt; /* # awaiting semval = 0 */
semval Non-negative integer that is the actual value of the sema-
phore.
sempid Process ID of the last process that performed a semaphore
operation on this semaphore.
semncnt Count of the number of processes that are currently
suspended awaiting this semaphore's semval to become
greater than its current value.
Page 14 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
semzcnt Count of the number of processes that are currently
suspended awaiting this semaphore's semval to become 0.
Semaphore operation access permissions
In the semop() and semctl() system call descriptions, the permission
required for an operation is interpreted as follows:
00400 Read by user
00200 Alter by user
00040 Read by group
00020 Alter by group
00004 Read by others
00002 Alter by others
Read and alter permissions on a semid are granted to a process if one
or more of the following are true:
- The effective user ID of the process is superuser.
- The effective user ID of the process matches semperm.cuid or
semperm.uid in the data structure associated with semid and the
appropriate bit of the "user" portion (0600) of semperm.mode is
set.
- The effective group ID of the process matches semperm.cgid or
semperm.gid and the appropriate bit of the "group" portion (060)
of semperm.mode is set.
- The appropriate bit of the "other" portion (06) of semperm.mode is
set.
Otherwise, the corresponding permissions are denied.
Session
A session is a group of processes identified by a common ID called a
session ID, capable of establishing a connection with a controlling
terminal. Any process that is not a process group leader may create a
new session and process group, becoming the session leader of the ses-
sion and process group leader of the process group. A newly created
process joins the session of its creator.
Session ID
Each session in the system is identified during its lifetime by a
positive integer called a session ID, the process ID of its session
leader.
Page 15 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
Session leader
A session leader is a process whose session ID is the same as its pro-
cess and process group ID.
Session lifetime
A session lifetime begins when the session is created by a logon pro-
cess, and ends when the lifetime of the last process that is a member
of the session ends, or when the last process that is a member in the
session leaves the session.
Shared memory access permissions
In the shmop() and shmctl() system call descriptions, the permission
required for an operation is interpreted as follows:
00400 Read by user
00200 Write by user
00040 Read by group
00020 Write by group
00004 Read by others
00002 Write by others
Read and write permissions on a shared memory identifier (shmid) are
granted to a process if one or more of the following are true:
- The effective user ID of the process is superuser.
- The effective user ID of the process matches shmperm.cuid or
shmperm.uid in the data structure associated with shmid and the
appropriate bit of the "user" portion (0600) of shmperm.mode is
set.
- The effective group ID of the process matches shmperm.cgid or
shmperm.gid and the appropriate bit of the "group" portion (060)
of shmperm.mode is set.
- The appropriate bit of the "other" portion (06) of shmperm.mode is
set.
- Otherwise, the corresponding permissions are denied.
Shared memory identifier
A shared memory identifier (shmid) is a positive integer created by a
shmget() system call. Each shmid has a segment of memory (referred to
as a shared memory segment) and a data structure associated with it.
Note that these shared memory segments must be explicitly removed by
the user after the last reference to them is removed. The data struc-
ture is referred to as shmidds and contains the following members:
Page 16 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
struct ipcperm shmperm; /* operation permission struct */
int shmsegsz; /* size of segment in bytes */
struct anon-map *shmamp; /* segment anonmap pointer */
ushort shmlkcnt; /* number of times it is being
locked */
pidt shmlpid; /* pid of last shmop */
pidt shmcpid; /* pid of creator */
ulong shmnattch; /* used only for shminfo */
ulong shmcnattch; /* used only for shminfo */
timet shmatime; /* last shmat time */
long shmpad1; /* reserved */
timet shmdtime; /* last shmdt time */
long shmpad2; /* reserved */
timet shmctime; /* last change time */
long shmpad3; /* reserved */
long shmpad4[4]; /* reserved */
There follows a description of the fields of the shmidds structure:
shmperm Is an ipcperm structure that specifies the shared memory
operation permission (see below). This structure includes
the following members:
uidt cuid; /* creator user id */
gidt cgid; /* creator group id */
uidt uid; /* user id */
gidt gid; /* group id */
modet mode; /* r/w permission */
ulong seq; /* slot usage sequence # */
keyt key; /* key */
long pad[4]; /* reserved */
shmsegsz specifies the size of the shared memory segment in bytes.
shmcpid is the process ID of the process that created the shared
memory identifier.
shmlpid the process ID of the last process that performed a
shmop() operation.
shmnattch the number of processes that currently have this segment
attached.
shmatime the time of the last shmat() operation [see shmop(2)].
shmdtime the time of the last shmdt() operation [see shmop(2)].
shmctime the time of the last shmctl() operation that changed one
of the members of the above structure.
Page 17 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
Special processes
The process with ID 0 and the process with ID 1 are special processes
referred to as proc0 and proc1 [see kill(2)]. proc0 is the process
scheduler. proc1 is the initialization process (init); proc1 is the
ancestor of every other process in the system and is used to control
the process structure.
STREAMS
A set of kernel mechanisms that support the development of network
services and data communication drivers. It defines interface stan-
dards for character input/output within the kernel and between the
kernel and user level processes. The STREAMS mechanism is composed of
utility routines, kernel facilities and a set of data structures.
Stream
A stream is a full-duplex data path within the kernel between a user
process and driver routines. The primary components are a stream head,
a driver and zero or more modules between the stream head and driver.
A stream is analogous to a shell pipeline except that data flow and
processing are bidirectional; downstream is the direction from the
stream head to the driver, upstream the direction from the driver to
the stream head.
Stream head
In a stream, the stream head is the end of the stream that provides
the interface between the stream and a user process. The principle
functions of the stream head are processing STREAMS-related system
calls, and passing data and information between a user process and the
stream.
Superuser
A process is recognized as a superuser process and is granted special
privileges, such as immunity from file permissions, if its effective
user ID is 0.
Write queue
In a stream, the message queue in a module or driver containing mes-
sages moving downstream.
Page 18 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
ERROR NUMBERS
Most of the functions described below have one or more error status
values.
In most cases an error is indicated by a return value, almost always
-1 or the NULL pointer. Details are provided with each description. In
addition an error number is placed in the external variable errno. If
a call is successful, errno is not reset. In some cases, the value of
errno must be queried to ascertain whether the function has completed
successfully.
Below is a complete list of error numbers and their names, as defined
in errno.h [see errno(5)]. If the meaning of the error number for a
particular function differs from that given here, it will be explained
in the description of the function.
1 EPERM
Not owner. Typically this error indicates an attempt to modify a
file in some way forbidden except to its owner or the superuser.
It is also returned for attempts by ordinary users to do things
allowed only to the superuser.
2 ENOENT
No such file or directory. A filename is specified and the file
should exist but doesn't, or one of the directories in a path
name does not exist.
3 ERCH
No such process. No process can be found corresponding to that
specified by PID in the kill() or ptrace() routine.
4 EINTR
Interrupted system call. An asynchronous signal (such as
interrupt or quit), which should not be ignored, occurred during
a system call. If execution is resumed after processing the sig-
nal, it will appear as if the interrupted system call returned
this error condition.
5 EIO
I/O error. Some physical I/O error has occurred. This error may
in some cases not appear until the next system call [e.g. an
error during write() may be reported after close()].
6 ENXIO
No such device or address. An I/O operation refers to a device
which cannot be accessed.
7 E2BIG
Arg list too long. An argument list longer than ARGMAX bytes is
presented to a member of the exec family of routines. The argu-
ment list limit is the sum of the size of the argument list plus
the size of the environment's exported shell variables.
Page 19 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
8 ENOEXEC
Exec format error. A request is made to execute a file which,
although it has the appropriate permissions, does not start with
a valid format [see a.out(4)].
9 EBADF
Bad file number. A file descriptor refers to no open file.
10 ECHILD
No child processes. A wait() routine was executed by a process
which had no existing or unwaited for child processes.
11 EAGAIN
Out of system resources. The fork() call failed because the
system's process table is full or the user is not allowed to
start any more processes. It is also possible that a system call
failed because of insufficient memory or swap space.
12 ENOMEM
Not enough space. During execution of an exec(), brk(), or sbrk()
routine, a program asks for more space than the system is able to
supply. The maximum usable size is defined by a system parameter.
The error may also occur if the arrangement of text, data, and
stack segments requires too many segmentation registers, or if
there is not enough swap space during the fork() routine.
13 EACCES
Permission denied. A file has been accessed in a way forbidden by
the file access permissions.
14 EFAULT
Bad address. The system encountered a hardware fault in attempt-
ing to use an argument of a routine. For example, errno poten-
tially may be set to EFAULT any time a routine that takes a
pointer argument is passed an invalid address, if the system can
detect the condition. Because systems will differ in their abil-
ity to reliably detect a bad address, on some implementations
passing a bad address to a routine will result in undefined
behavior.
15 ENOTBLK
Block device required. A non-block file was mentioned where a
block device was required (e.g. in a call to the mount() rou-
tine).
Page 20 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
16 EBUSY
Resource not available. An attempt was made to mount a device
that was already mounted or an attempt was made to unmount a
device on which there is an active file (open file, current
directory, mounted-on file, active text segment). It will also
occur if an attempt is made to enable accounting when it is
already enabled.
17 EEXIST
File exists. An existing file was mentioned in an inappropriate
context (e.g., call to the link() routine).
18 EXDEV
Cross-device link. A link to a file on another device was
attempted.
19 ENODEV
No such device. An attempt was made to apply an inappropriate
operation to a device (e.g. read a write-only device).
20 ENOTDIR
Not a directory. A non-directory was specified where a directory
is required (e.g., in a path prefix or as an argument to the
chdir(2) routine).
21 EISDIR.
Is a directory. An attempt was made to write on a directory.
22 EINVAL
Invalid argument. An invalid argument was specified; an undefined
signal was used in a call to the signal(2) or kill(2) routine.
23 ENFILE
File table overflow. The system file table is full, i.e. SYSOPEN
files are open, and temporarily no more files can be opened.
24 EMFILE
Too many open files. No process may have more than OPENMAX file
descriptors open at a time.
25 ENOTTY
Not a typewriter. A call was made to the ioctl() routine specify-
ing a file that is not a character special file.
26 ETXTBSY
Text file busy. An attempt was made to execute a pure-procedure
program that is currently open for writing. Also an attempt to
open for writing or to remove a pure-procedure program that is
being executed.
Page 21 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
27 EFBIG
File too large. The size of a file exceeded the maximum file
size, FCHRMAX [see getrlimit(2)].
28 ENOSPC
No space left on device. While writing a file, there is no free
space left on the data medium. In the fcntl() routine, the set-
ting or removing of record locks on a file cannot be accomplished
because there are no more record entries left on the system.
29 ESPIPE
Illegal seek. A call to the lseek() routine was issued to a pipe.
30 EROFS
Read-only file system. An attempt to modify a file or directory
in a read-only file system.
31 EMLINK
Too many links. An attempt to make more than the maximum number
of links (LINKMAX) to a file.
32 EPIPE
Broken pipe. A write on a pipe for which there is no process to
read the data. This condition normally generates a signal; the
error is returned if the signal is ignored.
33 EDOM
Math argument out of domain of function. The argument of a
mathematical function (3M) is out of the domain of the function.
34 ERANGE
Math result not representable. The value of a mathematical func-
tion (3M) is not representable within machine precision.
35 ENOMSG
No message of desired type. An attempt was made to receive a mes-
sage of a type that does not exist on the specified message queue
[see msgop(2)].
36 EIDRM
Identifier removed. This error is returned to processes that
resume execution due to the removal of an identifier from the
interprocess communication system [see msgctl(2), semctl(2), and
shmctl(2)].
Page 22 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
37 ECHRNG
Channel number out of range.
38 EL2NSYNC
Level 2 not synchronized.
39 EL3HLT
Level 3 halted.
40 EL3RST
Level 3 reset.
41 ELNRNG
Link number out of range.
42 EUNATCH
Protocol driver not attached.
43 ENOCSI
No CSI structure available.
44 EL2HLT
Level 2 halted.
45 EDEADLK
Risk of a deadlock. A deadlock situation was detected and
avoided. This error pertains to file and record locking.
46 ENOLCK
No record locks available. There are no more locks available. The
system lock table is full [see fcntl(2)].
47-49
Reserved numbers.
50 EBADE
Bad exchange descriptor.
51 EBADR
Bad request descriptor.
52 EXFULL
Message tables full.
53 ENOANO
Anode table overflow.
54 EBADRQC
Bad request code.
55 EBADSLT
Invalid slot.
Page 23 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
56 EDEADLOCK
File locking deadlock.
57 EBFONT
Bad font file format.
58-59
Reserved numbers.
60 ENOSTR
Device not a stream. A putmsg() or getmsg() system call was
attempted on a file that is not a STREAMS device.
61 ENODATA
No data available.
62 ETIME
Timer expired. The timer set for a STREAMS ioctl() call has
expired. The cause of this error is device-specific and could
indicate either a hardware or software failure, or perhaps a
timeout value that is too short for the specific operation. The
status of the ioctl() operation is indeterminate.
63 ENOSR
Out of stream resources. During a STREAMS open(), either no
STREAMS queues or no STREAMS head data structures were available.
This is a temporary condition; one may recover from it if other
processes release resources.
64 ENONET
Machine is not on the network.
65 ENOPKG
Package not installed. This error occurs when users attempt to
use a system call from a package which has not been installed.
66 EREMOTE
Object is remote.
67 ENOLINK
Link has been severed.
68 EADV
Advertise error.
69 ESRMNT
Srmount error.
70 ECOMM
Communication error when sending.
Page 24 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
71 EPROTO
Protocol error. This error is device-specific, but is generally
not related to a hardware failure.
72-73
Reserved numbers.
74 EMULTIHOP
Multihop attempted.
75-76
Reserved numbers.
77 EBADMSG
Not a data message. During a read(), getmsg(), or ioctl() system
call to a STREAMS device, something has come to the head of the
queue that can't be processed. That something depends on the sys-
tem call:
read() control information or a passed file descriptor.
getmsg() passed file descriptor.
ioctl() control or data information.
78 ENAMETOOLONG
Filename too long. The length of the pathname argument exceeds
PATHMAX or its length exceeds NAMEMAX [see limits(4)].
79 EOVERFLOW
Value too large for defined data type.
80 ENOTUNIQ
Name not unique on network.
81 EBADFD
File descriptor in bad state. Either a file descriptor refers to
no open file or a read request was made to a file that is open
only for writing.
82 EREMCHG
Remote address changed.
83 ELIBACC
Cannot access a needed shared library. Trying to use exec() to
start an a.out that requires a static shared library and the
static shared library doesn't exist or the user doesn't have per-
mission to use it.
84 ELIBBAD
Accessing a corrupted shared library. Trying to use exec() to
start an a.out that requires a static shared library (to be
linked in) and exec() could not load the static shared library.
The static shared library is probably corrupted.
Page 25 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
85 ELIBSCN
.lib section in a.out corrupted. Trying to exec() an a.out that
requires a static shared library (to be linked in) and there was
erroneous data in the .lib section of the a.out. The .lib section
tells exec what static shared libraries are needed.
86 ELIBMAX
Attempting to link in more shared libraries than system limit.
Trying to exec() an a.out that requires more static shared
libraries than is allowed on the current configuration of the
system.
87 ELIBEXEC
Cannot exec() a shared library directly. Attempting to exec() a
shared library directly.
88 EILSEQ
Illegal byte sequence. Handle multiple characters as a single
character.
89 ENOSYS
Operation not applicable.
90 ELOOP
Number of symbolic links encountered during path name traversal
exceeds MAXSYMLINKS.
91 ERESTART
Interrupted system call should be restarted.
92 ESTRPIPE
If pipe/FIFO, don't sleep in stream head.
93 ENOTEMPTY
Directory not empty.
94 EUSERS
Too many users (for UFS).
95 ENOTSOCK
Socket operation on non-socket.
96 EDESTADDRREQ
Destination address required. A required address was omitted from
an operation on a transport endpoint.
97 EMSGSIZE
Message too long. A message sent on a transport provider was
larger than the internal message buffer or some other network
limit.
Page 26 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
98 EPROTOTYPE
Protocol wrong type for socket. A protocol was specified that
does not support the semantics of the socket type requested.
99 ENOPROTOOPT
Protocol not available. A bad option or level was specified when
getting or setting options for a protocol.
100-109
Reserved numbers.
110 ENOLIMFILE
Lnode database not open. If ShareII is active all the processes
are attached to the root lnode. Refer to the manual page for the
ShareII charge command which is used to open and close the data-
base. ShareII closes the database automatically if the current
license expires.
111 EPROCLIM
Process limit reached. A fork() can fail if the ShareII process
limit is reached for the lnode to which the forking process is
attached. Note that process limits are applied up the lnode
hierarchy.
112 EDISJOINT
Lnode hierarchy is disjointed. Either by data corruption or
forced removal of an lnode with children, the ShareII lnode data-
base contains an orphan lnode. Processes cannot attach to an
orphan lnode.
113 ENOLOGIN
No logins allowed for user. The user has a ShareII flag.nologin
flag which evaluates as set.
114 ELOGINLIM
Login limit reached. The user has a ShareII flag.onelogin flag
which evaluates as set and the ShareII logins count attribute for
this user is already one.
115 EGROUPLOOP
Loop in lnode hierarchy. When activating an lnode, the depth of
the lnode tree was found to be deeper than the configured max-
imum. When changing the parent of an lnode, the depth of the
relocated lnode would have exceeded the configured maximum.
116 ENOATTACH
Attach to lnode not allowed. The lnode has a ShareII
flag.noattach flag which evaluates as set.
117-119
Reserved numbers.
Page 27 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
120 EPROTONOSUPPORT
Protocol not supported. The protocol has not been configured into
the system or no implementation for it exists.
121 ESOCKTNOSUPPORT
Socket type not supported. The support for the socket type has
not been configured into the system or no implementation for it
exists.
122 EOPNOTSUPP
Operation not supported on transport endpoint. For example, try-
ing to accept a connection on a datagram transport endpoint.
123 EPFNOSUPPORT
Protocol family not supported. The protocol family has not been
configured into the system or no implementation for it exists.
This error arises with Internet protocols.
124 EAFNOSUPPORT
Address family not supported by protocol family. An address
incompatible with the requested protocol was used.
125 EADDRINUSE
Address already in use. User attempted to use an address already
in use, and the protocol does not allow this.
126 EADDRNOTAVAIL
Cannot assign requested address. Results from an attempt to
create a transport endpoint with an address not on the current
machine.
127 ENETDOWN
Network is down. Operation encountered a dead network.
128 ENETUNREACH
Network is unreachable. Operation was attempted to an unreachable
network.
129 ENETRESET
Network dropped connection because of reset. The host you were
connected to crashed and rebooted.
130 ECONNABORTED
Software caused connection abort. A connection abort was caused
internally within your host machine.
131 ECONNRESET
Connection reset by connected party. The connection was closed by
the connected party. This normally results from a timeout or a
reboot of the machine.
Page 28 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
132 ENOBUFS
No buffer space available. An operation on a transport endpoint
or pipe was not performed because the system lacked sufficient
buffer space or because a queue was full.
133 EISCONN
Transport endpoint is already connected. A connect request has
been made, or a sendto or sendmsg specified a destination
address, even though the endpoint was already connected.
134 ENOTCONN
Transport endpoint is not connected. A request to send or receive
data was disallowed because the transport endpoint is not con-
nected and (when sending a datagram) no address was supplied.
135 EUCLEAN
Structure needs cleaning.
136 Reserved number.
137 ENOTNAM
Not a name file.
138 ENAVAIL
Not available.
139 EISNAM
Is a name file.
140 EREMOTEIO
Remote I/O error.
141 EINIT
Reserved number.
142 EREMDEV
Reserved number.
143 ESHUTDOWN
Cannot send after transport endpoint shutdown. A request to send
data was disallowed because the transport endpoint has already
been shut down.
144 ETOOMANYREFS
Too many references: cannot splice.
145 ETIMEDOUT
Connection timed out. A connect or send request failed because
the connected party did not properly respond after a period of
time. The timeout period is dependent on the communication proto-
col.
Page 29 Reliant UNIX 5.44 Printed 11/98
intro_prm2(2) intro_prm2(2)
146 ECONNREFUSED
Connection refused. No connection could be made because the tar-
get machine refused it. This usually results from trying to con-
nect to a service that is inactive on the remote host computer.
147 EHOSDOWN
Host is down. A transport provider operation failed because the
destination host was down.
148 EHOSTUNREACH
No route to host. A transport provider operation was attempted to
an unreachable host.
149 EALREADY
Operation already in progress. An operation was attempted on a
non-blocking object that already had an operation in progress.
150 EINPROGRESS
Operation now in progress. An operation that takes a long time to
complete (such as a connect) was attempted on a non-blocking
object.
151 ESTALE
Ineffective NFS file identifier.
152-157
Reserved numbers.
158 ECANCELED
Operation canceled.
159 EHANDLER
Signal handler exists.
160-199
Reserved numbers.
500 EIORESID
Block not fully transferred.
DIRECTORIES
INCDIR Standard directory for #include files (usually /usr/include
or /usr/include/sys)
SEE ALSO
introprm1(1), introprm5(5).
Chapter on "Object files" in the "Guide to Tools for Programming in
C".
Page 30 Reliant UNIX 5.44 Printed 11/98