dg_cpu_info(3T) DG/UX R4.11MU05 dg_cpu_info(3T)
NAME
dgcpuinfo, dgcpuinfoinit, dgcpuinfodestroy - get information
about a computer's CPU/cache/memory hierarchy
SYNOPSIS
#include <sys/dgcpu.h>
int dgcpuinfoinit(struct dgcpuinfo *infoptr);
int dgcpuinfodestroy(struct dgcpuinfo *infoptr);
int dgcpuinfo(long version,
long selector,
long selectorvalue,
long *keyptr,
struct dgcpuinfo *infoptr);
where:
infoptr A pointer to a struct dgcpuinfo to receive
information reported by dgcpuinfo().
version An integer version number for the dgcpuinfo() call,
which should be set to DGCPUINFOCURRENTVERSION.
selector An integer indicating how to select the CPU for which
dgcpuinfo() will return information;
DGCPUINFOSELECTONECPU indicates that
selectorvalue holds the desired CPU ID;
DGCPUINFOSELECTNEXTCPU indicates that keyptr is
to be used to iterate through CPU IDs across multiple
calls to dgcpuinfo()
selectorvalue An integer indicating the CPU ID for which
dgcpuinfo() will return information; this value is
ignored when selector is other than
DGCPUINFOSELECTONECPU
keyptr A pointer to a key value that is used to iterate
through CPU IDs across multiple calls to
dgcpuinfo(); the key value should be initialized
to DGCPUINFOINITIALKEY for the first call to
dgcpuinfo(); this keyptr is ignored when selector
is other than DGCPUINFOSELECTNEXTCPU.
DESCRIPTION
The dgcpuinfo() function is used to obtain information about the
CPU/cache/memory hierarchy of the underlying machine from the
perspective of a single CPU. The information is reported in the
struct dgcpuinfo structure pointed to by infoptr. This
information is typically used with the CPU affinity calls also
defined in <sys/dgcpu.h>. For a detailed description of the
information reported by dgcpuinfo() and its usage in the context of
CPU affinity, refer to <sys/dgcpu.h>.
Before calling dgcpuinfo(), the struct dgcpuinfo structure
pointed to by infoptr must be initialized by a call to
dgcpuinfoinit(). This obviates the need to initialize every CPU
ID set declared in the struct dgcpuinfo. When the struct
dgcpuinfo is no longer used, it should be destroyed with a call to
dgcpuinfodestroy().
The CPU hierarchy information can be retrieved for only one CPU ID at
a time. The selector parameter is used to decide the CPU ID for
which information will be returned. If selector is
DGCPUINFOSELECTONECPU, then selectorvalue denotes the CPU ID
for which information will be reported; in this case, keyptr is
ignored.
If selector is DGCPUINFOSELECTNEXTCPU, then keyptr points to a
key value that is used to iterate through CPU IDs across multiple
calls to dgcpuinfo(); in this case, selectorvalue is ignored.
The key value pointed to by keyptr should be initialized to
DGCPUINFOINITIALKEY for the first call to dgcpuinfo(),
indicating that dgcpuinfo() should return information for the first
existing CPU ID in the system. On return from each successful call
to dgcpuinfo(), the value pointed to by keyptr is updated; thus
the caller should not modify the value if it wishes to continue
iterating through CPU IDs. If there are more CPU IDs through which
to iterate, dgcpuinfo() returns 1; otherwise, if there are no more,
it returns 0.
The value DGCPUINFOCURRENTVERSION should be passed as the version
to dgcpuinfo().
If dgcpuinfo() fails, the contents of the locations pointed to by
infoptr and keyptr are undefined.
DIAGNOSTICS
Return Value
If successful, dgcpuinfoinit() and dgcpuinfodestroy() return 0.
Otherwise, they return -1 and set errno to indicate the error.
If successful, dgcpuinfo() returns 0 or 1. Otherwise, it returns
-1 and sets errno to indicate the error.
Errors
For each of the following conditions, dgcpuinfodestroy() and
dgcpuinfo() return -1 and set errno to the corresponding value:
[EINVAL] An invalid struct dgcpuinfo has been specified. This
occurs when DG/UX has detected that the struct dgcpuinfo
structure pointed to by infoptr has not been initialized
by a previous call to dgcpuinfoinit() or has been
corrupted.
For each of the following conditions, dgcpuinfo() returns -1 and
sets errno to the corresponding value:
[EINVAL] The value given by version does not refer to a supported
version number.
[EINVAL] The value given by selector is not
DGCPUINFOSELECTONECPU or DGCPUINFOSELECTNEXTCPU.
[ESRCH] When selector is DGCPUINFOSELECTONECPU, the value
given by selectorvalue does not denote a CPU ID of an
existing CPU.
[EAGAIN] The system could not allocate temporary memory needed to
complete the call. The caller can try again later when the
system is less loaded.
SEE ALSO
dgcpuidsetinit(3T), dgcpusetaffinity(3T),
dgcpugetaffinity(3T), threads(5).
NOTES
An application must link with -lthread in order to gain access to
these functions. However, the application need not use threads.
Currently, dgcpuinfoinit() always succeeds and returns 0. In the
future, it may need to allocate memory, which could result in an
ENOMEM failure.
Licensed material--property of copyright holder(s)