diff options
author | Tristan Hill <stan@saticed.me.uk> | 2010-04-18 11:54:00 +0000 |
---|---|---|
committer | Robert Roth <robert.roth.off@gmail.com> | 2013-08-30 07:31:31 +0300 |
commit | 753d9abb130a0960d59762625ac2286ae48bbbdc (patch) | |
tree | 2e904898a193320cffde8813e454de6c42336047 | |
parent | 3c4ddb5572b1b8b886571030540ce970ff68427e (diff) | |
download | libgtop-753d9abb130a0960d59762625ac2286ae48bbbdc.tar.gz |
proclist, procarg and proctime gtkdoc updates
Added gtkdoc for proclist, procarg and proctime.
Author: Tristan Hill <stan@saticed.me.uk>
https://bugzilla.gnome.org/show_bug.cgi?id=616082
-rw-r--r-- | doc/reference/libgtop-sections.txt | 37 | ||||
-rw-r--r-- | include/glibtop/proclist.h | 69 | ||||
-rw-r--r-- | include/glibtop/proctime.h | 58 | ||||
-rw-r--r-- | sysdeps/common/default.c | 69 |
4 files changed, 168 insertions, 65 deletions
diff --git a/doc/reference/libgtop-sections.txt b/doc/reference/libgtop-sections.txt index 0d99d695..ba878943 100644 --- a/doc/reference/libgtop-sections.txt +++ b/doc/reference/libgtop-sections.txt @@ -219,17 +219,8 @@ glibtop_set_parameter_l <INCLUDE>glibtop/procargs.h</INCLUDE> <SECTION> <FILE>procargs</FILE> -GLIBTOP_PROC_ARGS_SIZE -GLIBTOP_MAX_PROC_ARGS glibtop_proc_args -glibtop_get_proc_args_l glibtop_get_proc_args -glibtop_get_proc_args_r -glibtop_init_proc_args_p -glibtop_get_proc_args_p -glibtop_init_proc_args_s -glibtop_get_proc_args_s -glibtop_get_proc_argv_l glibtop_get_proc_argv </SECTION> @@ -420,26 +411,8 @@ glibtop_get_proc_uid_s <INCLUDE>glibtop/proctime.h</INCLUDE> <SECTION> <FILE>proctime</FILE> -GLIBTOP_PROC_TIME_START_TIME -GLIBTOP_PROC_TIME_RTIME -GLIBTOP_PROC_TIME_UTIME -GLIBTOP_PROC_TIME_STIME -GLIBTOP_PROC_TIME_CUTIME -GLIBTOP_PROC_TIME_CSTIME -GLIBTOP_PROC_TIME_TIMEOUT -GLIBTOP_PROC_TIME_IT_REAL_VALUE -GLIBTOP_PROC_TIME_FREQUENCY -GLIBTOP_PROC_TIME_XCPU_UTIME -GLIBTOP_PROC_TIME_XCPU_STIME -GLIBTOP_MAX_PROC_TIME glibtop_proc_time glibtop_get_proc_time -glibtop_get_proc_time_r -glibtop_get_proc_time_l -glibtop_init_proc_time_p -glibtop_get_proc_time_p -glibtop_init_proc_time_s -glibtop_get_proc_time_s </SECTION> <INCLUDE>glibtop/signal.h</INCLUDE> @@ -515,10 +488,6 @@ glibtop_send_version <INCLUDE>glibtop/proclist.h</INCLUDE> <SECTION> <FILE>proclist</FILE> -GLIBTOP_PROCLIST_NUMBER -GLIBTOP_PROCLIST_TOTAL -GLIBTOP_PROCLIST_SIZE -GLIBTOP_MAX_PROCLIST GLIBTOP_KERN_PROC_ALL GLIBTOP_KERN_PROC_PID GLIBTOP_KERN_PROC_PGRP @@ -532,12 +501,6 @@ GLIBTOP_EXCLUDE_SYSTEM GLIBTOP_EXCLUDE_NOTTY glibtop_proclist glibtop_get_proclist -glibtop_get_proclist_r -glibtop_get_proclist_l -glibtop_init_proclist_p -glibtop_get_proclist_p -glibtop_init_proclist_s -glibtop_get_proclist_s </SECTION> <INCLUDE>glibtop/sem_limits.h</INCLUDE> diff --git a/include/glibtop/proclist.h b/include/glibtop/proclist.h index 7859fe08..2fdbfb44 100644 --- a/include/glibtop/proclist.h +++ b/include/glibtop/proclist.h @@ -36,22 +36,89 @@ G_BEGIN_DECLS /* You can use the folowing constants as the `which' member of * glibtop_get_proclist () to specify which processes to fetch. */ -#define GLIBTOP_KERN_PROC_ALL 0 /* all processes */ +/** + * GLIBTOP_KERN_PROC_ALL: + * + * Return information about all processes + **/ +#define GLIBTOP_KERN_PROC_ALL 0 + +/** + * GLIBTOP_KERN_PROC_PID: + * + * Return all processes with the pid which is passed in @arg. You can use this to find out whether some process still exists. + **/ #define GLIBTOP_KERN_PROC_PID 1 + +/** + * GLIBTOP_KERN_PROC_PGRP: + * + * Return all processes in the process group passed in @arg. + **/ #define GLIBTOP_KERN_PROC_PGRP 2 + +/** + * GLIBTOP_KERN_PROC_SESSION: + * + * Return all processes in the session passed in @arg. + **/ #define GLIBTOP_KERN_PROC_SESSION 3 + +/** + * GLIBTOP_KERN_PROC_TTY: + * + * Return all processes which have the controlling tty passed in @arg + * (which is interpreted as the device number). + **/ #define GLIBTOP_KERN_PROC_TTY 4 + +/** + * GLIBTOP_KERN_PROC_UID: + * + * Return all processes with the effective uid passed in @arg. + **/ #define GLIBTOP_KERN_PROC_UID 5 + +/** + * GLIBTOP_KERN_PROC_RUID: + * + * Return all processes with the real uid passed in @arg. + **/ #define GLIBTOP_KERN_PROC_RUID 6 #define GLIBTOP_KERN_PROC_MASK 15 + +/** + * GLIBTOP_EXCLUDE_IDLE: + * + * Exclude idle processes. + **/ #define GLIBTOP_EXCLUDE_IDLE 0x1000 + +/** + * GLIBTOP_EXCLUDE_SYSTEM: + * + * Exclude system (on most UNIXes root's) processes. + **/ #define GLIBTOP_EXCLUDE_SYSTEM 0x2000 + +/** + * GLIBTOP_EXCLUDE_NOTTY: + * + * Exclude processes without a controlling terminal. + **/ #define GLIBTOP_EXCLUDE_NOTTY 0x4000 typedef struct _glibtop_proclist glibtop_proclist; +/** + * glibtop_proclist: + * @number: Number of entries in the returned list. + * @total: Total size of the returned list (this equals @number * @size). + * @size: Size of a single entry in the returned list + * (this equals <type>sizeof(unsigned)</type>). + */ struct _glibtop_proclist { guint64 flags; diff --git a/include/glibtop/proctime.h b/include/glibtop/proctime.h index 5f542aea..cd22e2f5 100644 --- a/include/glibtop/proctime.h +++ b/include/glibtop/proctime.h @@ -46,26 +46,50 @@ typedef struct _glibtop_proc_time glibtop_proc_time; /* Time section */ +/** + * glibtop_proc_time: + * @start_time: Start time of process in seconds since the epoch. + * @rtime: Real time accumulated by process (should be @utime + @stime). + * @utime: User-mode CPU time accumulated by process. + * @stime: Kernel-mode CPU time accumulated by process. + * @cutime: Cumulative utime of process and reaped children. + * @cstime: Cumulative stime of process and reaped children. + * @timeout: The time (in jiffies) of the process’s next timeout. + * @it_real_value: The time (in jiffies) before the next <type>SIGALRM</type> + * is sent to the process due to an interval timer. + * @frequency: Tick frequency. + * @xcpu_utime: SMP user-mode CPU time accumulated by process. + * @xcpu_stime: SMP kernel-mode CPU time accumulated by process + * + * Process time data filled by glibtop_get_proc_time(). + * + * Under Linux the @start_time value may be wrong due to the information + * available from the kernel. + * + * The Linux kernel defines <type>INITIAL_JIFFIES</type> which implies a time + * shift. Because <type>INITIAL_JIFFIES</type> is not user-space defined, + * we cannot use it to compute an accurate @start_time. On Linux 2.6, + * <type>INITIAL_JIFFIES</type> is 300 so @start_time is + * always 3s different from the real start time of the given process. You + * may also get shift results if your system clock is not synchronised + * with your hardware clock. See <command>man hwclock</command>. + */ struct _glibtop_proc_time { + /*< private >*/ guint64 flags; - guint64 start_time; /* start time of process -- - * seconds since 1-1-70 */ - guint64 rtime; /* real time accumulated by process */ - guint64 utime; /* user-mode CPU time accumulated by process */ - guint64 stime; /* kernel-mode CPU time accumulated by process */ - guint64 cutime; /* cumulative utime of process and - * reaped children */ - guint64 cstime; /* cumulative stime of process and - * reaped children */ - guint64 timeout; /* The time (in jiffies) of the process's - * next timeout */ - guint64 it_real_value; /* The time (in jiffies) before the - * next SIGALRM is sent to the process - * due to an interval timer. */ - guint64 frequency; /* Tick frequency. */ - guint64 xcpu_utime [GLIBTOP_NCPU]; /* utime and stime for all CPUs on */ - guint64 xcpu_stime [GLIBTOP_NCPU]; /* SMP machines. */ + /*< public >*/ + guint64 start_time; + guint64 rtime; + guint64 utime; + guint64 stime; + guint64 cutime; + guint64 cstime; + guint64 timeout; + guint64 it_real_value; + guint64 frequency; + guint64 xcpu_utime [GLIBTOP_NCPU]; + guint64 xcpu_stime [GLIBTOP_NCPU]; }; diff --git a/sysdeps/common/default.c b/sysdeps/common/default.c index 71db0746..2df25ee6 100644 --- a/sysdeps/common/default.c +++ b/sysdeps/common/default.c @@ -135,18 +135,18 @@ glibtop_get_proc_uid(glibtop_proc_uid *buf, pid_t pid) /** + * SECTION:proctime + * @title: Process Time + * @short_description: Get process time information + * @stability: Stable + */ + +/** * glibtop_get_proc_time: - * @buf: - * @pid: Process id to get the user and tty information + * @buf: Returned process time information - see #glibtop_proc_time. + * @pid: Process id * - * Please note that under Linux, #start_time value may be strange. - * Linux kernel defines <type>INITIAL_JIFFIES</type> which implies a time - * shift. Because <type>INITIAL_JIFFIES</type> is not user-space defined, - * we cannot use it to compute accurate @code{start_time}. On Linux2.6, - * <type>INITIAL_JIFFIES</type> is 300 so <type>start_time</type> is - * always 3s different from real start time of the given process. You - * may also get shift results if your system clock is not synchronised - * with your hardware clock. See <command>man hwclock</command>. + * Get process time information. */ void glibtop_get_proc_time(glibtop_proc_time *buf, pid_t pid) @@ -197,6 +197,26 @@ glibtop_get_proc_map(glibtop_proc_map *buf, pid_t pid) } +/** + * SECTION:procargs + * @title: Process Arguments + * @short_description: Get process command line arguments + * @see_also: #libgtop-Process-List + * @stability: Stable + */ + +/** + * glibtop_get_proc_args: + * @buf: Struct with @size of returned string. + * @pid: Process id + * @max_len: Maximum length of string to return (use zero to get all arguments). + * + * Get process command line arguments. + * + * Returns: @pid's command line arguments separated by null bytes; the length of + * this string is returned in the @buf size field. You are required to free + * the string when done. + */ char * glibtop_get_proc_args(glibtop_proc_args *buf, pid_t pid, unsigned max_len) { @@ -204,6 +224,18 @@ glibtop_get_proc_args(glibtop_proc_args *buf, pid_t pid, unsigned max_len) } +/** + * glibtop_get_proc_argv + * @buf: Struct with @size of combined returned arguments. + * @pid: Process id + * @max_len: Maximum length of all arguments combined (use zero to get all arguments). + * + * Get process command line arguments. + * + * Returns: A NULL-terminated array of strings with all arguments of process pid + * (up to @max_len characters). Remember to <function>g_strfreev</function> + * the returned array to avoid a memory leak. + */ char ** glibtop_get_proc_argv(glibtop_proc_args *buf, pid_t pid, unsigned max_len) { @@ -211,6 +243,23 @@ glibtop_get_proc_argv(glibtop_proc_args *buf, pid_t pid, unsigned max_len) } +/** + * SECTION:proclist + * @title: Process List + * @short_description: List running processes + * @stability: Stable + */ + +/** + * glibtop_get_proclist + * @buf: Extra return information, see #glibtop_proclist. + * @which: Criteria for processes in returned list. See the <type>GLIBTOP_KERN_PROC_*</type> and <type>GLIBTOP_EXCLUDE_*</type> constants. + * @arg: Extra arguments applied to @which. Only <type>GLIBTOP_KERN_PROC_*</type> constants take arguments, see each constant definition for particular @arg description. + * + * Returns: A list of running processes or <type>NULL</type> on error. The + * returned list is allocated using <function>g_malloc</function> and must be + * freed using <function>g_free</function> to avoid a memory leak. + */ pid_t* glibtop_get_proclist(glibtop_proclist *buf, gint64 which, gint64 arg) { |