Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
sg_get_process_stats(3)				       sg_get_process_stats(3)

NAME
       sg_get_process_stats,   sg_get_process_stats_r,	 sg_get_process_count,
       sg_get_process_count_of,	sg_get_process_count_r,	sg_free_process_count,
       sg_process_compare_name,	    sg_process_compare_pid,    sg_process_com-
       pare_uid,       sg_process_compare_gid,	      sg_process_compare_size,
       sg_process_compare_res, sg_process_compare_cpu, sg_process_compare_time
       - get process statistics

SYNOPSIS
       #include	<statgrab.h>

       sg_process_stats	*sg_get_process_stats (size_t *entries);

       sg_process_stats	*sg_get_process_stats_r	(size_t	*entries);

       sg_error	sg_free_process_stats (sg_process_stats	*data);

       sg_process_count	*sg_get_process_count (void);

       sg_process_count	*sg_get_process_count_of (sg_process_count_source
		       pcs);

       sg_process_count	*sg_get_process_count_r	(sg_process_stats const
		       *whereof);

       sg_error	sg_free_process_count (sg_process_count	*data);

       int sg_process_compare_name (const void *va, const void *vb);

       int sg_process_compare_pid (const void *va, const void *vb);

       int sg_process_compare_uid (const void *va, const void *vb);

       int sg_process_compare_gid (const void *va, const void *vb);

       int sg_process_compare_size (const void *va, const void *vb);

       int sg_process_compare_res (const void *va, const void *vb);

       int sg_process_compare_cpu (const void *va, const void *vb);

       int sg_process_compare_time (const void *va, const void *vb);

DESCRIPTION
       The sg_get_process_stats	functions provide statistics  about  the  cur-
       rently  running	processes.  Both functions, sg_get_process_stats() and
       sg_get_process_stats_r(), take an  optional  entries  parameter,	 which
       points  (when  given) to	a size_t to take the number of returned	vector
       entries.

       The functions  sg_get_process_count_of()	 and  sg_get_process_count_r()
       provide	an  aggregated	view  of  the process table - they deliver the
       amount of processes per process state. The sg_get_process_count() is in
       fact   a	 preprocessor  macro  for  backward  compatibility  and	 calls
       sg_get_process_count_of()   with	  the	parameter   pcs	  of	sg_en-
       tire_process_count to emulate the behavior until	0.17.

       API Shortcut

       +------------------------+--------------------+---------------------+
       |function		| returns	     | data owner	   |
       +------------------------+--------------------+---------------------+
       |sg_get_process_stats	| sg_process_stats * | libstatgrab (thread |
       |			|		     | local)		   |
       +------------------------+--------------------+---------------------+
       |sg_get_process_stats_r	| sg_process_stats * | caller		   |
       +------------------------+--------------------+---------------------+
       |sg_get_process_count_of	| sg_process_count * | libstatgrab (thread |
       |			|		     | local)		   |
       +------------------------+--------------------+---------------------+
       |sg_get_process_count_r	| sg_process_count * | caller		   |
       +------------------------+--------------------+---------------------+
       The sg_process_stats vectors received from sg_get_process_stats_r()  or
       the  sg_process_count  summaries	 received  from	sg_get_process_count_r
       must be freed using sg_free_process_stats() or sg_free_process_count(),
       respectively.   The  caller  is	responsible for	doing it when the data
       isn't needed any	more.

       sg_process_compare_name
       sg_process_compare_pid
       sg_process_compare_uid
       sg_process_compare_gid
       sg_process_compare_size
       sg_process_compare_res
       sg_process_compare_cpu
       sg_process_compare_time

       These functions compare two sg_process_stats entries, and return	an int
       to  represent  which one	is greater. The	main use of these functions is
       to be passed to qsort to	sort the sg_process_stats by the given type.

       Example

       size_t entries;
       sg_process_stats	*proc_stats = NULL;
       while( NULL != (	proc_stats = sg_get_process_stats_r(&entries) )	) {
	   /* order entries by comparing the process identifier	*/
	   qsort( proc_stats, entries, sizeof(proc_stats[0]), &sg_process_compare_pid );
	   show_proc_stats( proc_stats );
	   sg_free_process_stats( proc_stats );
       }

RETURN VALUES
       The   structure	 returned   by	 sg_get_process_stats	is   of	  type
       sg_process_stats.

       typedef struct {
	       char *process_name;
	       char *proctitle;

	       pid_t pid;    /*	process	identifier */
	       pid_t parent; /*	Parent pid */
	       pid_t pgid;   /*	process	id of process group leader */
	       pid_t sessid; /*	session	id of the session the process belongs to */

	       uid_t uid;
	       uid_t euid;
	       gid_t gid;
	       gid_t egid;

	       unsigned	long long context_switches;
	       unsigned	long long voluntary_context_switches;
	       unsigned	long long involuntary_context_switches;
	       unsigned	long long proc_size; /*	in bytes */
	       unsigned	long long proc_resident; /* in bytes */
	       time_t start_time; /* When was the process started */
	       time_t time_spent; /* time running in seconds */
	       double cpu_percent;
	       int nice;
	       sg_process_state	state;

	       time_t systime;
       } sg_process_stats;

       typedef enum {
	       SG_PROCESS_STATE_RUNNING,
	       SG_PROCESS_STATE_SLEEPING,
	       SG_PROCESS_STATE_STOPPED,
	       SG_PROCESS_STATE_ZOMBIE,
	       SG_PROCESS_STATE_UNKNOWN
       } sg_process_state;

       process_name
	      The  name	of the command that was	run. The content of this field
	      heavily depends on the underlying	operating system,  some	 store
	      the  basename  the executable passes to the exec(2) system call,
	      some the entire path. Most OS restrict the size of this field  -
	      some like	the *BSD family	to a very low value of 15 bytes.

	      This field is usually immutable for userland processes.

       proctitle
	      The  command line	(the "title") of the process. Take note	- this
	      can be modified by the process, so isn't guaranteed  to  be  the
	      original command line.

       pid    The process ID.

       parent The parent process ID.

       pgid   The process ID of	the process group leader.

       sessid Session id of the	session	the process belongs to.

       uid    The ID of	the user the process is	running	as.

       euid   The ID of	the effective user the process is running as.

       gid    The ID of	the group the process is running as.

       egid   The ID of	the effective group the	process	is running as.

       context_switches
	      The  number  of  context switches	of this	process	(voluntary and
	      involuntary).

       voluntary_context_switches
	      The number of voluntary context switches of  this	 process  (eg.
	      by calling sched_yield() or sleep()).

       involuntary_context_switches
	      The  number of involuntary context switches of this process (eg.
	      time slice exhausted or signal sent).

       proc_size
	      The virtual memory size of the process in	bytes.

       proc_resident
	      The size of the process that's resident in memory.

       start_time
	      The time when the	process	has  been  started  in	seconds	 since
	      epoch.

       time_spent
	      The  number of seconds the process has been running (user+system
	      time, without time spent by child	processes).

       cpu_percent
	      The current percentage of	CPU the	process	is using.

       nice   The nice value of	the process.

       state  The current state	of the process.	See sg_process_state for  per-
	      mitted values.

       systime
	      The  time	in seconds since epoch of the moment where the present
	      statistic	has been created. This might be	(but doesn't  have  to
	      be) the same moment for all returned entries, regardless whether
	      they're fetched with one snapshot	or puzzled from	some  kind  of
	      procfs.

       The     structure     returned	  by	sg_get_process_count_of	   and
       sg_get_process_count_r is of type sg_process_count.

       typedef enum sg_process_count_source {
	       sg_entire_process_count,
	       sg_last_process_count
       } sg_process_count_source;

       typedef struct{
	       unsigned	long long total;
	       unsigned	long long running;
	       unsigned	long long sleeping;
	       unsigned	long long stopped;
	       unsigned	long long zombie;
	       unsigned	long long unknown;

	       time_t systime;
       }sg_process_count;

       total  The total	number of processes.

       running
	      The number of running processes.

       sleeping
	      The number of sleeping processes.

       stopped
	      The number of stopped processes.

       zombie The number of zombie processes.

       unknown
	      The number of processes not matching any of  above  named	 cate-
	      gories.

       systime
	      The  time	in seconds since epoch of the moment where the present
	      statistic	has been created.

BUGS
       The very	first call  of	sg_get_process_count_of(sg_last_process_count)
       will	return	   the	  same	  as	sg_get_process_count_of(sg_en-
       tire_process_count).

       The compare functions exist rather for backward compatibility than  for
       functionality  enhancements.  Limited  flexibility (e.g.	reverse	order)
       and lack	of optimising opportunities for	the compiler leads to the rec-
       ommendation to implement	the required compare routines locally.

SEE ALSO
       statgrab(3)

WEBSITE
       <http://www.i-scream.org/libstatgrab/>

i-scream			  2013-06-07	       sg_get_process_stats(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | BUGS | SEE ALSO | WEBSITE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sg_get_process_stats&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help