pstat(2)

NAME

pstat_getstatic(), pstat_getdynamic(), pstat_getproc(), pstat_getlwp(), pstat_getprocvm(), pstat_getprocessor(), pstat_getvminfo(), pstat_getdisk(), pstat_getlv(), pstat_getswap(), pstat_getfile(), pstat_getipc(), pstat_getsem(), pstat_getmsg(), pstat_getshm(), pstat_getstable(), pstat_getcrashinfo(), pstat_getcrashdev(), pstat() — get system information

SYNOPSIS

#include <sys/param.h>
#include <sys/pstat.h>

int pstat_getstatic(
     struct pst_static *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_getvminfo(
     struct pst_vminfo *buf, size_t elemsize, size_t elemcount,
     int index
);

int pstat_getipc(
     struct pst_ipcinfo *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_getproc(
     struct pst_status *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_getprocvm(
     struct pst_vm_status *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_getlv(
     struct pst_lv *buf, size_t elemsize, size_t elemcount,
     int index
);

int pstat_getswap(
     struct pst_swapinfo *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_getmsg(
     struct pst_msginfo *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_getfile(
     struct pst_fileinfo *buf, size_t elemsize, size_t elemcount,
     int index
);

int pstat_getstable(
     struct pst_stable *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_getcrashdev(
     struct pst_crashdev *buf, size_t elemsize, size_t elemcount,
     int index
);

int pstat(
     int, union pstun, size_t, size_t, int
);

Remarks

The underlying function pstat() is provided for backward compatibility. Use of the pstat_get*() wrapper functions (for example, pstat_getproc()) is recommended to avoid the polymorphic typing of the union pstun parameter.

DESCRIPTION

The pstat functions return information about various system contexts. The contents of the various contexts' associated data structures, structs pst_static, pst_dynamic, pst_vminfo, pst_ipcinfo, pst_processor, pst_diskinfo, pst_swapinfo, pst_status, pst_vm_status, pst_lvinfo, pst_seminfo, pst_msginfo, pst_shminfo, pst_fileinfo, pst_stable, pst_crashinfo, and pst_crashdev, are declared in the header file <sys/pstat.h>. The header contains 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
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
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
Open File	`pst_fileinfo`	`pstat_getfile()`	1 per file	yes

Wrapper Function Descriptions

pstat_getstatic()

Returns static information about the system. This data does not vary while the system is running. There is one global instance of this context. Data, up to a maximum of elemsize bytes, are returned in the struct pst_static pointed to by buf. The elemcount parameter must be 1. The index parameter must be 0.

pstat_getdynamic()

Returns dynamic information about the system. There is one global instance of this context. Data, up to a maximum of elemsize bytes, are returned in the struct pst_dynamic pointed to by buf. The elemcount parameter must be 1. The index parameter must be 0.

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, are returned in the struct pst_vminfo pointed to by buf. The elemcount parameter must be 1. The index parameter must be 0.

pstat_getipc()

Returns information about System V IPC subsystem. There is one global instance of this context. This data does not vary while the system is running. Data, up to a maximum of elemsize bytes, are returned in the struct pst_ipcinfo pointed to by buf. The elemcount parameter must be 1. The index parameter must be 0.

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_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, are 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_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, are 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_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, are 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_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, are 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_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, are 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_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, are 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_getprocvm()

Returns information specific to a particular process' 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, are 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.

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, are 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_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, are 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_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, are 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_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, are 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_getfile()

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, are 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_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, are returned in the struct pst_stable 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, and pstat_getcrashdev interfaces are available only in the wide mode and for applications written in standard C and extended ANSI.

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. 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 points to an invalid address.
[ESRCH]: For the pstat_getproc(), pstat_getprocvm(), pstat_getlv(), pstat_getsem(), pstat_getmsg(), pstat_getshm() or pstat_getfile() 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()).
[EINVAL]: For the pstat_getproc(), pstat_getprocvm(), pstat_getlv(), pstat_getsem(), pstat_getmsg(), pstat_getshm() or pstat_getfile() 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(), 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(), or pstat_getcrashdev() calls.
[EOVERFLOW]: Offset element is too large to store into the structure pointed to by the buf argument.

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 static global information 
 */ 
{ 
     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(*psp)); 
          if (pstat_getprocessor(psp, sizeof(*psp), 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' 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(*pss)); 
          if (pstat_getshm(pss, sizeof(*pss), 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 a process 
 */ 
{ 
     struct pst_status pst; 
     int target = (int)getppid(); 
  
     /* 
      * First get the desired process to get its 'index'. 
      * This will be used when retrieving the file data. 
      */ 
     if (pstat_getproc(&pst, sizeof(pst), (size_t)0, target) != -1) { 
          int pidx = pst.pst_idx; 
#define BURST ((size_t)10) 
          struct pst_fileinfo psf[BURST]; 
          int i, count; 
          int idx = 0; /* index within the context */ 

          (void)printf("Open files for process PID %d\n", pst.pst_pid); 

          /* 
           * Construct the index into the per-process file context: 
           * Most significant 16 bits are the process' index (above). 
           * Least significant 16 bits are the file's index. 
           * For a given process, the file index starts at 0. 
           */ 
          idx = (pidx << 16) | (0 & 0xffff); 

          /* loop until all fetched */ 
          while (count = pstat_getfile(psf, sizeof(psf[0]), 
                 BURST, idx) > 0) { 
               /* process them (max of BURST) at a time */ 
               for (i = 0; i < count; i++) { 
                    (void)printf("fd #%x\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_idx + 1; 
          } 
          if (count == -1) 
               perror("pstat_getfile()"); 

#undef BURST 
     } 
     else 
          perror("pstat_getproc"); 
} 

/* 
 * Example 7: Acquire information about a specific LWP 
 */ 
{ 
     struct lwp_status lwpbuf; 

     /* 
      * get information for LWP whose lwpid is 121 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 
          ...
} 

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.