unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 pstat(2)							    pstat(2)




 NAME
      pstat_getcrashdev(), pstat_getcrashinfo(), pstat_getdisk(),
      pstat_getdynamic(), pstat_getfile(), pstat_getfile2(),
      pstat_getfiledetails(), pstat_getipc(), pstat_getlv(), pstat_getlwp(),
      pstat_getmpathname(), pstat_getmsg(), pstat_getnode(),
      pstat_getpathname(), pstat_getproc(), pstat_getprocessor(),
      pstat_getprocvm(), pstat_getsem(), pstat_getshm(), pstat_getsocket(),
      pstat_getstable(), pstat_getstatic(), pstat_getstream(),
      pstat_getswap(), pstat_getvminfo(), pstat()   - get system information

 SYNOPSIS
      #include <&lt&lt&lt;sys/param.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/pstat.h>&gt&gt&gt;

      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



 Hewlett-Packard Company	    - 1 -    HP-UX Release 11i: November 2000






 pstat(2)							     pstat(2)




      );

      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_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_getsem(
	   struct pst_seminfo *buf, size_t elemsize, size_t elemcount,
	   int index
      );




 Hewlett-Packard Company	    - 2 -    HP-UX Release 11i: November 2000






 pstat(2)							     pstat(2)




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

      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 is recommended (for example,
      pstat_getproc()) 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 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_processor, pst_seminfo,
      pst_shminfo, pst_stable, pst_static, pst_status, pst_socket,



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




      pst_stream, pst_swapinfo, pst_vminfo, and pst_vm_status, are declared
      in the header files <&lt&lt&lt;sys/pstat.h>&gt&gt&gt;, <&lt&lt&lt;sys/pstat/*_pstat_body.h>&gt&gt&gt;.  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		 |
 _____________|______________|_____________________|_____________________|_____
 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
 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_getcrashdev()
		     Returns information specific to a particular crash dump
		     device.  There is one instance of this context for each



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




		     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_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, 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_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_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, 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



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




		     the process as the least significant 16 bits.  Example:

		     index = ((pst_idx <&lt&lt&lt;<&lt&lt&lt; 16) | (file_index &&amp&amp&amp; 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, are 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



 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




		     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 are 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 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_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.




 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	   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_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 are 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



 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




		     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, 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_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, 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 to be filled in. The index parameter
		     specifies the starting logical node id that is
		     requested.



 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	   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_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_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_getprocvm()
		     Returns information specific to a particular process'
		     address space.  There is one instance of this context



 Hewlett-Packard Company	   - 10 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




		     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. More information
		     on VM regions mapped to files can be obtained with the
		     pstat_getfiledetails() call.

	   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_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.




 Hewlett-Packard Company	   - 11 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	   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 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_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 struct sockaddr,
		     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, are
		     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 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_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 are 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



 Hewlett-Packard Company	   - 12 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




		     about any modules. Head information is returned for
		     every call.  The fid parameter uniquely identifies the
		     file. This id is obtained from calls to pstat_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, 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_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.

    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.





 Hewlett-Packard Company	   - 13 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




      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.

 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/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_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_getfile() or pstat_getfile2()
			  calls, elemcount was not zero, and index was less
			  than zero.

	   [EINVAL]	  elemsize is less than or equal to zero or elemsize
			  is larger than the size of the associated data
			  structure (for example, elemsize>sizeof( struct
			  pst_processor) for the pstat_getprocessor() call).

	   [EINVAL]	  elemcount is not 1 or index is not zero for the
			  pstat_getstatic(), pstat_getdynamic(),
			  pstat_getvminfo(), pstat_getipc(),
			  pstat_getstable(), or pstat_getcrashinfo() calls.




 Hewlett-Packard Company	   - 14 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	   [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(), 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

	   [EACCES]	  If uid!=0 or 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.

 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



 Hewlett-Packard Company	   - 15 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




      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 <&lt&lt&lt;sys/param.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/pstat.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/unistd.h>&gt&gt&gt;

      /*
       * Example 1: get static global information
       */
      {
	   struct pst_static pst;

	   if (pstat_getstatic(&&amp&amp&amp;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;




 Hewlett-Packard Company	   - 16 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	   if (pstat_getdynamic(&&amp&amp&amp;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 <&lt&lt&lt; 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))>&gt&gt&gt;0) {
		/* got count (max of BURST) this time.	process them */
		for (i = 0; i <&lt&lt&lt; 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;
	   }




 Hewlett-Packard Company	   - 17 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	   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(&&amp&amp&amp;pst, sizeof(pst), (size_t)0, target) != -1)
		(void)printf("Parent started at %s", ctime(&&amp&amp&amp;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(&&amp&amp&amp;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 <&lt&lt&lt; num_shm; i++) {
			  /* skip inactive segments */
			  if (!(pss[i].psh_flags &&amp&amp&amp; 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");
      }





 Hewlett-Packard Company	   - 18 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




      /*
       * 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)) >&gt&gt&gt; 0) {
		     /* process them (max of BURST) at a time */
		     for (i = 0; i <&lt&lt&lt; 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)





 Hewlett-Packard Company	   - 19 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	   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(&&amp&amp&amp;psf, sizeof(psf), 0, fd, getpid());
	  if (count == 1) {
	       count = pstat_getfiledetails(&&amp&amp&amp;psfdetails, sizeof(psfdetails),
					    &&amp&amp&amp;psf.psf_fid);
	       if (count == 1) {
		     if ((psfdetails.psfd_hi_fileid == psf.psf_hi_fileid) &&amp&amp&amp;&&amp&amp&amp;
			 (psfdetails.psfd_lo_fileid == psf.psf_lo_fileid) &&amp&amp&amp;&&amp&amp&amp;
			 (psfdetails.psfd_hi_nodeid == psf.psf_hi_nodeid) &&amp&amp&amp;&&amp&amp&amp;
			 (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;




 Hewlett-Packard Company	   - 20 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	  fd = open("/dev/echo", O_RDONLY);
	  rv = pstat_getfile2(&&amp&amp&amp;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,
				  &&amp&amp&amp;(psf.psf_fid));
	      if (count >&gt&gt&gt; 0) {
		    if ((psfstream[0].val.head.pst_hi_fileid ==
			      psf.psf_hi_fileid) &&amp&amp&amp;&&amp&amp&amp;
			  (psfstream[0].val.head.pst_lo_fileid ==
			      psf.psf_lo_fileid) &&amp&amp&amp;&&amp&amp&amp;
			  (psfstream[0].val.head.pst_hi_nodeid ==
			      psf.psf_hi_nodeid) &&amp&amp&amp;&&amp&amp&amp;
			  (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);
      }

      /*
       * 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(&&amp&amp&amp;psf, sizeof(psf), 0, fd, getpid());




 Hewlett-Packard Company	   - 21 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	  if (rv == 1) {

	      /*
	       * Ask for socket information.
	       */
	      count = pstat_getsocket(psfsocket, sizeof(struct pst_socket),
				      &&amp&amp&amp;(psf.psf_fid));
	      if (count == 1) {
		    if ((psfsocket.pst_hi_fileid == psf.psf_hi_fileid) &&amp&amp&amp;&&amp&amp&amp;
			(psfsocket.pst_lo_fileid == psf.psf_lo_fileid) &&amp&amp&amp;&&amp&amp&amp;
			(psfsocket.pst_hi_nodeid == psf.psf_hi_nodeid) &&amp&amp&amp;&&amp&amp&amp;
			(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(&&amp&amp&amp;psf, sizeof(psf), 0, fd, getpid());

      if (rv == 1) {

	  /*
	   * Ask for pathname information.
	   */
	  count = pstat_getpathname(filename, 20, &&amp&amp&amp;(psf.psf_fid));
	  if (count >&gt&gt&gt; 0) {
		if (strncmp("/etc/passwd", filename, count) == 0) {




 Hewlett-Packard Company	   - 22 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




			     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(&&amp&amp&amp;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, &&amp&amp&amp;(psf.psf_id.psf_fsid));
	  if (count >&gt&gt&gt; 0) {
		for (i = 0; i <&lt&lt&lt; 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 {



 Hewlett-Packard Company	   - 23 -   HP-UX Release 11i: November 2000






 pstat(2)							    pstat(2)




	       perror("pstat_getfile2");
	}
	close(fd);
      }

 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	    Includes various header files that
				    contain detailed descriptions of context
				    data structures and fields.

 SEE ALSO
      ps(1), top(1), vmstat(1), iostat(1), fuser(1M), vgdisplay(1M),
      crashconf(1M), stat(2), sysconf(2), semctl(2), msgctl(2), shmctl(2),
      crashconf(2), fileno(3S).































 Hewlett-Packard Company	   - 24 -   HP-UX Release 11i: November 2000