pstat(2)

NAME

pstat: pstat_getcommandline(), pstat_getcrashdev(), pstat_getcrashinfo(), pstat_getdisk(), pstat_getio(), pstat_getdynamic(), pstat_getfile2(), 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_getsem(), 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 NAME is described in its own PSTAT FUNCTION section below.

The functions pstat_getlocality() and pstat_getproclocality() are described in a separate manpage; see pstat_getlocality(2).

DESCRIPTION

The HP-UX pstat 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, pstat_get*(), and corresponding structures, pst_*, 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 <sys/pstat.h> and <sys/pstat/*_pstat_body.h>. Do not use these header files to infer information about the usage of pstat functions that have their own manpages (see the SYNOPSIS Remarks 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 necessarily 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 consistency 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 pstat_get*() 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 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 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 operating system.

New data for a context are added to the end of that context's data structure.
Old, obsolete data members are not 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, sizeof(struct pst_processor) for the Processor context) as the elemsize parameter will continue to execute on future operating system releases without recompilation, even those that have larger context 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 Version 1.

Programming Model Considerations

While the pstat functional interfaces, pstat_get*(), 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 pst_* 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 -D_PSTAT64 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 -D_PSTAT64 compiler flag is deprecated. 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 -D_PSTAT64. The pstat functions pstat_getlwp(), pstat_getcrashinfo(), and pstat_getlocality() 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 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 COMMALLOWED 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

pstat_getcommandline() - get command line of a process

Synopsis

#include <sys/pstat.h>

int pstat_getcommandline(
char *buf,
size_t elemsize,
size_t elemcount,
int pid"
);

Description

pstat_getcommandline() returns the command line of the process specified in the pid parameter. Up to a maximum of elemsize-1 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 1.

PSTAT FUNCTION

Name

pstat_getcrashdev() - get information for a crash dump device

Synopsis

#include <sys/pstat.h>

int pstat_getcrashdev(
struct pst_crashdev *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getcrashdev() 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 elemsize bytes of data is returned in the pst_crashdev structures pointed to by buf. The elemcount parameter specifies the number of pst_crashdev 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

pstat_getcrashinfo() - get information for a system's crash dump configuration

Synopsis

#include <sys/pstat.h>

int pstat_getcrashinfo(
struct pst_crashinfo *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getcrashinfo() returns information about the system's crash dump configuration. Up to a maximum of elemsize bytes of data is returned in the pst_crashinfo structure pointed to by buf. The elemcount parameter must be 1. The index parameter must be 0.

PSTAT FUNCTION

Name

pstat_getdisk() - get information for a disk

Synopsis

#include <sys/pstat.h>

int pstat_getdisk(
struct pst_diskinfo *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getdisk() 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 pst_diskinfo structures pointed to by buf. The elemcount parameter specifies the number of pst_diskinfo 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 psd_status in the pst_diskinfo structure to tell if the disk is opened (1) or closed (0).

PSTAT FUNCTION

Name

pstat_getio() - get information for an IO Object

Synopsis

#include <sys/pstat.h>

int pstat_getio(
struct pst_ioinfo *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getio() 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 pst_ioinfo structures pointed to by buf. The elemcount parameter specifies the number of pst_ioinfo 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 psi_status in the pst_ioinfo structure to tell if the IO object is opened (1) or closed (0).

PSTAT FUNCTION

Name

pstat_getdynamic() - get dynamic information about the system

Synopsis

#include <sys/pstat.h>

int pstat_getdynamic(
struct pst_dynamic *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getdynamic() 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 pst_dynamic structure pointed to by buf. The elemcount parameter must be 1. The index parameter must be 0.

PSTAT FUNCTION

Name

pstat_getfile2() - get information for an open file of a process

Synopsis

#include <sys/pstat.h>

int pstat_getfile2(
struct pst_fileinfo2 *buf,
size_t elemsize,
size_t elemcount,
int index,
pid_t pid
);

Description

pstat_getfile2() 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 pst_fileinfo2 structures pointed to by buf. The elemcount parameter specifies the number of pst_fileinfo2 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 0 and setting the index to the file descriptor number.

The pst_fileinfo2 structure contains both a psf_offset and psf_offset64 element. The psf_offset element can correctly store a 32-bit value, whereas the psf_offset64 element can store a 64-bit value. pstat_getfile2() will fill in both psf_offset and psf_offset64 if the value can be correctly stored in both elements. If the offset is too large to be correctly stored in psf_offset, then psf_offset will contain a -1. No error will be set in this case.

PSTAT FUNCTION

Name

pstat_getfiledetails() - get detailed information for an open file

Synopsis

#include <sys/pstat.h>

int pstat_getfiledetails(
struct pst_filedetails *buf,
size_t elemsize,
struct pst_fid *fid
);

Description

pstat_getfiledetails() 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 pst_filedetails structure pointed to by buf. The fid parameter uniquely identifies the file. This fid is obtained from calls to pstat_getfile2(), pstat_getproc() or pstat_getprocvm(). The pst_filedetails 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 not done a setuid or a setgid.

The structure members psfd_mode, psfd_ino, psfd_dev, psfd_uid, psfd_gid, psfd_atime, psfd_mtime, psfd_ctime will have meaningful values for regular files, character or block special files, and pipes. The value of the member psfd_nlink will be set to number of links to the file. The member psfd_rdev will have meaningful value for character or block special files, while the psfd_size is valid for regular files. The members psfd_hi_fileid, psfd_lo_fileid, psfd_hi_nodeid, and psfd_lo_nodeid are unique IDs representing the open file. These IDs together are used to match the corresponding IDs returned from the pstat_getfile2(). This call does not work for sockets other than the AF_UNIX family type.

PSTAT FUNCTION

Name

pstat_getipc() - get information about the System V IPC subsystem

Synopsis

#include <sys/pstat.h>

int pstat_getipc(
struct pst_ipcinfo *buf,
size_t elemsize,
size_t elemcount,
int index
);

PSTAT FUNCTION

Name

pstat_getlwp() - get information for a thread or LWP in a process

Synopsis

#include <sys/pstat.h>

int pstat_getlwp(
struct lwp_status *buf,
size_t elemsize,
size_t elemcount,
int index,
pid_t pid
);

Description

pstat_getlwp() 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 lwp_status structure pointed to by buf. The elemcount parameter specifies the number of lwp_status structures that are available at buf to be filled in. The index parameter specifies the starting index within the context of LWPs in a process.

If pid is set to -1 and elemcount is greater than 0, elemcount entries of system LWP information are returned to the caller program.

If pid is greater than or equal to 0 and elemcount is greater than 0, 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 0 and setting index to the TID (Thread ID) of that LWP within its process.

PSTAT FUNCTION

Name

pstat_getmpathname() - get entries from system cache of recently looked-up names

Synopsis

#include <sys/pstat.h>

int pstat_getmpathname(
struct pst_mpathnode *buf,
size_t elemsize,
size_t elemcount,
int index,
struct psfsid *fid
);

Description

pstat_getmpathname() returns the entries from the system cache of recent names looked up (DNLC) for a specified file system, in buf. The fsid parameter uniquely identifies the file system. This fsid should be the psf_fsid field of a psfileid structure obtained from calls to pstat_getfile2(), pstat_getproc(), or pstat_getprocvm(). 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 0 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 pst_mpathnode structures pointed to by buf. The pst_mpathnode structure contains the following members:

_T_ULONG_T psr_idx;  
struct psfileid   psr_file;  
struct psfileid   psr_parent;  
char       psr_name[PS_SEGMENTNAME_SZ];  

psr_idx is the current index of an entry into the chain of DNLC entries for the file system. psr_idx+1 can be passed on to another pstat_getmpathname() call as the index parameter to obtain the entries starting after the last psr_idx. psr_file is the file the current entry describes and psr_parent is the parent of this file. psr_name is the NULL-terminated path name component for the current entry.

Reverse path name lookup can be performed by searching the entries for one that has a psr_file member equal to the psr_parent member of the current entry. This is done until an entry with a NULL psr_parent 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 psr_name 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 -1 is returned and errno is set indicating the cause of the failure.

PSTAT FUNCTION

Name

pstat_getmsg() - get information for a System V message queue

Synopsis

#include <sys/pstat.h>

int pstat_getmsg(
struct pst_msginfo *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getmsg() 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 pst_msginfo structures pointed to by buf. The elemcount parameter specifies the number of pst_msginfo 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 0 and setting index to the msqid of that message queue.

PSTAT FUNCTION

Name

pstat_getnode() - get information about an SCA system node

Synopsis

#include <sys/pstat.h>

int pstat_getnode(
struct pst_node *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getnode() 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 pst_node structure pointed to by buf. The elemcount parameter specifies the number of pst_node 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

pstat_getpathname() - get the full path name of an open file

Synopsis

#include <sys/pstat.h>

int pstat_getpathname(
char *buf,
size_t elemcount,
struct pst_fid *fid
);

Description

pstat_getpathname() 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 pstat_getfile2(), pstat_getproc(), or pstat_getprocvm(). The value of elemcount should be at least one greater than the length of the path name to be returned. The PATH_MAX 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 pstat_getfiledetails() 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, 0 is returned and errno is not set. On other failures, the value of -1 is returned and errno is set indicating the cause of the failure. This call does not work for sockets.

PSTAT FUNCTION

Name

pstat_getpmq() - get information for a POSIX message queue

Synopsis

#include <sys/pstat.h>

int pstat_getpmq(
struct pst_pmqinfo *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getpmq() 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 pst_pmqinfo structures pointed to by buf. The elemcount parameter specifies the number of pst_pmqinfo structures that are available at buf to be filled in. The index parameter specifies the starting index within the context of POSIX message queues.

PSTAT FUNCTION

Name

pstat_getproc() - get information for a process

Synopsis

#include <sys/pstat.h>

int pstat_getproc(
struct pst_status *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getproc() 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 pst_status structures pointed to by buf. The elemcount parameter specifies the number of pst_status 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 0 and setting index to the PID of that process.

PSTAT FUNCTION

Name

pstat_getprocessor() - get information for a processor

Synopsis

#include <sys/pstat.h>

int pstat_getprocessor(
struct pst_processor *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getprocessor() returns information specific to a particular processor (the only processor on a uniprocessor system). There is one instance of this context for each processor on the system. For each instance requested, up to a maximum of elemsize bytes of data is returned in the pst_processor structures pointed to by buf. The elemcount parameter specifies the number of pst_processor 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

int pstat_getsocket(
struct pst_socket *buf,
size_t elemsize,
struct pst_fid *fid
);

Synopsis

#include <sys/pstat.h>

int pstat_getstream(
struct pst_stream *buf,
size_t elemsize,
size_t elemcount,
int moduleskip,
struct pst_fid *fid
);

Description

pstat_getstream() 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 pst_stream structures pointed to by buf. The elemcount parameter specifies the number of pst_stream 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 parameter uniquely identifies the file. This ID is obtained from calls to pstat_getfile2().

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 -1 is returned and errno is set indicating the cause of the failure.

The use of this function is limited to UID 0 or an effective UID match. See pstat_getfiledetails() for the definition of effective UID match.

The type field can be PS_STR_HEAD,PS_STR_MODULE or PS_STR_DRIVER. The union val in pst_stream structure will represent the structures head, module, or driver in the respective cases. If the flag PS_STR_ISACLONE is set in pst_flag for head, the field pst_dev_seq in head represents the clone driver sequence number for the stream.

PSTAT FUNCTION

Name

pstat_getswap() - get information for a swap area

Synopsis

#include <sys/pstat.h>

int pstat_getswap(
struct pst_swapinfo *buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getswap() 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 pst_swapinfo structures pointed to by buf. The elemcount parameter specifies the number of pst_swapinfo 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

pstat_getvminfo() - get information about the virtual memory subsystem

Synopsis

#include <sys/pstat.h>

int pstat_getvminfo(
structpst_vminfo*"buf,
size_t elemsize,
size_t elemcount,
int index
);

Description

pstat_getvminfo() 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 pst_vminfo structure pointed to by buf. The elemcount parameter must be 1. The index parameter must be 0.

RETURN VALUE

Upon successful completion, the various pstat functions (for example, pstat_getprocessor()) return the number of instances, which could be 0, filled in at the address provided by the user. pstat_getcommandline(), however, returns the number of characters of the process command line returned at the address provided by the user and pstat_getpathname() returns the number of characters of the file path name returned at the address provided by the user. Otherwise, a value of -1 is returned and errno 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 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 EOVERFLOW 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 application must infer how many structures the kernel has filled in, by the following method.

To determine which structure resulted in the error return with EOVERFLOW 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 not equal to -1 is the structure that caused the error return with EOVERFLOW 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 pstat_getdynamic(), an error return with EOVERFLOW set means that the only structure requested is the structure that caused the error return with EOVERFLOW.

Once the structure that caused the error return with EOVERFLOW 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 structures need not be checked in this manner.

Such fields can be determined using the validity macros explicitly defined for the corresponding pst_* data structure and the corresponding validity vector for that particular structure. These validity macros correspond to one specific field within the given pst_* data structure. If the bitwise AND of a particular validity macro with its corresponding validity vector evaluates to 0, 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 corresponding pst_* data structure. The other fields within that particular structure need not be checked using this method.

ERRORS

If a pstat function fails, errno is set to one of the following values. If an underlying function fails, errno may be set to a value not specified here; see errno(2) for such errors.

EACCES

The UID is not 0 (superuser) and the effective UID does not match for pstat_getfiledetails(), pstat_getsocket(), pstat_getstream(), or pstat_getpathname(). See pstat_getfiledetails() for the definition of effective UID match.

EFAULT

buf or fid points to an invalid address.

EINTR

For pstat_getsocket() the operation was terminated due to the receipt of a signal; no data was transferred.

EINVAL

For pstat_getfile2(), pstat_getlv(), pstat_getmsg(), pstat_getproc(), pstat_getprocvm(), pstat_getpset(), pstat_getsem(), or pstat_getshm(), elemcount was not 0, and index was less than 0.

EINVAL

elemsize is less than or equal to 0 or elemsize is larger than the size of the associated data structure. For example, elemsize is greater than sizeof(structpst_processor) for pstat_getprocessor().

EINVAL

For pstat_getcrashinfo(), pstat_getdynamic(), pstat_getipc(), pstat_getstable(), pstat_getstatic(), or pstat_getvminfo(), elemcount is not 1 or index is not 0.

EINVAL

For pstat_getcrashdev(), pstat_getdisk(), pstat_getnode(), pstat_getpmq(), pstat_getprocessor(), pstat_getpsem(), or pstat_getswap(), elemcount is not greater than or equal to 1 or index is not greater than or equal to 0.

EINVAL

For pstat_getnode(), index is not a valid logical node ID.

EINVAL

For pstat_getpathname(), elemcount is less than or equal to 0.

EINVAL

pstat_getfiledetails() was called for a socket other than the AF_UNIX family, or pstat_getpathname() was called for a socket.

EINVAL

pstat_getsocket() was called for a file that is not of type socket.

EINVAL

pstat_getcommandline() was called with pid less than 0 or elemcount not equal to 1.

ENOBUFS

For pstat_getsocket(), the operation was terminated due to unavailability of buffer space.

ENOENT

For pstat_getfile2(), pstat_getfiledetails(), pstat_getpathname(), pstat_getsocket(), or pstat_getstream(), the file was not found, or it was closed.

For pstat_getmpathname(), the specified file system was not found or the file system did not have DNLC entries.

ENOSTR

pstat_getstream() was called for a file that is neither a stream nor a stream-based pipe or socket.

ENOSYS

The requested pstat function is not implemented or not configured in the system.

EOVERFLOW

The offset element is too large to store into the structure pointed to by the buf parameter.

EOVERFLOW

For pstat_getfiledetails(), a value to be stored would overflow one of the members of the pst_filedetails structure. The psfd_valid member indicates the field that overflowed.

EOVERFLOW

For pstat_getpathname(), the elemcount parameter is not 1 greater than the length of the path name to be returned.

ESRCH

The process in question was not found or was exiting. For pstat_getlv(), pstat_getmsg(), pstat_getproc(), pstat_getprocvm(), pstat_getpset(), pstat_getsem(), or pstat_getshm(), elemcount was 0, specifying the single-item short-cut, and no item matched the selection criteria in index. For example, PID for pstat_getproc().

EXAMPLES

All of these examples are compiled with the _PSTAT64 flag. All examples have the following prolog. The define of _PSTAT64 is placed before the inclusion of the <sys/pstat.h> 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 pstat_getstatic().

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 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\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 EOVERFLOW 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 EOVERFLOW, 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 pstat_getproc().

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 pstat_get*() routines were developed by HP.

FILES

/usr/include/sys/pstat.h: pstat data structures and identifiers
/usr/include/sys/pstat/*_pstat_body.h: pstat data structures and identifiers

Do not use these header files to infer information about the usage of pstat functions that have their own manpages (see the SYNOPSIS Remarks subsection).

pstat(2)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Remarks

DESCRIPTION

Summary of Available Contexts

The pstat Context

The pstat Index

Data Consistency

Backward Compatibility

Programming Model Considerations

Security Restrictions

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name

Synopsis

Description

PSTAT FUNCTION

Name