pstat(2) System Calls Manual pstat(2)
NAME
pstat: pstat_getcommandline(), pstat_getcrashdev(), pstat_getcrashinfo(), 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_getprocessor(), pstat_getprocvm(), pstat_getpsem(), pstat_getpset(), pstat_get-
sem(), pstat_getshm(), pstat_getsocket(), pstat_getstable(), pstat_getstatic(), 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_getlocality(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 corresponding 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 communicate 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 special 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 neces-
sarily correspond directly to a kernel object. For instance, the dynamic context represents a collection of some of the dynamic system-
wide information 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
particular 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.
Applications may need to be aware of potential consistency issues in data returned by pstat due to this. There are two senses of data con-
sistency 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. However, since pstat often reports on kernel data that are rapidly
changing 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 function 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 dif-
ferent 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 backwards source and object compatibility for programs written using
the pstat interfaces. Three rules are followed to allow existing applications to continue to execute from release to release of the oper-
ating system.
o New data for a context are added to the end of that context's data structure.
o Old, obsolete data members are deleted from the data structure.
o 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 continue to execute on that and future releases. Note that the reverse
is not true: a program using the pstat interfaces compiled on, for example, HP-UX 11i Version 2 will not necessarily work on HP-UX 11i Ver-
sion 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
programming models may differ in size. To accomodate applications written in standard C and extended ANSI C that must still use the ILP32
programming 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
application 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 applications 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 func-
tions 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
attempting to get information on message queues, semaphores or processes which are in a different compartment. See compartments(5) for
more information 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 characters 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 config-
ured 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 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 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 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
context for each open file descriptor. For each instance requested, up to a maximum of elemsize bytes of data is returned in the struc-
tures 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 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 elements. 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 iden-
tifies 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 meaningful 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 tunables. 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 description.
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 available at buf to be filled in. The index parameter specifies the start-
ing index within the context of logical volumes. As a shortcut, information for a single logical volume can be obtained by setting elem-
count 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 param-
eter specifies 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 elemcount entries of LWP info within the process specified by pid are
returned.
As a shortcut, information about a single LWP can be obtained by setting 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 specified 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 maximum 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 parame-
ter 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
component 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 concatenating 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 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 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 parame-
ter 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 lim-
ited 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 available 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 parame-
ter 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 processor 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 struc-
tures 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 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 description.
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 con-
tained 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 cur-
rently 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 elem-
count 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 available at buf to be filled in. The index parameter specifies the
starting 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 parame-
ter 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 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 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 fam-
ily.
Note
The socket state in the field of is deprecated and will be obsoleted/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 associated 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 available at buf to be filled in. The moduleskip parameter indicates
the number of modules to skip before returning information about any modules. Head information is returned for every call. The fid param-
eter 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 structures 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)
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 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 characters 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 pro-
vide. 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 purpose it is to indicate whether other fields in that data
structure contain 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 structures 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 appli-
cation 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 kernel. 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 structure, 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 determined, the particular fields of that structure that do not contain valid
data can be determined as follows. Please note that all preceding structures were filled in by the kernel, and fields from those struc-
tures need not be checked in this manner.
Such fields can be determined using the validity macros explicitly defined for the corresponding data structure and the correspond-
ing 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 validity macro with its corresponding validity vector evaluates to the field corre-
sponding 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 corresponding data structure.
The other fields within that particular 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
", pst.page_size);
else
perror("pstat_getstatic");
}
Example 2
Get information about all processors, first obtaining number of processor 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
",
execs, i);
}
(void)printf("total execs for the system were %llu
",
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
",
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
",
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
",
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
",
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
", 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 key size
");
for (i = 0; i < num_shm; i++) {
/* skip inactive segments */
if (!(pss[i].psh_flags & PS_SHM_ALLOC))
continue;
(void)printf("%lld %#llx %llu
",
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
", 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 FSid %llx:%llx fileid %lld
",
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...
");
}
}
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
");
}
else {
printf("State changed
");
}
}
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
");
printf("The major number of the stream is %lld
",
psfstream[0].val.head.pst_dev_major);
} else {
printf("State changed
");
}
} 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
");
printf("The type of socket is %u, should be %d
",
psfsocket.pst_type, PS_SOCK_STREAM);
} else {
printf("State changed
");
}
} 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
");
} else {
printf("Error encountered
");
}
} else if (count == 0) {
printf("path name not found in system cache
");
} 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
",
i, mpath_buf[i].psr_name);
}
} else if (count == 0) {
printf("path names not found in system cache
");
} 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
",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 ALSO
pstat_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)