GETSPATH(2,L) AIX Technical Reference GETSPATH(2,L)
-------------------------------------------------------------------------------
getspath, setspath
PURPOSE
Manages the site path list.
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <sys/types.h>
getspath(site_path, length)
sitepath_t *site_path;
int length;
setspath(site_path, length)
sitepath_t *site_path;
int length;
DESCRIPTION
The site path is used when resolving file names which refer to hidden
directories. It is also used to select execution sites in the exec, rexec, run,
and migrate system calls.
The site path consists of an array of site path elements. These elements may
be of three possible types:
NULLSITE Refers to the local site or to that site's machine type or a
compatible type.
site_number
The number of a specific cluster site. This type of element refers
to the specified site or to that site's machine type or a compatible
type.
(cpu_type|SPATH_CPU)
A machine type number that is specified in the file <a.out.h>. It
refers to the specified machine type or to an arbitrarily selected
site of that CPU type.
NULLSITE and SPATH_CPU are constants defined in the file <sys/types.h>. Known
cpu_type numbers include:
Processed November 7, 1990 GETSPATH(2,L) 1
GETSPATH(2,L) AIX Technical Reference GETSPATH(2,L)
hidden
code common directory compatible
name component type
CPU_386 iAPX 80386 i386 none
CPU_S370 System/370 i370 none
CPU_XA370 XA/370 xa370 i370
When selecting a component of a hidden directory (see "chhidden"), each element
of the site path is tried in turn. If a file is found in the hidden directory
with the name of the machine type or the name of a compatible type referred to
by the site path element, that file is used. A compatible type is chosen only
if the exact type is not found.
The site path is also used to choose a site for execution in the case of an
exec system call or in the case of a migrate, rexec, or run system call which
is passed a site_number argument of 0. In these cases, the site is chosen as
follows. First, the system determines the machine type on which the new
process file (for exec, rexec, or run) or the current process (for migrate)
must run. Then, the site path is searched until an element is found which
corresponds to that machine type. If the element is NULLSITE, the process runs
locally. If the element is a site number, the process executes on that site.
If the element has the SPATH_CPU bit turned on, the process runs on a randomly
chosen site of the specified type (except that the local site is chosen if it
is the right machine type).
In a setspath call, the site_path argument points to an array of length
elements of type sitepath_t. In a getspath call, the site_path argument points
to an array of sitepath_t elements into which the system will return at most
length values.
RETURN VALUE
Upon successful completion, setspath returns a value of 0 to the calling
process and getspath returns the length of the site_path array to the calling
process. Otherwise, a value of -1 is returned and errno is set to indicate the
error.
ERROR CONDITIONS
These calls fail if any of the following are true:
EINVAL length is greater than the maximum site path length allowed by the
system (setspath only).
EINVAL length is less than the length of the current process's site path
(getspath only).
EFAULT site_path points to an invalid address.
EBADST The site path specified by site_path contains an invalid site or
cpu_type number (setspath only).
Processed November 7, 1990 GETSPATH(2,L) 2
GETSPATH(2,L) AIX Technical Reference GETSPATH(2,L)
RELATED INFORMATION
In this book: "chhidden," "exec: execl, execv, execle, execve, execlp,
execvp," "migrate," "rexec: rexecl, rexecv, rexecle, rexecve, rexeclp,
rexecvp," and "run: runl, runv, runle, runve, runlp, runvp."
Processed November 7, 1990 GETSPATH(2,L) 3