pstat(2)

NAME

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

#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
);

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
);

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
);

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

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

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

The pstat routines support the following contexts of information. Detailed descriptions of each routine follow.

				`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

				`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

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 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));

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 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 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;  
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 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 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 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 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. When applications are compiled with the _PSTAT_STREAM_GET_XPORT flag, the pstat_getstream() API reports the Transport protocol details for XTI/TLI-based TCP/UDP end-points. pstat_getstream() returns the Transport protocol information in the instance that contains the Stream head information. It sets the PS_STR_XPORT_DATA bit in the pst_extn_flags to indicate that the Transport details are available for the open file descriptor. The fid 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

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.

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.

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.

RETURN VALUE

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

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: 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_stream) for the pstat_getstream() call).
EINVAL: elemcount is not 1 or index is not zero for the pstat_getstatic(), pstat_getdynamic(), 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.
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

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

#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); 
      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) { 
          /* 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 + 1; 
     } 

     if (count == -1) 
          perror("pstat_getproc()"); 

#undef BURST 
} 

/* 
 * Example 4: Get a particular process's information 
 */ 
{ 
     struct pst_status pst; 
     int target = (int)getppid(); 

     if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) 
          (void)printf("Parent started at %s", ctime(&pst.pst_start)); 
     else 
          perror("pstat_getproc"); 
} 

/* 
 * Example 5: get information about all shared memory segments 
 */ 
{ 
     struct pst_ipcinfo psi; 
     struct pst_shminfo *pss; 

     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)); 
          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("%d\t%#x\t%d\n", 
                                 pss[i].psh_uid, pss[i].psh_key, 
                                 pss[i].psh_segsz); 
               } 
          } 
          else 
               perror("pstat_getshm"); 
     } 
     else 
          perror("pstat_getipc"); 
} 

/* 
 * Example 6: List all the open files for the parent process 
 */ 
{ 
      pid_t target = getppid(); 
#define BURST ((size_t)10) 
      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 #%d\tFSid %x:%x\tfileid %d\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 7: Acquire information about a specific LWP 
 */ 
{ 
     struct lwp_status lwpbuf; 

     /* 
      * get information for LWP whose lwpid is 4321 within 
      * a process whose pid is 1234. 
      */ 

     count = pstat_getlwp(buf, sizeof(struct lwp_status),  
          0, 4321, 1234) 

     if (count == -1) 
          perror("pstat_getlwp()"); 
     else 
          ...
} 

/* 
 * Example 8: Acquire detailed information about a specific file 
 */ 
main() 
{ 
    struct pst_fileinfo2 psf; 
    struct pst_filedetails psfdetails; 
    int count, fd; 

    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 9: Acquire detailed information about a stream 
 */ 
main() 
{ 

    struct pst_fileinfo2 psf; 
    struct pst_stream psfstream[3]; 
    int rv, count, fd; 
  
    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 %d\n", 
                                psfstream[0].val.head.pst_dev_major); 
              } else { 
                       printf("State changed\n"); 
              } 
        } else { 
          perror("pstat_getstream()"); 
        } 
    } else { 
         perror("pstat_getfile2"); 
    } 
    close(fd); 
} 

/* 
 * cc -D_PSTAT_STREAM_GET_XPORT -o example9A example9A.c -lxti 
 * 
 * Example 9A: Acquire protocol information of an XTI 
 *             or a TLI TCP/UDP end-point. 
 */ 
#include <stdio.h> 
#include <sys/param.h> 
#include <sys/pstat.h> 
#include <sys/unistd.h> 
#include <sys/xti.h> 
#include <netinet/in.h> 
#include <fcntl.h> 
#include <stdlib.h> 
main() 
{ 

    struct pst_fileinfo2 psf; 
    struct pst_stream *psfstream; 
    int rv, count, fd, entt_cnt, i; 
  
    fd = t_open("/dev/tcp", O_RDWR, NULL); 
  
    if ( fd < 0 ) { 
       t_error("t_open() failed /dev/tcp"); 
       exit(-1); 
    }; 
  
    rv = t_bind(fd, NULL, NULL); 
    if ( rv < 0 ) { 
       t_error("t_bind() failed on the fd"); 
       exit(-1); 
    }; 
  
    rv = pstat_getfile2(&psf, sizeof(psf), 0, fd, getpid()); 
    if (rv == 1) { 
        entt_cnt = psf.psf_nstrentt; 
        psfstream = (struct pst_stream *)malloc(entt_cnt * 
                                            sizeof(struct pst_stream)); 
        if (!psfstream) { 
            perror("malloc failed"); 
        } 
  
        /* 
         * Get Transport protocol information for this stream. 
         */ 
        count = pstat_getstream(psfstream, sizeof(struct pst_stream), 
                                    entt_cnt, 0, &(psf.psf_fid)); 
        if (count > 0) { 
           for (i = 0; i < entt_cnt; i++) { 
                if (psfstream[i].type != PS_STR_HEAD) 
                    continue; 
                break; 
           } 
  
           if (i >= entt_cnt) { 
               perror("No STREAM Head"); 
               return(1); 
           } 
  
           if ((psfstream[i].val.head.pst_hi_fileid == 
                     psf.psf_hi_fileid) && 
               (psfstream[i].val.head.pst_lo_fileid == 
                     psf.psf_lo_fileid) && 
               (psfstream[i].val.head.pst_hi_nodeid == 
                     psf.psf_hi_nodeid) && 
                    (psfstream[i].val.head.pst_lo_nodeid == 
                        psf.psf_lo_nodeid)) { 
                     printf("Success\n"); 
                     printf("The major number of the stream is %d\n", 
                                psfstream[i].val.head.pst_dev_major); 
  
                     if (psfstream[i].pst_extn_flags & 
                          PS_STR_XPORT_DATA) { 
                        if (psfstream[i].pst_str_xport_protocol == 
                              PS_STR_XPORT_TCP_PROTO) { 
                          printf("TCP max hiwat %d\n", 
                                      psfstream[i].pst_str_xport_obufsz); 
                          printf("Local port number is %d\n", 
                                  ((struct sockaddr_in *) 
                                  (psfstream[i].pst_str_xport_boundaddr)) 
                                   ->sin_port); 
                          printf("TCP protocol state %d\n", 
                                   psfstream[i].pst_str_xport_pstate); 
                        } 
                     } 
           } else { 
              printf("State changed\n"); 
           } 
        } else { 
          perror("pstat_getstream()"); 
        } 
    } else { 
         perror("pstat_getfile2"); 
    } 
    close(fd); 
} 

/* 
 * Example 10: Acquire detailed information about a socket 
 */ 
main() 
{ 
    struct pst_fileinfo2 psf; 
    struct pst_socket psfsocket; 
    int rv, count, fd; 
  
    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 %d, 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 11: Acquire pathname information about opened file 
 */ 
main() 
{ 
  
struct pst_fileinfo2 psf; 
char filename[20]; 
int rv, count, fd; 
  
fd = open("/etc/passwd", O_RDONLY); 
rv = pstat_getfile2(&psf, sizeof(psf), 0, fd, getpid()); 
  
if (rv == 1) { 
  
    /* 
     * Ask for pathname 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("pathname not found in system cache\n"); 
    } else { 
          perror("pstat_getpathname()"); 
    } 
  } else { 
         perror("pstat_getfile2"); 
  } 
  close(fd); 
} 

/* 
 * Example 12: Acquire multiple pathname information for a file 
 * system 
 */ 
main() 
{ 
  
struct pst_fileinfo2 psf; 
struct pst_mpathnode mpath_buf[20]; 
int i, rv, count, fd; 
pid_t target; 
  
target = getpid(); 
  
fd = open("/etc/passwd", O_RDONLY); 
rv = pstat_getfile2(&psf, sizeof(psf), 0, fd, target); 
  
if (rv == 1) { 
  
    /* 
     * Ask for multiple pathname 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("pathnames not found in system cache\n"); 
    } else { 
          perror("pstat_getmpathname()"); 
    } 
  } else { 
         perror("pstat_getfile2"); 
  } 
  close(fd); 
} 

/* 
 * Example 13: Acquire the extended commandline for the process 
 */ 
main() 
{ 
  
char cmdline[1024]; 
int rv; 
  
  
rv = pstat_getcommandline(cmdline, sizeof(cmdline),1, getpid()); 
  
if (rv < 0) { 
          perror("pstat_getcommandline()"); 
} else { 
         printf("Commandline : %s \n",cmdline); 
  } 
} 

WARNINGS

Some parts of the program status may not get updated when a process becomes a zombie. An example is that the cpu percentage is not updated because the process is not expected to be scheduled to run after entering the zombie state.

AUTHOR

The pstat routines were developed by HP.

FILES

/usr/include/sys/pstat.h: Contains detailed descriptions of context data structures and fields.