pstat(2) pstat(2)
NAME [Toc] [Back]
pstat(), pstat_getcommandline(), pstat_getcrashdev(),
pstat_getcrashinfo(), pstat_getdisk(), pstat_getdynamic(),
pstat_getfile(), pstat_getfile2(), pstat_getfiledetails(),
pstat_getipc(), pstat_getlocality(), pstat_getlv(), pstat_getlwp(),
pstat_getmpathname(), pstat_getmsg(), pstat_getnode(),
pstat_getpathname(), pstat_getpmq(), pstat_getproc(),
pstat_getprocessor(), pstat_getproclocality(), pstat_getprocvm(),
pstat_getpsem(), pstat_getpset(), pstat_getsem(), pstat_getshm(),
pstat_getsocket(), pstat_getstable(), pstat_getstatic(),
pstat_getstream(), pstat_getswap(), pstat_getvminfo() - get system
information
SYNOPSIS [Toc] [Back]
#include <sys/param.h>
#include <sys/pstat.h>
int pstat(
int, union pstun, size_t, size_t, int
);
int pstat_getcommandline(
char *buf, size_t elemsize, size_t elemcount,
int pid
);
int pstat_getcrashdev(
struct pst_crashdev *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getcrashinfo(
struct pst_crashinfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getdisk(
struct pst_diskinfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getdynamic(
struct pst_dynamic *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getfile(
struct pst_fileinfo *buf, size_t elemsize, size_t elemcount,
int index
);
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
int pstat_getfile2(
struct pst_fileinfo2 *buf, size_t elemsize, size_t elemcount,
int index, pid_t pid
);
int pstat_getfiledetails(
struct pst_filedetails *buf, size_t elemsize, struct pst_fid *fid
);
int pstat_getipc(
struct pst_ipcinfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getlv(
struct pst_lvinfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getlwp(
struct lwp_status *buf, size_t elemsize, size_t elemcount,
int index, pid_t pid
);
int pstat_getmpathname(
struct pst_mpathnode *buf, size_t elemsize, size_t elemcount,
int index, struct psfsid *fid
);
int pstat_getmsg(
struct pst_msginfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getnode(
struct pst_node *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getpathname(
char *buf, size_t elemcount, struct pst_fid *fid
);
int pstat_getpmq(
struct pst_pmqinfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getproc(
struct pst_status *buf, size_t elemsize, size_t elemcount,
int index
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
);
int pstat_getprocessor(
struct pst_processor *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getprocvm(
struct pst_vm_status *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getpsem(
struct pst_pseminfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getpset(
struct pst_pset *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getsem(
struct pst_seminfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getshm(
struct pst_shminfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getsocket(
struct pst_socket *buf, size_t elemsize, struct pst_fid *fid
);
int pstat_getstable(
struct pst_stable *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getstatic(
struct pst_static *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getstream(
struct pst_stream *buf, size_t elemsize, size_t elemcount,
int moduleskip, struct pst_fid *fid
);
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
int pstat_getswap(
struct pst_swapinfo *buf, size_t elemsize, size_t elemcount,
int index
);
int pstat_getvminfo(
struct pst_vminfo *buf, size_t elemsize, size_t elemcount,
int index
);
Remarks [Toc] [Back]
The underlying function pstat() is provided for backward compatibility.
Use of the pstat_get*() wrapper functions is recommended (for example,
pstat_getproc()) to avoid the polymorphic typing of the union pstun
parameter.
The functions pstat_getlocality() and pstat_getproclocality() have
their own manpages. See pstat_getlocality(2) and
pstat_getproclocality(2).
DESCRIPTION [Toc] [Back]
The pstat functions return information about various system contexts.
The contents of the various associated data structures, structs
pst_crashdev, pst_crashinfo, pst_diskinfo, pst_dynamic, pst_fileinfo,
pst_fileinfo2, pst_filedetails, pst_ipcinfo, pst_lvinfo,
pst_mpathnode, pst_msginfo, pst_node, pst_pmqinfo, pst_processor,
pst_pseminfo, pst_pset, pst_seminfo, pst_shminfo, pst_stable,
pst_static, pst_status, pst_socket, pst_stream, pst_swapinfo,
pst_vminfo, and pst_vm_status, are declared in the header files
<sys/pstat.h>, and <sys/pstat/*_pstat_body.h>. The headers contain
descriptions of the fields of each of the context data structures.
Summary of Available Contexts [Toc] [Back]
The pstat routines support the following contexts of information.
Detailed descriptions of each routine follow.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
_________________________________________________________________________
| | | |Short
Context |Struct |Routine |Instances |Cut
_____________|______________|_____________________|________________|_____
Static |pst_static |pstat_getstatic() |1 |
Dynamic |pst_dynamic |pstat_getdynamic() |1 |
VM |pst_vminfo |pstat_getvminfo() |1 |
IPC |pst_ipcinfo |pstat_getipc() |1 |
Stable Store |pst_stable |pstat_getstable() |1 |
Crash Dumps |pst_crashinfo |pstat_getcrashinfo() |1 |
_____________|______________|_____________________|________________|_____
Processor |pst_processor |pstat_getprocessor() |1 per processor |
Disk |pst_diskinfo |pstat_getdisk() |1 per disk |
Swap |pst_swapinfo |pstat_getswap() |1 per swap area |
Dump Areas |pst_crashdev |pstat_getcrashdev() |1 per dump area |
Node |pst_node |pstat_getnode() |1 per node |
Locality |pst_locality |pstat_getlocality() |1 per locality |
_____________|______________|_____________________|________________|_____
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
_____________________________________________________________________________
| | | |Short
Context |Struct |Routine |Instances |Cut
____________|______________|_____________________|_____________________|_____
Commandline |char * |pstat_ |1 per process |yes
| |getcommandline() | |
Process |pst_status |pstat_getproc() |1 per process |yes
LW Process |lwp_status |pstat_getlwp() |1 per lwp/thread |yes
Process VM |pst_vm_status |pstat_getprocvm() |1 per process region |yes
Process |pst_proc_ |pstat_ |1 per process loc. |yes
Locality | locality |getproclocality() | |
LVM Vol |pst_lvinfo |pstat_getlv() |1 per lvol |yes
Sema Set |pst_seminfo |pstat_getsem() |1 per sem set |yes
Msg Queue |pst_msginfo |pstat_getmsg() |1 per msg queue |yes
Shared Mem |pst_shminfo |pstat_getshm() |1 per shm seg |yes
Proc Set |pst_pset |pstat_getpset() |1 per proc set |yes
P-Sema Set |pst_pseminfo |pstat_getpsem() |1 per sema |no
P-Msg Queue |pst_pmqinfo |pstat_getpmq() |1 per msg queue |no
____________|______________|_____________________|_____________________|_____
Open File |pst_fileinfo |pstat_getfile() |1 per file |yes
Open File |pst_fileinfo2 |pstat_getfile2() |1 per file |yes
____________|______________|_____________________|_____________________|_____
Open File |pst_ |pstat_ |1 per file/call |
|filedetails |getfiledetails() | |
Open Socket |pst_socket |pstat_getsocket() |1 per socket/call |
Open Stream |pst_stream |pstat_getstream() |1 per stream/call |
Open File |char * |pstat_getpathname() |1 per file/call |
____________|______________|_____________________|_____________________|_____
DNLC |pst_mpathnode |pstat_getmpathname() |1 per DNLC entry |
____________|______________|_____________________|_____________________|_____
Wrapper Function Descriptions [Toc] [Back]
pstat_getcommandline()
Returns the commandline of the process specified in the
pid parameter. Up to a maximum of elemsize - 1 bytes
are returned in the buffer buf, if the elemsize is less
than or equal to the size of the process commandline.
If the elemsize is greater than the size of process
commandline, only the available number of bytes are
returned. Up to a maximum of 1020 characters of the
process commandline is stored. The elemcount parameter
has to be one.
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, data, up to a maximum of elemsize
bytes, is returned in the structs pst_crashdev pointed
to by buf. The elemcount parameter specifies the
number of structs pst_crashdev that are available at
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
buf to be filled in. The index parameter specifies the
starting index within the context of crash dump
devices.
pstat_getcrashinfo()
Returns information about the system's crash dump
configuration. Data, up to a maximum of elemsize
bytes, are returned in the struct pst_crashinfo pointed
to by buf. The elemcount parameter must be 1. The
index parameter must be 0.
pstat_getdisk()
Returns information specific to a particular disk.
There is one instance of this context for each disk
configured into the system. For each instance
requested, data, up to a maximum of elemsize bytes, is
returned in the structs pst_diskinfo pointed to by buf.
The elemcount parameter specifies the number of structs
pst_diskinfo that are available at buf to be filled in.
The index parameter specifies the starting index within
the context of disks.
pstat_getdynamic()
Returns dynamic information about the system. There is
one global instance of this context. Data, up to a
maximum of elemsize bytes, is returned in the struct
pst_dynamic pointed to by buf. The elemcount parameter
must be 1. The index parameter must be 0.
pstat_getfile()
This call is now obsolete and is provided for backward
compatibility only. Use of pstat_getfile2() call is
recommended. 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, data, up to a maximum of elemsize
bytes, is returned in the structs pst_fileinfo pointed
to by buf. The elemcount parameter specifies the
number of structs pst_fileinfo 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 a 32-bit quantity constructed
of the pst_idx field of the 'owning' process, obtained
via pstat_getproc(), described above, as the most
significant 16 bits, and the index of open files within
the process as the least significant 16 bits. Example:
index = ((pst_idx << 16) | (file_index & 0xffff));
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
As a shortcut, information for a single file within the
specified process may be obtained by setting elemcount
to zero and setting the least significant 16 bits to
the file descriptor number (the most significant 16
bits are still set to the pst_idx field from the
pst_status structure for the process).
The pst_fileinfo 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_getfile() 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_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, data, up
to a maximum of elemsize bytes, is returned in the
structs pst_fileinfo2 pointed to by buf. The elemcount
parameter specifies the number of structs pst_fileinfo2
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 may be obtained by setting elemcount
to zero 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_getfiledetails()
Returns detailed information specific to a particular
open file. For a specified opened file, there is only
one instance of this context. For each call, data, up
to a maximum of elemsize bytes, is returned in the
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
struct pst_filedetails pointed to by buf. The fid
parameter uniquely identifies the file. This fid is
obtained from calls to pstat_getfile(),
pstat_getproc(), or pstat_getprocvm(). The
pst_filedetails structure contains information
equivalent to the stat(2) call. Use of this function is
limited to UID==0 or effective UID match. 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
set[u/g]id.
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 opened
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 AF_UNIX
family type.
pstat_getipc()
Returns information about 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. Data, up to a maximum of elemsize bytes, is
returned in the struct pst_ipcinfo pointed to by buf.
The elemcount parameter must be 1. The index parameter
must be 0.
pstat_getlocality()
Returns information specific to a particular locality.
See the pstat_getlocality(2) manpage.
pstat_getlv()
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, data, up to a maximum of elemsize
bytes, is returned in the structs pst_lvinfo pointed to
by buf. The elemcount parameter specifies the number
of structs pst_lvinfo that are available at buf to be
filled in. The index parameter specifies the starting
index within the context of logical volumes. As a
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
shortcut, information for a single logical volume may
be obtained by setting elemcount to zero and setting
index to the dev_t of that logical volume.
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, data, up to a
maximum of elemsize bytes, is returned in the struct
lwp_status pointed to by buf. The elemcount parameter
specifies the number of struct lwp_status 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 zero and setting index
to the TID (Thread ID) of that LWP within its process.
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_getfile(), 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 filesystem. The elemcount
parameter specifies the number of DNLC entries to be
returned. Typically, the index parameter will be
specified as zero and the elemcount parameter will be
high enough to obtain all the entries of the specified
file system. For each call, data, up to a maximum of
elemsize bytes, is returned in the structs
pst_mpathnode 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;
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
char psr_name[PS_SEGMENTNAME_SZ];
psr_idx is the current index of an entry into the chain
of DNLC entries for the filesystem. 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 pathname
component for the current entry.
Reverse pathname 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 pathname 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
pathname can then be formed by concatenating the
pathname to the mount point of the file system.
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_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, data, up to a maximum of
elemsize bytes, is returned in the structs pst_msginfo
pointed to by buf. The elemcount parameter specifies
the number of structs pst_msginfo 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 may be obtained by setting elemcount to
zero and setting index to the msqid of that message
queue.
pstat_getnode()
Returns information specific about a 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 struct
pst_node pointed to by buf. The elemcount parameter
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
specifies the number of struct pst_node that are
available at buf to be filled in. The index parameter
specifies the starting logical node id that is
requested.
pstat_getpathname()
Returns the full pathname of an opened file in buf if
it is available in the system cache of recent names
looked up (DNLC). The fid parameter uniquely identifies
the opened file. This fid is obtained from calls to
pstat_getfile(), pstat_getfile2(), pstat_getproc(), or
pstat_getprocvm(). The value of elemcount should be at
least one greater than the length of the pathname to be
returned. The PATH_MAX variable from pathconf(2) can
be used for this purpose. Use of this function is
limited to UID==0 or effective UID match. Please refer
pstat_getfiledetails() call for more information on
Effective UID match.
On success, the function returns the length of the
pathname copied starting at the location specified by
buf. If the pathname 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_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, data, up to a maximum of elemsize
bytes, is returned in the structs pst_pmqinfo pointed
to by buf. The elemcount parameter specifies the
number of structs pst_pmqinfo that are available at buf
to be filled in. The index parameter specifies the
starting index within the context of POSIX message
queues.
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,
data, up to a maximum of elemsize bytes, is returned in
the structs pst_status pointed to by buf. The
elemcount parameter specifies the number of structs
pst_status 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 may be obtained by setting
elemcount to zero and setting index to the PID of that
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
process.
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, data, up to a
maximum of elemsize bytes, is returned in the structs
pst_processor pointed to by buf. The elemcount
parameter specifies the number of structs pst_processor
that are available at buf to be filled in. The index
parameter specifies the starting index within the
context of processors.
pstat_getproclocality()
Returns information specific to a particular process's
memory placement for each locality. See the
pstat_getproclocality(2) manpage.
pstat_getprocvm()
Returns information specific to a particular process's
address space. There is one instance of this context
for each process region contained in the process'
address space. For each instance requested, data, up
to a maximum of elemsize bytes, is returned in the
struct pst_vm_status pointed to by buf. Only at most
one instance (process region) is returned for each call
to pstat_getprocvm(). The elemcount parameter
identifies the process for which address space
information is to be returned. An elemcount parameter
of zero indicates that address space information for
the currently executing process should be returned.
The index parameter specifies the starting index
(beginning with 0) within the context of process
regions for the indicated process. For example, an
index of 3 indicates the 4th process region within the
indicated process' address space. As a shortcut,
information for a specific process (other than the
currently executing one) may be obtained by setting
elemcount to the PID of that process. More information
on VM regions mapped to files can be obtained with the
pstat_getfiledetails() call.
pstat_getpsem()
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, data, up to a maximum of elemsize
bytes, is returned in the structs pst_pseminfo pointed
to by buf. The elemcount parameter specifies the
number of structs pst_pseminfo that are available at
Hewlett-Packard Company - 13 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
buf to be filled in. The index parameter specifies the
starting index within the context of POSIX named
semaphore sets.
pstat_getpset()
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, data, up to a maximum of elemsize bytes, are
returned in the struct pst_pset pointed by buf. The
elemcount parameter specifies the number of structs
pst_pset 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 may be obtained
by setting elemcount to zero and setting index to the
pset id of that processor set.
pstat_getsem()
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, data, up to a maximum of
elemsize bytes, is returned in the structs pst_seminfo
pointed to by buf. The elemcount parameter specifies
the number of structs pst_seminfo 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 may be obtained by setting elemcount to
zero and setting index to the semid of that semaphore
set.
pstat_getshm()
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, data, up to a
maximum of elemsize bytes, is returned in the structs
pst_shminfo pointed to by buf. The elemcount parameter
specifies the number of structs pst_shminfo that are
available at buf to be filled in. The index parameter
specifies the starting index within the context of
System V shared memory segments. As a shortcut,
information for a single shared memory segment may be
obtained by setting elemcount to zero and setting index
to the shmid of that shared memory segment.
pstat_getsocket()
Returns detailed information specific to a socket. For
the specified socket, there is one instance of this
Hewlett-Packard Company - 14 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
context. For each call, data, up to a maximum of
elemsize bytes, is returned in the struct pst_socket
pointed to by buf. The fid parameter uniquely
identifies the socket. This fid is obtained from calls
to pstat_getfile() or pstat_getfile2(). Use of this
function is limited to UID==0 or effective UID match.
Please refer pstat_getfiledetails() call for more
information on effective UID match.
On success, the function returns 1. On failure, the
value of -1 is returned and errno 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 pstat_getfiledetails() call. In
case of AF_UNIX sockets, the fields pst_peer_hi_nodeid
and pst_peer_lo_nodeid can be used to find the peer
socket by matching them with pst_hi_nodeid and
pst_lo_nodeid. The members pst_boundaddr and
pst_remaddr contain data of the form structsockaddr,
sockaddr_un, sockaddr_in, sockaddr_in6, etc. depending
on the socket family.
pstat_getstable()
Returns information contained in the system's stable
storage area. There is one global instance of this
context. Data, up to a maximum of elemsize bytes, is
returned in the struct pst_stable pointed to by buf.
The elemcount parameter must be 1. The index parameter
must be 0.
pstat_getstatic()
Returns information about the system. This data may
change while the system is running due to
administrative changes in the associated kernel
tunables. There is one global instance of this context.
Data, up to a maximum of elemsize bytes, is returned in
the struct pst_static pointed to by buf. The elemcount
parameter must be 1. The index parameter must be 0.
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, data, up to a maximum of
elemsize bytes, is returned in the structs pst_stream
pointed to by buf. The elemcount parameter specifies
the number of structs pst_stream 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
Hewlett-Packard Company - 15 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
parameter uniquely identifies the file. This id is
obtained from calls to pstat_getfile() or
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.
Use of this function is limited to UID==0 or effective
UID match. Please refer pstat_getfiledetails() call for
more information on 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_getswap()
Returns information specific to a particular swap area.
There is one instance of this context for each swap
area (block or filesystem) configured into the system.
For each instance requested, data, up to a maximum of
elemsize bytes, is returned in the structs pst_swapinfo
pointed to by buf. The elemcount parameter specifies
the number of structs pst_swapinfo that are available
at buf to be filled in. The index parameter specifies
the starting index within the context of swap areas.
pstat_getvminfo()
Returns information about the virtual memory subsystem.
There is one global instance of this context. Data, up
to a maximum of elemsize bytes, is returned in the
struct pst_vminfo pointed to by buf. The elemcount
parameter must be 1. The index parameter must be 0.
Notes [Toc] [Back]
A wide (64 bit) version of the pstat interfaces are available for
narrow (32 bit) applications to use. A narrow application could use
the flag -D_PSTAT64 at compile time to switch to the wide interfaces.
Using this compiler flag in a narrow application is equivalent to
using the default interfaces on a wide system.
Refer to the pstat header file to see how the various structures would
look like when the -D_PSTAT64 flag is used.
Hewlett-Packard Company - 16 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
The pstat_getlwp, pstat_getcrashinfo, pstat_getcrashdev, and
pstat_getnode interfaces are available only in the wide mode and for
applications written in standard C and extended ANSI.
RETURN VALUE [Toc] [Back]
Upon successful completion, pstat() and the various wrapper routines
(for example, pstat_getprocessor()) return the number of instances
filled in at the address buf. pstat_getcommandline(), however,
returns the number of characters of the process commandline returned
in the buf parameter. Otherwise, a value of -1 is returned and errno
is set to indicate the error.
ERRORS [Toc] [Back]
The pstat functions fail if any of the following conditions are
encountered:
[EFAULT] buf/fid points to an invalid address.
[ESRCH] Process in question is not found or exiting.
For the pstat_getproc(), pstat_getprocvm(),
pstat_getlv(), pstat_getsem(), pstat_getmsg(),
pstat_getpset(), and pstat_getshm() calls,
elemcount was 0, specifying the single-item
short-cut, and no item matched the selection
criteria in index (for example, PID for
pstat_getproc()).
[ENOENT] For calls pstat_getfile(), pstat_getfile2(),
pstat_getfiledetails(), pstat_getsocket(),
pstat_getstream(), pstat_getpathname() [ENOENT]
is returned if the file is not found, or it is
closed. For pstat_getmpathname() call, [ENOENT]
is returned if the specified file system is not
found or if the file system does not have DNLC
entries.
[EINVAL] For the pstat_getproc(), pstat_getprocvm(),
pstat_getlv(), pstat_getsem(), pstat_getmsg(),
pstat_getshm(), pstat_getpset(),
pstat_getfile(), or pstat_getfile2() calls,
elemcount was not zero, and index was less than
zero.
[EINVAL] elemsize is less than or equal to zero or
elemsize is larger than the size of the
associated data structure (for example,
elemsize>sizeof( struct pst_processor) for the
pstat_getprocessor() call).
[EINVAL] elemcount is not 1 or index is not zero for the
pstat_getstatic(), pstat_getdynamic(),
Hewlett-Packard Company - 17 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
pstat_getvminfo(), pstat_getipc(),
pstat_getstable(), or pstat_getcrashinfo()
calls.
[EINVAL] elemcount is not greater than or equal to 1 or
index is not greater than or equal to zero for
the pstat_getprocessor(), pstat_getdisk(),
pstat_getswap(), pstat_getcrashdev(),
pstat_getpmq(), pstat_getpsem(), or
pstat_getnode() calls.
[EINVAL] index is not a valid logical node id for
pstat_getnode() call.
[EINVAL] elemcount is less than or equal to zero for
pstat_getpathname() call.
[EINVAL] If pstat_getfiledetails() is called for a
socket other than AF_UNIX family or
pstat_getpathname is called for a socket.
[EINVAL] If pstat_getsocket() is called for a file which
is not of type socket.
[EINVAL] If pstat_getcommandline() is called with pid
less than zero or elemcount not equal to one .
[EACCES] If uid!=0 and effective id does not match for
calls pstat_getfiledetails(),
pstat_getsocket(), pstat_getstream(), and
pstat_getpathname().
[EOVERFLOW] Offset element is too large to store into the
structure pointed to by the buf argument.
[EOVERFLOW] For the pstat_getfiledetails() call, 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 the pstat_getpathname() call, the elemcount
parameter is not one greater than the length of
the pathname to be returned.
[ENOSTR] pstat_getstream() is called for a file which is
neither a stream nor a stream based
pipe/socket.
[EINTR] For pstat_getsocket() call, the operation was
terminated due to the receipt of a signal, and
no data was transferred.
Hewlett-Packard Company - 18 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
[ENOBUFS] For pstat_getsocket() call, the operation was
terminated due to unavailability of buffer
space.
[ENOSYS] The requested pstat function is not implemented
or not configured in the system.
BACKWARD COMPATIBILITY [Toc] [Back]
The specific calling convention of passing the expected data structure
size is used 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 which passes its compile-time size of the
context's data structure (for example, sizeof(struct pst_processor)
for the per-process 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, say, HP-UX release 10.0 will not work on
HP-UX release 9.0.
The code examples, below, demonstrate the calling conventions
described above.
EXAMPLES [Toc] [Back]
#include <sys/param.h>
#include <sys/pstat.h>
#include <sys/unistd.h>
/*
* Example 1: get global information from pstat_getstatic()
*/
{
struct pst_static pst;
if (pstat_getstatic(&pst, sizeof(pst), (size_t)1, 0) != -1)
(void)printf("page size is %d bytes\n", pst.page_size);
Hewlett-Packard Company - 19 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
else
perror("pstat_getstatic");
}
/*
* Example 2: get information about all processors, first obtaining
* number of processor context instances
*/
{
struct pst_dynamic psd;
struct pst_processor *psp;
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));
if (pstat_getprocessor(psp, sizeof(struct pst_processor), nspu,
0) != -1) {
int i;
int total_execs = 0;
for (i = 0; i < nspu; i++) {
int execs = psp[i].psp_sysexec;
total_execs += execs;
(void)printf("%d exec()s on processor #%d\n",
execs, i);
}
(void)printf("total execs for the system were %d\n",
total_execs);
}
else
perror("pstat_getdynamic");
}
else
perror("pstat_getdynamic");
}
/*
* Example 3: get information about all per-process -- 10 at a time
* done this way since current count of active processes unknown
*/
{
#define BURST ((size_t)10)
struct pst_status pst[BURST];
int i, count;
int idx = 0; /* index within the context */
/* loop until count == 0, will occur all have been returned */
while ((count=pstat_getproc(pst, sizeof(pst[0]),BURST,idx))>0) {
Hewlett-Packard Company - 20 - HP-UX 11i Version 2: August 2003
pstat(2) pstat(2)
/* got count (max of BURST) this time. process them */
for (i = 0; i < count; i++) {
(void)printf("pid is %d, 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 +
|