PSTAT Interfaces May 2000 Table of Contents 1. Introduction ............................................................................................................................... 2 1.1 Abstract .................................................................................................................................. 2 1.2 Purpose of Document.............................................................................................................. 2 1.3 Intended Audience .................
4.21 pstat_getstable().................................................................................................................. 24 4.22 pstat_getstatic()................................................................................................................... 24 4.23 pstat_getstream() ................................................................................................................ 25 4.24 pstat_getswap() .......................................................................
• For more information on how to use pstat interfaces please refer to the source code of freeware application lsof at ftp://vic.cc.purdue.edu/pub/tools/unix/lsof 2. Overview In the early days of UNIX, programmers and system administrators were required to write their own tools to monitor and manage the system. In order to facilitate access to the internals of the kernel implementation, UNIX provided the /dev/kmem and /dev/ mem pseudo devices.
IPC Stable Store Crash Dumps Processor Disk Swap Areas Dump Areas Node Process LW Process Process Region LVM Volume Sema Set Msg Queue Shared Memory Open File Open File Open File Open Socket Open Stream Open File DNLC pst_ipcinfo pst_stable pst_crashinfo pst_processor pst_diskinfo pst_swapinfo pst_crashdev pst_node pst_status lwp_status pst_vm_status pst_lvinfo pst_seminfo pst_msginfo pst_shminfo pst_fileinfo pst_fileinfo2 pst_filedetails pst_socket pst_stream char * pst_mpathnode pstat_getipc() pstat_get
4. Description of Wrappers 4.1 pstat_getcrashdev() Synopsis: int pstat_getcrashdev(struct pst_crashdev *buf, size_t elemsize, size_t elemcount, int index); Description: This call returns information about crash dump devices configured on the system. There is one instance of this context for each crash dump device configured on the system. For each instance, data up to a maximum of elemsize bytes are returned in the structs pst_crashdev pointed to by buf.
• EINVAL is set if the user is in narrow more. • EINVAL is set if elemcount is not equal to 1 or index is not equal to 0. • EINVAL is set if user’s size declaration is not valid. • EFAULT is set if buf is invalid. Example: #include void main(void) { struct pst_crashinfo pst; int count; /* Get information about the first crash dump configuration. */ count = pstat_getcrashinfo(&pst, sizeof(pst), 1, 0); if (count > 0) { printf(“\nSize of total dump area: %d”, pst.
} for (i = 0; i < count; i++) { printf("\n Disk hardware path = %s", pst[i].psd_hw_path.psh_name); } } 4.4 pstat_getdynamic() Synopsis: int pstat_getdynamic(struct pst_dynamic *buf, size_t elemsize, size_t elemcount, int index); Description: This call returns dynamic system variables, ones that may change frequently during normal operation of the kernel. This includes such information, as the number of jobs in disk wait, free memory pages, open logical volumes, etc.
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(), as the most significant 16 bits, and the index of open files within the process as the least significant 16 bits.
Example: List all the open files for the parent process. #include
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. Return Value: This call returns –1 on failure or 1 on success. Errors: • EFAULT is set if buf or fid points to invalid address. • ENOENT is set if the specified file is not found or closed. • EINVAL is set if the user’s size declaration is invalid.
This call returns the system-wide global System V IPC constants. These are currently defined at boot time, but may become dynamic in future releases. There is only one instance of this context. 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. Return Value: This call returns –1 on failure or 1 on success. Errors: • EINVAL is set if elemcount is not equal to 1 or index is not equal to 0.
Example: #include #include #include
(1) (2) (3) (4) elemsize is > 0 or <= actual size of the kernel's version index >= 0 if pid >= 0, elemcount >= 0 if pid == -1, elemcount > 0 • ESRCH is set if the specific-PID (Process Identification number) shortcut is used and there is no active process with that PID. • EFAULT is set of buf points to invalid address. Example: #include void main(void) { struct lwp_status lwpbuf; /* * Get information for LWP whose lwpid is 4321 within * a process whose pid is 1234.
Return Value: 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. Errors: • EPERM is set if UID != 0. • EFAULT is set if buf or fsid point to invalid address. • EINVAL is set if elemcount is not greater than or equal to 1 or index is not greater than or equal to 0. • EINVAL is set if the user's size declaration isn't valid.
This call returns information describing System V message queues. Each structure returned describes one message queue identifier on the system. For each instance 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. The index parameter specifies the starting index within the context of System V message queues.
int pstat_getnode(struct pst_node *buf, size_t elemsize, size_t elemcount, int index); Description: This call returns information about SCA (ccNUMA) system nodes. It is only available as 64-bit data (i.e., _PSTAT64 needs to be defined). There is one instance of this context for each SCA node on the system. For each instance data up to a maximum of elemsize bytes are 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.
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.
#define BURST ((size_t)10) struct pst_status pst[BURST]; int i, count; int idx = 0; /* index within the context */ /* loop until count == 0 */ 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++) { 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].
• EFAULT is set if buf points to an invalid address. Example: Get information about all processors, first obtaining number of processor context instances. #include #include void main(void) { struct pst_dynamic psd; struct pst_processor *psp; int count; if (pstat_getdynamic(&psd, sizeof(psd), (size_t)1, 0) != -1) { size_t nspu = psd.
indicated process' address space. Additional information on VM regions mapped to files can be obtained with the pstat_getfiledetails() call. Return Value: This call returns 1 on success or –1 on failure. It returns 0 when there are no regions to copy. Errors: • EINVAL is set if the user's size declaration isn't valid. • EINVAL is set if index is less than 0. • ESRCH is set if elemcount > 0, and there is no active process with that PID. • EFAULT is set if buf points to an invalid address.
information for a single semaphore set may be obtained by setting elemcount to zero and setting index to the semid of that semaphore set. Return Value: This call returns –1 on failure or number of instances copied to buf on success. Errors: • EINVAL is set if the user's size declaration isn't valid. • EINVAL is set if index < 0. • ESRCH is set if the specific-semid shortcut is used and there is no semaphore set with that ID. • EFAULT is set if buf points to invalid address. Example: #include
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. Return Value: This call returns –1 on failure or number of instances copied to buf on success. Errors: • EINVAL is set if the user's size declaration isn't valid. • EINVAL is set if index < 0.
Description: This call 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 are 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_getfile2(). Use of this call is limited to UID == 0 or effective UID match. Please refer to pstat_getfiledetails() call for more information on effective UID match.
perror("pstat_getsocket()"); } } else { perror("pstat_getfile2"); } close(fd); } 4.21 pstat_getstable() Synopsis: int pstat_getstable(struct pst_stable *buf, size_t elemsize, size_t elemcount, int index); Description: Returns information contained in the system's stable storage area. There is one 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.
} else { perror("pstat_getstatic"); } } 4.23 pstat_getstream() Synopsis: int pstat_getstream(struct pst_stream *buf, size_t elemsize, size_t elemcount, int moduleskip, struct pst_fid *fid); Description: This call provides 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 are returned in the structs pst_stream pointed to by buf.
* If there is more than 1 module, we expect 3 structures, * head, modules). */ count = pstat_getstream(psfstream, sizeof(struct pst_stream), sizeof(psfstream) / sizeof(struct pst_stream), 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.
This call returns information about the virtual memory. There is only one 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. Return Value: On success, the call returns 1. On failure, value of -1 is returned and errno is set indicating the cause of the failure. Errors: • EINVAL is set if elemcount is not 1 or index is not 0.
6. Appendix pst_crashdev This structure describes a crash dump device. It is only available as 64-bit data. Header file: int64_t psc_idx; struct __psdev psc_device; int64_t psc_offset; int64_t psc_size; struct psdev psc_lv; int64_t psc_source; /* /* /* /* /* /* Index of this device.
struct psdrvnam psd_drv_name; /* driver name */ _T_LONG_T psd_token; /* driver's ID */ _T_LONG_T psd_instance; /* the instance of the device */ struct __pshwpath psd_hw_path; /* hardware path */ struct __psttime psd_dkwait; /* cumulative time from enqueue to start */ struct __psttime psd_dkresp; /* cumulative time from enqueue to done */ _T_LONG_T psd_dkcyl_index; /* cylinder number index, used by sadp */ _T_LONG_T psd_dkcyl[PS_DK_CYL_SIZE]; /* cylinder number array, * used by sadp */ _T_LONG_T psd_dkqlen_c
_T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T psd_mpdcnt; /* psd_procovf; /* psd_inodeovf; /* psd_fileovf; /* psd_global_virtual; int32_t _T_LONG_T _T_LONG_T _T_LONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T # of (bad) memory pages deallocated */ # of times the proc table overflowed */ # of times the inode table overflowed */ # of times the file table overflowed */ /* Available global virtual space * (pages) */ psd_valid; /* This is a vector that will indicate * if a certain field in is valid.
_T_OFF64_T _PSF_OFFSET64; /* * Current 64-bit offset in the file * If __STDC_32_MODE__, defined as * off32_t psf_dummy[2]; */ This structure provides three types of identifiers, namely: psf_id, psf_fid, and fileid and nodeid. This section explains the usage of these ids. The pstat_getfile2() call returns a list of all open files for a process. The pstat_getproc() call provides the text file, current working directory (cwd), and root. The pstat_getprocvm() call provides the memory regions for the process.
int32_t psfd_ftype; /* File type, PS_TYPE_VNODE etc. */ pst_subtype_t psfd_subtype; /* File sub type PS_SUBTYPE_CHARDEV etc. */ int32_t psfd_lckflag; /* Flags associated with file locking */ /* * This is a vector that will indicate if a certain field in the structure is * valid or not. User should check this field when EOVERFLOW is set.
_T_ULONG_T struct __psdev _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T psl_idx; psl_dev; psl_rxfer; psl_rcount; psl_wxfer; psl_wcount; psl_openlv; psl_mwcwaitq; _T_ULONG_T _T_ULONG_T _T_ULONG_T psl_mwcsize; psl_mwchits; psl_mwcmisses; /* /* /* /* /* /* /* /* * /* /* /* Index for further pstat() requests */ device specification for the volume */ # of reads */ # of bytes read */ # of writes */ # of bytes written */ # of opened LV's in this LV's LVG */ Length of LV's mirror write cons
int64_t int64_t int64_t int64_t int64_t int64_t int64_t lwp_fss; lwp_bind_flags; lwp_bind_spu; lwp_bind_ldom; lwp_reserved1; lwp_reserved2; lwp_reserved3; /* /* /* /* /* /* /* fair share scheduler group ID */ processor/ldom binding flag */ processor bound to */ ldom bound to */ reserved - do not use */ reserved - do not use */ reserved - do not use */ pst_mpathnode Header file: _T_ULONG_T psr_idx; /* * Current index of the entry on the chain of DNLC * entries.
uint64_t uint64_t uint64_t uint64_t uint64_t uint64_t uint64_t uint64_t uint64_t psn_idx; /* value currently undefined */ psn_logical_node; /* logical node ID */ psn_physical_node;/* physical node ID */ psn_cpu_cnt; /* number of node active CPUs */ psn_private_mem_size; /* node private memory in (MB)*/ psn_gmem_start; /* start of node global memory(in MB) */ psn_gmem_size; /* max size of node global memory(in MB) */ psn_reserved[3]; /* Reserved for future use */ psn_padding[6]; /* Padding to next pow(2) */
_T_ULONG_T pst_nsignals;/* # signals received by the process */ _T_ULONG_T pst_msgrcv; /* # socket msgs received by the proc*/ _T_ULONG_T pst_msgsnd; /* # of socket msgs sent by the proc */ _T_LONG_T pst_maxrss; /* highwater mark for proc resident set size */ _T_LONG_T pst_sid; /* session ID */ _T_LONG_T pst_schedpolicy; /* scheduling policy for the process */ _T_LONG_T pst_ticksleft; /* clock ticks left in process' RR timeslice */ struct __psfileid pst_rdir; /* File ID of the process' root directory */ str
struct __pst_fid pst_fid_cdir;/* uint32_t pst_hi_fileid_rdir; /* uint32_t pst_lo_fileid_rdir; uint32_t pst_hi_nodeid_rdir; /* uint32_t pst_lo_nodeid_rdir; struct __pst_fid pst_fid_rdir;/* uint32_t pst_hi_fileid_text; /* uint32_t pst_lo_fileid_text; uint32_t pst_hi_nodeid_text; /* uint32_t pst_lo_nodeid_text; struct __pst_fid pst_fid_text;/* Cookie for current working directory */ per shared file ID */ per vnode ID */ Cookie for root directory */ per shared file ID */ per vnode ID */ Cookie for text file */
double psp_avg_5_min; double psp_avg_15_min; /* per-processor CPU time/state */ _T_LONG_T psp_cpu_time[PST_MAX_CPUSTATES]; _T_ULONG_T psp_logical_node; /* node the spu is on */ pst_vm_status This structure contains process address space information. Header file:
pst_shminfo This structure describes System V shared memory segment) information. Each structure returned describes on segment identifier on the system. Header file:
uint32_t _T_ULONG_T _T_ULONG_T char char pst_pstate; /* protocol state */ pst_boundaddr_len; /* Length of pst_boundaddr */ pst_remaddr_len; /* Length of pst_remaddr */ pst_boundaddr[PS_ADDR_SZ]; /* local addr/port, etc */ pst_remaddr[PS_ADDR_SZ]; /* peer addr/port, etc */ The members pst_boundaddr and pst_remaddr contain data of the form struct sockaddr, sockaddr_un, sockaddr_in, sockaddr_in6, etc. depending on the socket family.
_T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T * freezes */ /* # of pages to try to keep free via * daemon */ pst_minfree; /* minimum free pages before swapping * begins */ pst_max_ninode; /* Max number of Inodes */ pst_max_nfile; /* Max number of file table entries */ pst_stable_size; /* size of data structure pst_stable */ pst_support
} val; Maximum module name length: PS_STRMODNAME_SZ à 32 The type field pst_stream structure can be PS_STR_HEAD, PS_STR_MODULE or The union val in pst_stream 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 the stream. PS_STR_DRIVER. pst_swapinfo This structure describes per-swap-area information.
_T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T _T_LONG_T psv_snzfod; psv_spgfrec; psv_spgin; psv_spgout; psv_spgpgin; psv_spgpgout; psv_spswpin; psv_spswpout; psv_srev; psv_sseqfree; psv_sswtch
_T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_ULONG_T _T_LONG_T /* LP demotions by page size */ psv_reserved1; /* reserved -- do not use */ psv_reserved2; /* reserved -- do not use */ psv_reserved3; /* reserved -- do not use */ psv_sbreadcache; /* Total bread cache hits */ psv_sbreada; /* Total read aheads */ psv_sbreadacache;/* Total read ahead cache hits */ psv_rpswpin; /*
