summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTristan Hill <stan@saticed.me.uk>2010-04-18 11:54:00 +0000
committerRobert Roth <robert.roth.off@gmail.com>2013-08-30 07:31:31 +0300
commit753d9abb130a0960d59762625ac2286ae48bbbdc (patch)
tree2e904898a193320cffde8813e454de6c42336047
parent3c4ddb5572b1b8b886571030540ce970ff68427e (diff)
downloadlibgtop-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.txt37
-rw-r--r--include/glibtop/proclist.h69
-rw-r--r--include/glibtop/proctime.h58
-rw-r--r--sysdeps/common/default.c69
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)
{