pstat(2)pstat(2)NAME
pstat: pstat_getcommandline(), pstat_getcrashdev(), pstat_getcrash‐
info(), pstat_getdisk(), pstat_getio(), pstat_getdynamic(), pstat_get‐
file2(), pstat_getfiledetails(), pstat_getipc(), pstat_getlv(),
pstat_getlwp(), pstat_getmpathname(), pstat_getmsg(), pstat_getnode(),
pstat_getpathname(), pstat_getpmq(), pstat_getproc(), pstat_getproces‐
sor(), pstat_getprocvm(), pstat_getpsem(), pstat_getpset(), pstat_get‐
sem(), pstat_getshm(), pstat_getsocket(), pstat_getstable(), pstat_get‐
static(), pstat_getstream(), pstat_getswap(), pstat_getvminfo() - an
infrastructure for obtaining information from the kernel
SYNOPSIS
Remarks
Each function in is described in its own section below.
The functions and are described in a separate manpage; see pstat_getlo‐
cality(2).
DESCRIPTION
The HP-UX facility is a supported Application Programming Interface
(API) that returns detailed information about many aspects of a running
kernel. The pstat facility provides a number of functions, and corre‐
sponding structures, to get this information from the kernel.
This manpage serves as an overview of the pstat facility as well as the
manpage for most of the pstat functions. The associated data structure
members and other identifiers for these pstat functions are described
in the include files and use these header files to infer information
about the usage of pstat functions that have their own manpages (see
the subsection).
Summary of Available Contexts
The pstat routines support certain areas of information, summarized in
the following table. The columns are defined as follows:
Context The area of information.
Struct The name of the structure that is used by the kernel to com‐
municate results back to the caller.
Routine The name of the pstat function used to access the context.
Instances The number of instances per item of the given context in the
kernel.
SC Shortcut. "Yes" means a short cut exists; that is, if a spe‐
cial combination of inputs to the given function returns
information about a particular instance of the given context.
"No" means no short cut. "N/A" means not applicable.
─────────────┬─────────────────┬───────────────────────┬────────────────┬────
Context │Struct │Routine │Instances │SC
─────────────┼─────────────────┼───────────────────────┼────────────────┼────
Static │pst_static │pstat_getstatic() │1/system │N/A
Dynamic │pst_dynamic │pstat_getdynamic() │1/system │N/A
VM │pst_vminfo │pstat_getvminfo() │1/system │N/A
IPC │pst_ipcinfo │pstat_getipc() │1/system │N/A
Stable Store │pst_stable │pstat_getstable() │1/system │N/A
Crash Dumps │pst_crashinfo │pstat_getcrashinfo() │1/system │N/A
─────────────┼─────────────────┼───────────────────────┼────────────────┼────
Processor │pst_processor │pstat_getprocessor() │1/processor │No
Disk │pst_diskinfo │pstat_getdisk() │1/disk │No
IO Object │pst_ioinfo │pstat_getio() │1/IO object │No
Swap │pst_swapinfo │pstat_getswap() │1/swap area │No
Dump Areas │pst_crashdev │pstat_getcrashdev() │1/dump area │No
Node │pst_node │pstat_getnode() │1/node │No
Locality │pst_locality │pstat_getlocality() │1/locality │No
─────────────┼─────────────────┼───────────────────────┼────────────────┼────
Command Line │char * │pstat_getcommandline() │1/process │Yes
Process │pst_status │pstat_getproc() │1/process │Yes
LW Process │lwp_status │pstat_getlwp() │1/lwp/thread │Yes
Process VM │pst_vm_status │pstat_getprocvm() │1/process region│Yes
Process Loc. │pst_proc_locality│pstat_getproclocality()│1/process loc. │Yes
LVM Vol │pst_lvinfo │pstat_getlv() │1/lvol │Yes
Sema Set │pst_seminfo │pstat_getsem() │1/sem set │Yes
Msg Queue │pst_msginfo │pstat_getmsg() │1/msg queue │Yes
Shared Mem │pst_shminfo │pstat_getshm() │1/shm seg │Yes
Processor Set│pst_pset │pstat_getpset() │1/proc set │Yes
P-Sema Set │pst_pseminfo │pstat_getpsem() │1/sema │No
P-Msg Queue │pst_pmqinfo │pstat_getpmq() │1/msg queue │No
─────────────┼─────────────────┼───────────────────────┼────────────────┼────
Open File │pst_fileinfo2 │pstat_getfile2() │1/file │Yes
─────────────┼─────────────────┼───────────────────────┼────────────────┼────
Open File │pst_filedetails │pstat_getfiledetails() │1/file/call │N/A
Open Socket │pst_socket │pstat_getsocket() │1/socket/call │N/A
Open Stream │pst_stream │pstat_getstream() │1/stream/call │No
Open File │char * │pstat_getpathname() │1/file/call │N/A
─────────────┼─────────────────┼───────────────────────┼────────────────┼────
DNLC │pst_mpathnode │pstat_getmpathname() │1/DNLC entry │Yes
─────────────┴─────────────────┴───────────────────────┴────────────────┴────
The pstat Context
A pstat context represents a logical object or a related set of logical
objects upon which pstat reports. A pstat context does not necessarily
correspond directly to a kernel object. For instance, the dynamic con‐
text represents a collection of some of the dynamic system-wide infor‐
mation available from the system. There may be exactly one, or more
than one, instance of a given pstat context.
The pstat Index
The pstat index, which exists as an argument of many pstat functions
and as a return field of many pstat functions, represents a logical
placement within the given pstat context under consideration. For
pstat contexts with more than one instance, it provides a mechanism to
obtain all of the instances of a given context via multiple calls of
the given pstat function. Do not presume that the pstat index has any
relation to the representation of objects within the kernel; it should
not be used for any purpose other than to obtain instances of this par‐
ticular pstat context. Different instances of a pstat context are not
necessarily contained in sequential pstat indices.
Data Consistency
The pstat functions return data that may be rapidly changing in time.
The data may even change during a single pstat function call. Applica‐
tions may need to be aware of potential consistency issues in data
returned by pstat due to this. There are two senses of data consis‐
tency for pstat: the self-consistency of data within a given pstat
instance and consistency between two or more pstat instances, which may
even be from different contexts.
In general, an attempt is made by the pstat implementation to provide
reasonable self-consistency of a given pstat instance within the bounds
of performance constraints. The pstat implementation is designed such
that the information returned in a given data structure will contain
only information about one instance of the given pstat context. How‐
ever, since pstat often reports on kernel data that are rapidly chang‐
ing or that may change at any time, self-consistency between fields
within a given structure returned for a pstat instance is not assured.
In general, no attempt is made to provide consistency between two
instances of pstat contexts. This is true even if these two instances
are obtained via the same call. It is also true that two pstat func‐
tion calls that return the same instance of a pstat context may not be
consistent with each other due to changes in the kernel data that
occurred between the two calls. However, the pstat indexing technique
represents a general attempt by the pstat interfaces to ensure that two
instances of a pstat context with different indices represent different
objects.
Backward Compatibility
The pstat functions have a specific calling convention of passing the
expected data structure size into the function as a parameter in order
to allow for future expansion of the interface, while preserving back‐
wards source and object compatibility for programs written using the
pstat interfaces. Three rules are followed to allow existing applica‐
tions to continue to execute from release to release of the operating
system.
· New data for a context are added to the end of that context's data
structure.
· Old, obsolete data members are deleted from the data structure.
· The operating system honors the elemsize parameter of the call and
only returns the first elemsize bytes of the context data, even if
the actual data structure has since been enlarged.
In this way, an application that passes its compile-time size of the
context's data structure (for example, for the Processor context) as
the elemsize parameter will continue to execute on future operating
system releases without recompilation, even those that have larger con‐
text data structures. If the program is recompiled, it will also con‐
tinue to execute on that and future releases. Note that the reverse is
not true: a program using the pstat interfaces compiled on, for exam‐
ple, HP-UX 11i Version 2 will not necessarily work on HP-UX 11i Version
1.
Programming Model Considerations
While the pstat functional interfaces, and their pstat data that are
available to applications compiled using the ILP32 programming model
are source-compatible with the same applications written using the LP64
programming model, the corresponding structures in each of these pro‐
gramming models may differ in size. To accomodate applications written
in standard C and extended ANSI C that must still use the ILP32 pro‐
gramming model, the structures are provided in a transitional mode.
Such an application can use the flag at compile time to switch to using
these transitional structures. Using this compiler flag on such an
application is equivalent to using the pstat interfaces on an applica‐
tion using the LP64 programming model.
The use of the pstat functional interfaces for applications using the
ILP32 programming model without defining the compiler flag is depre‐
cated. Furthermore, some pstat functions are available only for appli‐
cations using the LP64 programming model and for applications written
in standard C and extended ANSI C that use the ILP32 programming model
and that define The pstat functions and are some of the pstat functions
that fall into this category.
Security Restrictions
Some or all of the actions associated with this system call are subject
to compartmental restrictions. This restriction applies when attempt‐
ing to get information on message queues, semaphores or processes which
are in a different compartment. See compartments(5) for more informa‐
tion about compartmentalization on systems that support that feature.
Compartmental restrictions can be overridden if the process possesses
the privilege (PRIV_COMMALLOWED). Processes owned by the superuser may
not have this privilege. Processes owned by any user may have this
privilege, depending on system configuration. See privileges(5) for
more information about privileged access on systems that support fine-
grained privileges.
PSTAT FUNCTION
Name
- get command line of a process
Synopsis
Description
returns the command line of the process specified in the pid parameter.
Up to a maximum of bytes is returned in the buffer buf, if the elemsize
is less than or equal to the size of the process command line. If the
elemsize is greater than the size of process command line, only the
available number of bytes are returned. Up to a maximum of 1020 char‐
acters of the process command line is stored. The elemcount parameter
must be
PSTAT FUNCTION
Name
- get information for a crash dump device
Synopsis
Description
returns information specific to a particular crash dump device. There
is one instance of this context for each crash dump device configured
on the system. For each instance requested, up to a maximum of elem‐
size bytes of data is returned in the structures pointed to by buf.
The elemcount parameter specifies the number of structures that are
available at buf to be filled in. The index parameter specifies the
starting index within the context of crash dump devices.
PSTAT FUNCTION
Name
- get information for a system's crash dump configuration
Synopsis
Description
returns information about the system's crash dump configuration. Up to
a maximum of elemsize bytes of data is returned in the structure
pointed to by buf. The elemcount parameter must be The index parameter
must be
PSTAT FUNCTION
Name
- get information for a disk
Synopsis
Description
returns information specific to a particular disk. There is one
instance of this context for each disk opened in the system. Unused,
closed disks may not have a context and the number of contexts may not
match the number of disks configured into the system. For each
instance requested, up to a maximum of elemsize bytes of data is
returned in the structures pointed to by buf. The elemcount parameter
specifies the number of structures that are available at buf to be
filled in. The index parameter specifies the starting index within the
context of disks. Some contexts may persist after their disks have
been closed. An application should use the field in the structure to
tell if the disk is opened (1) or closed (0).
PSTAT FUNCTION
Name
- get information for an IO Object
Synopsis
Description
returns information specific to a particular IO Object. IO objects
include devices like tape, changer and other objects like lunpath and
HBAs. There is one instance of this context for each IO object opened
in the system. Unused, closed IO objects may not have a context and
the number of contexts may not match the number of IO objects config‐
ured into the system. For each instance requested, up to a maximum of
elemsize bytes of data is returned in the structures pointed to by buf.
The elemcount parameter specifies the number of structures that are
available at buf to be filled in. The index parameter specifies the
starting index within the context of IO objects. Some contexts may
persist after their IO objects have been closed. An application should
use the field in the structure to tell if the IO object is opened (1)
or closed (0).
PSTAT FUNCTION
Name
- get dynamic information about the system
Synopsis
Description
returns dynamic information about the system. This data may change
frequently during the normal operation of the kernel. There is one
global instance of this context. Up to a maximum of elemsize bytes of
data is returned in the structure pointed to by buf. The elemcount
parameter must be The index parameter must be
PSTAT FUNCTION
Name
- get information for an open file of a process
Synopsis
Description
returns information specific to a particular open file for a specified
process. For the specified process, there is one instance of this con‐
text for each open file descriptor. For each instance requested, up to
a maximum of elemsize bytes of data is returned in the structures
pointed to by buf. The elemcount parameter specifies the number of
structures that are available at buf to be filled in. The index param‐
eter specifies the starting index within the context of open files for
the specified process: It is the file descriptor number with which to
begin. The pid parameter specifies the process ID.
As a shortcut, information for a single file within the specified
process can be obtained by setting elemcount to and setting the index
to the file descriptor number.
The structure contains both a and element. The element can correctly
store a 32-bit value, whereas the element can store a 64-bit value.
will fill in both and if the value can be correctly stored in both ele‐
ments. If the offset is too large to be correctly stored in then will
contain a No error will be set in this case.
PSTAT FUNCTION
Name
- get detailed information for an open file
Synopsis
Description
returns detailed information specific to a particular open file. For a
specified open file, there is only one instance of this context. For
each call, up to a maximum of elemsize bytes of data is returned in the
structure pointed to by buf. The fid parameter uniquely identifies the
file. This fid is obtained from calls to or The structure contains
information equivalent to the stat(2) call. The use of this function
is limited to UID 0 or an effective UID match. An effective UID match
occurs when the effective or real UID of the calling thread matches the
effective or real UID of the target process and the target process has
done a setuid or a setgid.
The structure members will have meaningful values for regular files,
character or block special files, and pipes. The value of the member
will be set to number of links to the file. The member will have mean‐
ingful value for character or block special files, while the is valid
for regular files. The members and are unique IDs representing the
open file. These IDs together are used to match the corresponding IDs
returned from the This call does not work for sockets other than the
AF_UNIX family type.
PSTAT FUNCTION
Name
- get information about the System V IPC subsystem
Synopsis
Description
returns information about the System V IPC subsystem. There is one
global instance of this context. This data may change while the system
is running due to administrative changes in the associated kernel tun‐
ables. Up to a maximum of elemsize bytes of data is returned in the
structure pointed to by buf. The elemcount parameter must be The index
parameter must be
PSTAT FUNCTION
Name
- get information for a locality
Description
See the pstat_getlocality(2) manpage for the synopsis and full descrip‐
tion.
PSTAT FUNCTION
Name
- get information for a logical volume
Synopsis
Description
returns information specific to a particular logical volume. There is
one instance of this context for each logical volume configured into
the system. For each instance requested, up to a maximum of elemsize
bytes of data is returned in the structures pointed to by buf. The
elemcount parameter specifies the number of structures that are avail‐
able at buf to be filled in. The index parameter specifies the start‐
ing index within the context of logical volumes. As a shortcut, infor‐
mation for a single logical volume can be obtained by setting elemcount
to and setting index to the of that logical volume.
PSTAT FUNCTION
Name
- get information for a thread or LWP in a process
Synopsis
Description
returns information specific to a particular thread or LWP (Lightweight
Process) in a process. There is one instance of this context for each
LWP in a process on the system. For each instance requested, up to a
maximum of elemsize bytes of data is returned in the structure pointed
to by buf. The elemcount parameter specifies the number of structures
that are available at buf to be filled in. The index parameter speci‐
fies the starting index within the context of LWPs in a process.
If pid is set to and elemcount is greater than elemcount entries of
system LWP information are returned to the caller program.
If pid is greater than or equal to and elemcount is greater than elem‐
count entries of LWP info within the process specified by pid are
returned.
As a shortcut, information about a single LWP can be obtained by set‐
ting elemcount to and setting index to the TID (Thread ID) of that LWP
within its process.
PSTAT FUNCTION
Name
- get entries from system cache of recently looked-up names
Synopsis
Description
returns the entries from the system cache of recent names looked up
(DNLC) for a specified file system, in buf. The parameter uniquely
identifies the file system. This should be the field of a structure
obtained from calls to or The index parameter specifies the starting
entry within the chain of DNLC entries to be returned for the specified
file system. The elemcount parameter specifies the number of DNLC
entries to be returned. Typically, the index parameter will be speci‐
fied as and the elemcount parameter will be high enough to obtain all
the entries of the specified file system. For each call, up to a maxi‐
mum of elemsize bytes of data is returned in the structures pointed to
by buf. The structure contains the following members:
is the current index of an entry into the chain of DNLC entries for the
file system. can be passed on to another call as the index parameter
to obtain the entries starting after the last is the file the current
entry describes and is the parent of this file. is the path name com‐
ponent for the current entry.
Reverse path name lookup can be performed by searching the entries for
one that has a member equal to the member of the current entry. This
is done until an entry with a entry is located, which indicates that
the entry for the root of the file system has been found. The path
name from the root of the file system is formed by concatenating the
names given by the member of each of the entries found during the
process. If desired, the full path name can then be formed by concate‐
nating the path name to the mount point of the file system.
The use of this function is limited to UID 0.
On success, the function returns the number of DNLC entries copied. In
case of failure, the value of is returned and is set indicating the
cause of the failure.
PSTAT FUNCTION
Name
- get information for a System V message queue
Synopsis
Description
returns information specific to a particular System V message queue.
There is one instance of this context for each System V message queue
on the system. For each instance requested, up to a maximum of elem‐
size bytes of data is returned in the structures pointed to by buf.
The elemcount parameter specifies the number of structures that are
available at buf to be filled in. The index parameter specifies the
starting index within the context of System V message queues. As a
shortcut, information for a single message queue can be obtained by
setting elemcount to and setting index to the of that message queue.
PSTAT FUNCTION
Name
- get information about an SCA system node
Synopsis
Description
returns information about a specific SCA system node. There is one
instance of this context for each SCA node on the system. For each
instance requested, up to a maximum of elemsize bytes is returned in
the structure pointed to by buf. The elemcount parameter specifies the
number of structures that are available at buf to be filled in. The
index parameter specifies the starting logical node ID that is
requested.
PSTAT FUNCTION
Name
- get the full path name of an open file
Synopsis
Description
returns the full path name of an open file in buf if it is available in
the system cache of recent names looked up (DNLC). The fid parameter
uniquely identifies the open file. This fid is obtained from calls to
or The value of elemcount should be at least one greater than the
length of the path name to be returned. The variable from pathconf(2)
can be used for this purpose. The use of this function is limited to
UID 0 or an effective UID match. See for the definition of effective
UID match.
On success, the function returns the length of the path name copied
starting at the location specified by buf. If the path name is not
available in the system cache, is returned and is not set. On other
failures, the value of is returned and is set indicating the cause of
the failure. This call does not work for sockets.
PSTAT FUNCTION
Name
- get information for a POSIX message queue
Synopsis
Description
returns information specific to a particular POSIX message queue.
There is one instance of this context for each POSIX message queue on
the system. For each instance requested, up to a maximum of elemsize
bytes of data is returned in the structures pointed to by buf. The
elemcount parameter specifies the number of structures that are avail‐
able at buf to be filled in. The index parameter specifies the start‐
ing index within the context of POSIX message queues.
PSTAT FUNCTION
Name
- get information for a process
Synopsis
Description
returns information specific to a particular process. There is one
instance of this context for each active process on the system. For
each instance requested, up to a maximum of elemsize bytes of data is
returned in the structures pointed to by buf. The elemcount parameter
specifies the number of structures that are available at buf to be
filled in. The index parameter specifies the starting index within the
context of processes. As a shortcut, information for a single process
can be obtained by setting elemcount to and setting index to the of
that process.
PSTAT FUNCTION
Name
- get information for a processor
Synopsis
Description
returns information specific to a particular processor (the only pro‐
cessor on a uniprocessor system). There is one instance of this con‐
text for each processor on the system. For each instance requested, up
to a maximum of elemsize bytes of data is returned in the structures
pointed to by buf. The elemcount parameter specifies the number of
structures that are available at buf to be filled in. The index param‐
eter specifies the starting index within the context of processors.
PSTAT FUNCTION
Name
- get information for a process's memory placement for each locality
Description
See the pstat_getlocality(2) manpage for the synopsis and full descrip‐
tion.
PSTAT FUNCTION
Name
- get information for a process's address space
Synopsis
Description
returns information specific to a particular process's address space.
There is one instance of this context for each process region contained
in the process's address space. For each instance requested, up to a
maximum of elemsize bytes of data is returned in the structure pointed
to by buf. Only at most one instance (process region) is returned for
each call to The elemcount parameter identifies the process for which
address space information is to be returned. An elemcount parameter of
indicates that address space information for the currently executing
process should be returned. The index parameter specifies the starting
index (beginning with 0) within the context of process regions for the
indicated process. For example, an index of indicates the 4th process
region within the indicated process's address space. As a shortcut,
information for a specific process (other than the currently executing
one) can be obtained by setting elemcount to the of that process. More
information on VM regions mapped to files can be obtained with the
call.
PSTAT FUNCTION
Name
- get information for a POSIX named semaphore
Synopsis
Description
returns information specific to a particular POSIX named semaphore.
There is one instance of this context for each POSIX named semaphore on
the system. For each instance requested, up to a maximum of elemsize
bytes of data is returned in the structures pointed to by buf. The
elemcount parameter specifies the number of structures that are avail‐
able at buf to be filled in. The index parameter specifies the start‐
ing index within the context of POSIX named semaphore sets.
PSTAT FUNCTION
Name
- get information for a processor set
Synopsis
Description
returns information specific to a particular processor set. There is
one instance of this context for each processor set on the system. For
each instance requested, up to a maximum of elemsize bytes of data is
returned in the structure pointed by buf. The elemcount parameter
specifies the number of structures that are available at buf to be
filled in. The index parameter specifies the starting index within the
context of processor sets. As a shortcut, information for a single
processor set can be obtained by setting elemcount to and setting index
to the pset ID of that processor set.
PSTAT FUNCTION
Name
- get information for a System V semaphore set
Synopsis
Description
returns information specific to a particular System V semaphore set.
There is one instance of this context for each System V semaphore set
on the system. For each instance requested, up to a maximum of elem‐
size bytes of data is returned in the structures pointed to by buf.
The elemcount parameter specifies the number of structures that are
available at buf to be filled in. The index parameter specifies the
starting index within the context of System V semaphore sets. As a
shortcut, information for a single semaphore set can be obtained by
setting elemcount to and setting index to the of that semaphore set.
PSTAT FUNCTION
Name
- get information for a System V shared memory segment
Synopsis
Description
returns information specific to a particular System V shared memory
segment. There is one instance of this context for each System V
shared memory segment on the system. For each instance requested, up
to a maximum of elemsize bytes of data is returned in the structures
pointed to by buf. The elemcount parameter specifies the number of
structures that are available at buf to be filled in. The index param‐
eter specifies the starting index within the context of System V shared
memory segments. As a shortcut, information for a single shared memory
segment can be obtained by setting elemcount to and setting index to
the of that shared memory segment.
PSTAT FUNCTION
Name
- get detailed information for a socket
Synopsis
Description
returns detailed information specific to a socket. For the specified
socket, there is one instance of this context. For each call, up to a
maximum of elemsize bytes of data is returned in the structure pointed
to by buf. The fid parameter uniquely identifies the socket. This fid
is obtained from calls to The use of this function is limited to UID 0
or an effective UID match. See for the definition of effective UID
match.
On success, the function returns On failure, the value of is returned
and is set indicating the cause of the failure. For AF_UNIX sockets
that are opened to files, more information about the files can be
obtained with the call. In case of AF_UNIX sockets, the fields and can
be used to find the peer socket by matching them with and The members
and contain data of the form and so on, depending on the socket family.
Note
The socket state in the field of is deprecated and will be obso‐
leted/removed in a future release.
PSTAT FUNCTION
Name
- get information from the system's stable storage area
Synopsis
Description
returns information contained in the system's stable storage area.
There is one global instance of this context. Up to a maximum of elem‐
size bytes of data is returned in the structure pointed to by buf. The
elemcount parameter must be The index parameter must be
PSTAT FUNCTION
Name
- get information about the system
Synopsis
Description
returns information about the system. Although this data usually does
not change frequently, it may change while the system is running due to
manually or automatically generated administrative changes in the asso‐
ciated kernel tunables, online addition/deletion of resources, or other
events. There is one global instance of this context. Up to a maximum
of elemsize bytes of data is returned in the structure pointed to by
buf. The elemcount parameter must be The index parameter must be
PSTAT FUNCTION
Name
- get detailed information for a stream
Synopsis
Description
returns detailed information specific to a stream. For the specified
stream, there is one instance of this context for the stream head, each
module, and the driver. For each call, up to a maximum of elemsize
bytes of data is returned in the structures pointed to by buf. The
elemcount parameter specifies the number of structures that are avail‐
able at buf to be filled in. The moduleskip parameter indicates the
number of modules to skip before returning information about any mod‐
ules. Head information is returned for every call. The fid parameter
uniquely identifies the file. This ID is obtained from calls to
On success, the function returns the number of structures returned
starting at the location specified by buf. This is at least 1, as the
head information is always returned. On failure, the value of is
returned and is set indicating the cause of the failure.
The use of this function is limited to UID 0 or an effective UID match.
See for the definition of effective UID match.
The field can be or The union in structure will represent the struc‐
tures or in the respective cases. If the flag is set in for the field
in represents the clone driver sequence number for the stream.
PSTAT FUNCTION
Name
- get information for a swap area
Synopsis
Description
returns information specific to a particular swap area. There is one
instance of this context for each swap area (block or file system) con‐
figured into the system. For each instance requested, up to a maximum
of elemsize bytes of data is returned in the structures pointed to by
buf. The elemcount parameter specifies the number of structures that
are available at buf to be filled in. The index parameter specifies
the starting index within the context of swap areas.
PSTAT FUNCTION
Name
- get information about the virtual memory subsystem
Synopsis
Description
returns information about the virtual memory subsystem. There is one
global instance of this context. Up to a maximum of elemsize bytes of
data is returned in the structure pointed to by buf. The elemcount
parameter must be The index parameter must be
RETURN VALUE
Upon successful completion, the various pstat functions (for example,
return the number of instances, which could be 0, filled in at the
address provided by the user. however, returns the number of charac‐
ters of the process command line returned at the address provided by
the user and returns the number of characters of the file path name
returned at the address provided by the user. Otherwise, a value of is
returned and is set to indicate the error.
EOVERFLOW Error
It is possible for a given field of a pstat structure to be too narrow
to contain correctly the data that the kernel is instructed to provide.
For example, over time, the growth of physical memory on the system may
become too large to be contained in the pstat field that reports it.
For this purpose, a pstat data structure may contain fields whose pur‐
pose it is to indicate whether other fields in that data structure con‐
tain valid data; there may be associated macros for use in interpreting
those fields. Within a given pstat data structure, each such field is
known as a validity vector for that structure, and each such macro is
known as a validity macro associated with that data structure.
If the call completes successfully, the validity vectors of the struc‐
tures returned need not be checked. However, if a call returns an
error with set, the last structure returned as a result of the call
contains at least one data item that exceeded the value that can be
stored in the corresponding field. This structure may still contain
some fields with valid data. All preceding structures were filled in
by the kernel. Since the number of structures returned by the kernel
is not directly available to the application in this case, the applica‐
tion must infer how many structures the kernel has filled in, by the
following method.
To determine which structure resulted in the error return with
set, the application must examine pstat structures sequentially,
beginning with the first such structure requested from the ker‐
nel. The pstat structure that has at least one validity vector
equal to is the structure that caused the error return with set
and is the last structure filled in by the kernel for this pstat
call.
For those pstat functions that return at most only one struc‐
ture, such as an error return with set means that the only
structure requested is the structure that caused the error
return with
Once the structure that caused the error return with has been deter‐
mined, the particular fields of that structure that do not contain
valid data can be determined as follows. Please note that all preced‐
ing structures were filled in by the kernel, and fields from those
structures need not be checked in this manner.
Such fields can be determined using the validity macros explic‐
itly defined for the corresponding data structure and the corre‐
sponding validity vector for that particular structure. These
validity macros correspond to one specific field within the
given data structure. If the bitwise AND of a particular valid‐
ity macro with its corresponding validity vector evaluates to
the field corresponding to that validity macro does not contain
valid data. Otherwise, that field contains valid data. The
only candidate fields to have resulted in this condition are
those fields with validity macros explicitly defined in the cor‐
responding data structure. The other fields within that partic‐
ular structure need not be checked using this method.
See also the section below.
ERRORS
If a pstat function fails, is set to one of the following values. If
an underlying function fails, may be set to a value not specified here;
see errno(2) for such errors.
The UID is not 0 (superuser)
and the effective UID does not match for or See for the
definition of effective UID match.
buf or fid points to an invalid address.
For the operation was terminated due to the receipt of a
signal; no data was transferred.
For or elemcount was not and index was less than
elemsize is less than or equal to or elemsize is larger than the
size of the associated data structure. For example,
elemsize is greater than for
For or elemcount is not or index is not
For or elemcount is not greater than or equal to or index is
not greater than or equal to
For index is not a valid logical node ID.
For elemcount is less than or equal to
was called for a socket other than the AF_UNIX family,
or was called for a socket.
was called for a file that is not of type socket.
was called with
pid less than or elemcount not equal to
For the operation was terminated due to unavailability of
buffer space.
For or the file was not found, or it was closed.
For the specified file system was not found or the file
system did not have DNLC entries.
was called for a file that is neither a stream
nor a stream-based pipe or socket.
The requested pstat function is not implemented or not configured in
the system.
The offset element is too large to store into the structure
pointed to by the buf parameter.
For a value to be stored would overflow one of the members
of the structure. The member indicates the field that
overflowed.
For the elemcount parameter is not greater than the length
of the path name to be returned.
The process in question was not found or was exiting.
For or elemcount was 0, specifying the single-item
short-cut, and no item matched the selection criteria in
index. For example, for
EXAMPLES
All of these examples are compiled with the flag. All examples have
the following prolog. The define of is placed before the inclusion of
the header so that it takes effect in that file.
#ifndef _PSTAT64
#define _PSTAT64
#endif
#include <sys/pstat.h>
#include <sys/unistd.h>
#include <sys/socket.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <fcntl.h>
Example 1
Get global information from
main()
{
struct pst_static pst;
(void)memset(&pst,0,sizeof(struct pst_static));
if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) == 1)
(void)printf("page size is %lld bytes\n", pst.page_size);
else
perror("pstat_getstatic");
}
Example 2
Get information about all processors, first obtaining number of proces‐
sor context instances.
main()
{
struct pst_dynamic psd;
struct pst_processor *psp;
(void)memset(&psd,0,sizeof(struct pst_dynamic));
if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) == 1) {
size_t nspu = psd.psd_proc_cnt;
psp = (struct pst_processor *)
malloc(nspu * sizeof(struct pst_processor));
(void)memset(psp,0,nspu*sizeof(struct pst_processor));
if (pstat_getprocessor(psp, sizeof(struct pst_processor), nspu,
0) != -1) {
int i;
unsigned long long total_execs = 0;
for (i = 0; i < nspu; i++) {
unsigned long long execs = psp[i].psp_sysexec;
total_execs += execs;
(void)printf("%llu exec()s on processor #%d\n",
execs, i);
}
(void)printf("total execs for the system were %llu\n",
total_execs);
}
else
perror("pstat_getprocessor");
}
else
perror("pstat_getdynamic");
}
Example 3A
Get dynamic information about the amount of virtual memory actively in
use on the system.
main()
{
struct pst_dynamic psd;
(void)memset(&psd,0,sizeof(struct pst_dynamic));
if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) == 1) {
(void)printf("total active virtual memory for the system %lld\n",
psd.psd_avm);
}
else
perror("pstat_getdynamic");
}
Example 3B
Get dynamic information about the amount of virtual memory actively in
use on the system. Program explicitly handles the possibility of as it
is using data from a call that may, in principle, overflow.
main()
{
struct pst_dynamic psd;
int ret,valid_avm_data;
(void)memset(&psd,0,sizeof(struct pst_dynamic));
ret = pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0);
valid_avm_data = (ret == 1) ||
((ret == -1) && (errno == EOVERFLOW) && (psd.psd_valid & PSD_AVM));
if (valid_avm_data) {
(void)printf("total active virtual memory for the system %lld\n",
psd.psd_avm);
}
else
perror("pstat_getdynamic");
}
Example 4A
Get information about all processes, 10 at a time. We do it this way
since the current count of active processes is unknown.
main()
{
#define BURST ((size_t)10)
struct pst_status pst[BURST];
int i, count;
int idx = 0; /* pstat index within the Process pstat context */
/* loop until count == 0, will occur all have been returned */
(void)memset(pst,0,BURST*sizeof(struct pst_status));
while ((count=pstat_getproc(pst, sizeof(pst[0]),BURST,idx))>0) {
/* got count this time. process them */
for (i = 0; i < count; i++) {
(void)printf("pid is %lld, command is %s\n",
pst[i].pst_pid, pst[i].pst_ucomm);
}
/*
* now go back and do it again, using the next index after
* the current 'burst'
*/
idx = pst[count-1].pst_idx + 1;
(void)memset(pst,0,BURST*sizeof(struct pst_status));
}
if (count == -1)
perror("pstat_getproc()");
#undef BURST
}
Example 4B
Get information about all processes, 10 at a time. We do it this way
since the current count of active processes is unknown. The program
explicitly handles the possibility of as it is using data from a field
that may in principle overflow.
main()
{
#define BURST ((size_t)10)
struct pst_status pst[BURST];
int i, ret, count;
int idx = 0; /* pstat index within the Process pstat context */
do {
(void)memset(pst,0,BURST*sizeof(struct pst_status));
count = 0;
ret = pstat_getproc(pst, sizeof(pst[0]),BURST,idx);
if (ret > 0) {
/* normal case: got ret Process contexts to report */
count = ret;
}
else if ((ret == 0)) {
/* normal case: finished all Process contexts */
count = 0;
}
else if ((ret == -1) && (errno == EOVERFLOW)) {
/* EOVERFLOW case: at least one Process context hit it,
so we find the one that caused this error. Neither of
the fields we are interested in has a validity macro
defined, so we just count the number of structures
returned to us */
for (i=0;i<BURST;i++) {
count++;
if (pst[i].pst_valid!=-1) {
break;
}
}
}
else if ((ret == -1)) {
/* error case */
perror("pstat_getproc()");
count = 0;
}
/* got count this time. process them */
for (i = 0; i < count; i++) {
(void)printf("pid is %lld, command is %s\n",
pst[i].pst_pid, pst[i].pst_ucomm);
}
/*
* now go back and do it again, using the next index after
* the current 'burst' if there are potentially more to find
*/
if (count)
idx = pst[count-1].pst_idx + 1;
} while (count);
#undef BURST
}
Example 5
Get information about our parent using
main()
{
struct pst_status pst;
int target = (int)getppid();
(void)memset(&pst,0,sizeof(struct pst_status));
if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1)
(void)printf("Parent real uid is %lld\n", pst.pst_uid);
else
perror("pstat_getproc");
}
Example 6
Get information about all shared memory segments.
main()
{
struct pst_ipcinfo psi;
struct pst_shminfo *pss;
(void)memset(&psi,0,sizeof(psi));
if (pstat_getipc(&psi, sizeof(psi), (size_t)1, 0) != -1) {
size_t num_shm = psi.psi_shmmni;
pss = (struct pst_shminfo *)
malloc(num_shm * sizeof(struct pst_shminfo));
(void)memset(pss,0,num_shm*sizeof(struct pst_shminfo));
if (pstat_getshm(pss, sizeof(struct pst_shminfo), num_shm, 0)
!= -1) {
int i;
(void)printf("owner\tkey\tsize\n");
for (i = 0; i < num_shm; i++) {
/* skip inactive segments */
if (!(pss[i].psh_flags & PS_SHM_ALLOC))
continue;
(void)printf("%lld\t%#llx\t%llu\n",
pss[i].psh_uid, pss[i].psh_key,
pss[i].psh_segsz);
}
}
else
perror("pstat_getshm");
}
else
perror("pstat_getipc");
}
Example 7
List all the open files for the parent process.
main()
{
#define BURST ((size_t)10)
pid_t target = getppid();
struct pst_fileinfo2 psf[BURST];
int i, count;
int idx = 0; /* index within the context */
(void)printf("Open files for process PID %d\n", target);
/* loop until all fetched */
while ((count = pstat_getfile2(psf, sizeof(struct pst_fileinfo2),
BURST, idx, target)) > 0) {
/* process them (max of BURST) at a time */
for (i = 0; i < count; i++) {
(void)printf("fd #%llu\tFSid %llx:%llx\tfileid %lld\n",
psf[i].psf_fd,
psf[i].psf_id.psf_fsid.psfs_id,
psf[i].psf_id.psf_fsid.psfs_type,
psf[i].psf_id.psf_fileid);
}
/*
* Now go back and do it again, using the
* next index after the current 'burst'
*/
idx = psf[count-1].psf_fd + 1;
}
if (count == -1)
perror("pstat_getfile2()");
#undef BURST
}
Example 8
Acquire information about a specific LWP.
main()
{
struct lwp_status lwpbuf;
int count;
/*
* get information for LWP whose lwpid is 4321 within
* a process whose pid is 1234.
*/
count = pstat_getlwp(&lwpbuf, sizeof(struct lwp_status),
0, 4321, 1234);
if ((count == -1) && (errno == ESRCH))
perror("pstat_getlwp(): cannot find given lwpid or pid");
else if (count == -1)
perror("pstat_getlwp()");
else {
/* process data from the call... */
(void)printf("processing lwp data...\n");
}
}
Example 9
Acquire detailed information about a specific file.
main()
{
struct pst_fileinfo2 psf;
struct pst_filedetails psfdetails;
int count, fd;
(void)memset(&psf,0,sizeof(psf));
(void)memset(&psfdetails,0,sizeof(psfdetails));
fd = open("/stand/vmunix", O_RDONLY);
count = pstat_getfile2(&psf, sizeof(psf), 0, fd, getpid());
if (count == 1) {
count = pstat_getfiledetails(&psfdetails, sizeof(psfdetails),
&psf.psf_fid);
if (count == 1) {
if ((psfdetails.psfd_hi_fileid == psf.psf_hi_fileid) &&
(psfdetails.psfd_lo_fileid == psf.psf_lo_fileid) &&
(psfdetails.psfd_hi_nodeid == psf.psf_hi_nodeid) &&
(psfdetails.psfd_lo_nodeid == psf.psf_lo_nodeid)) {
printf("Success\n");
}
else {
printf("State changed\n");
}
}
else {
perror("pstat_getfiledetails()");
}
}
else {
perror("pstat_getfile2");
}
close(fd);
}
Example 10
Acquire detailed information about a stream.
main()
{
struct pst_fileinfo2 psf;
struct pst_stream psfstream[3];
int rv, count, fd;
(void)memset(&psf,0,sizeof(psf));
(void)memset(&psfstream,0,sizeof(psfstream));
fd = open("/dev/echo", O_RDONLY);
rv = pstat_getfile2(&psf, sizeof(psf), 0, fd, getpid());
if (rv == 1) {
/*
* Ask for 3 structures (head + module(s) + driver).
* If there are no modules, we expect 2 structures (head, driver)
* If there is 1 module, we expect 3 structures (head, module,
* driver)
* If there is more than 1 module, we expect 3 structures
* (head, modules).
*/
count = pstat_getstream(psfstream, sizeof(struct pst_stream), 3, 0
,&(psf.psf_fid));
if (count > 0) {
if ((psfstream[0].val.head.pst_hi_fileid ==
psf.psf_hi_fileid) &&
(psfstream[0].val.head.pst_lo_fileid ==
psf.psf_lo_fileid) &&
(psfstream[0].val.head.pst_hi_nodeid ==
psf.psf_hi_nodeid) &&
(psfstream[0].val.head.pst_lo_nodeid ==
psf.psf_lo_nodeid)) {
printf("Success\n");
printf("The major number of the stream is %lld\n",
psfstream[0].val.head.pst_dev_major);
} else {
printf("State changed\n");
}
} else {
perror("pstat_getstream()");
}
} else {
perror("pstat_getfile2");
}
close(fd);
}
Example 11
Acquire detailed information about a socket.
main()
{
struct pst_fileinfo2 psf;
struct pst_socket psfsocket;
int rv, count, fd;
(void)memset(&psf,0,sizeof(psf));
(void)memset(&psfsocket,0,sizeof(psfsocket));
fd = socket(AF_INET, SOCK_STREAM, 0);
rv = pstat_getfile2(&psf, sizeof(psf), 0, fd, getpid());
if (rv == 1) {
/*
* Ask for socket information.
*/
count = pstat_getsocket(&psfsocket, sizeof(struct pst_socket),
&(psf.psf_fid));
if (count == 1) {
if ((psfsocket.pst_hi_fileid == psf.psf_hi_fileid) &&
(psfsocket.pst_lo_fileid == psf.psf_lo_fileid) &&
(psfsocket.pst_hi_nodeid == psf.psf_hi_nodeid) &&
(psfsocket.pst_lo_nodeid == psf.psf_lo_nodeid)) {
printf("Success\n");
printf("The type of socket is %u, should be %d\n",
psfsocket.pst_type, PS_SOCK_STREAM);
} else {
printf("State changed\n");
}
} else {
perror("pstat_getsocket()");
}
} else {
perror("pstat_getfile2");
}
close(fd);
}
Example 12
Acquire path name information about an open file.
main()
{
struct pst_fileinfo2 psf;
char filename[20];
int rv, count, fd;
(void)memset(&psf,0,sizeof(psf));
(void)memset(filename,0,sizeof(filename));
fd = open("/etc/passwd", O_RDONLY);
rv = pstat_getfile2(&psf, sizeof(psf), 0, fd, getpid());
if (rv == 1) {
/*
* Ask for path name information.
*/
count = pstat_getpathname(filename, 20, &(psf.psf_fid));
if (count > 0) {
if (strncmp("/etc/passwd", filename, count) == 0) {
printf("Success\n");
} else {
printf("Error encountered\n");
}
} else if (count == 0) {
printf("path name not found in system cache\n");
} else if ((count == -1) && (errno == EOVERFLOW)){
perror("pstat_getpathname(): input buffer too small");
}
} else {
perror("pstat_getfile2");
}
close(fd);
}
Example 13
Acquire multiple path name information for a file system.
main()
{
struct pst_fileinfo2 psf;
struct pst_mpathnode mpath_buf[20];
int i, rv, count, fd;
pid_t target;
(void)memset(&psf,0,sizeof(psf));
(void)memset(&mpath_buf,0,sizeof(mpath_buf));
target = getpid();
fd = open("/etc/passwd", O_RDONLY);
rv = pstat_getfile2(&psf, sizeof(psf), 0, fd, target);
if (rv == 1) {
/*
* Ask for multiple path name information.
*/
count = pstat_getmpathname(mpath_buf, sizeof(struct pst_mpathnode),
20, 0, &(psf.psf_id.psf_fsid));
if (count > 0) {
for (i = 0; i < count; i++) {
printf("component %d: %s\n",
i, mpath_buf[i].psr_name);
}
} else if (count == 0) {
printf("path names not found in system cache\n");
} else {
perror("pstat_getmpathname()");
}
} else {
perror("pstat_getfile2");
}
close(fd);
}
Example 14
Acquire the extended command line for the process.
main()
{
char cmdline[1024];
int rv;
(void)memset(&cmdline,0,sizeof(cmdline));
rv = pstat_getcommandline(cmdline, sizeof(cmdline),1, getpid());
if (rv < 0) {
perror("pstat_getcommandline()");
} else {
printf("Command line : %s \n",cmdline);
}
}
WARNINGS
Some parts of the program status may not get updated when a process
becomes a zombie. An example is the CPU percentage, which is not
updated because the process is not expected to be scheduled to run
after entering the zombie state.
AUTHOR
The routines were developed by HP.
FILES
pstat data structures and identifiers
pstat data structures and identifiers
use these header files to infer information about the usage of pstat
functions that have their own manpages (see the subsection).
SEE ALSOpstat_getlocality(2),
iostat(1), ps(1), top(1), vmstat(1), coreadm(1M), crashconf(1M),
fuser(1M), vgdisplay(1M), coreadm(2), crashconf(2), errno(2),
mq_open(2), msgctl(2), sem_open(2), semctl(2), shmctl(2), stat(2),
sysconf(2), fileno(3S), privileges(5), thread_safety(5).
pstat(2)