GNOME.org
 

[libgtop] proclist, procarg and proctime gtkdoc updates

commit 753d9abb130a0960d59762625ac2286ae48bbbdc
Author: Tristan Hill <stan saticed me uk>
Date:   Sun Apr 18 11:54:00 2010 +0000

    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

 doc/reference/libgtop-sections.txt |   37 -------------------
 include/glibtop/proclist.h         |   69 +++++++++++++++++++++++++++++++++++-
 include/glibtop/proctime.h         |   58 +++++++++++++++++++++---------
 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 0d99d69..ba87894 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 7859fe0..2fdbfb4 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 5f542ae..cd22e2f 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 71db074..2df25ee 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)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]