From: Sebastien GODARD Date: Fri, 17 Jul 2020 15:49:33 +0000 (+0200) Subject: Fix various comments in code and other files X-Git-Tag: v12.4.0~24 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c81e9f454fc454d252a5170e811211e4bcade39a;p=sysstat Fix various comments in code and other files Signed-off-by: Sebastien GODARD --- diff --git a/build/debuginfo b/build/debuginfo index c905177..c057db6 100644 --- a/build/debuginfo +++ b/build/debuginfo @@ -1,3 +1,4 @@ + Answer y to include debug information in some sysstat's commands. This is usually unneeded, so you can safely answer n. diff --git a/build/delay_range b/build/delay_range index 46af893..8ff7c78 100644 --- a/build/delay_range +++ b/build/delay_range @@ -1,4 +1,6 @@ + Tell sa2 script to wait for a random delay in the indicated range before running. This delay is expressed in seconds, and is aimed at preventing a massive I/O burst at the same time on VM sharing the same storage area. Default value is 0, meaning that sa2 will generate reports files immediately. + diff --git a/build/use-crond b/build/use-crond index 8ac5941..1e3365b 100644 --- a/build/use-crond +++ b/build/use-crond @@ -1,4 +1,6 @@ + By default sysstat uses systemd if available to start the sa1 (the data collector) and sa2 scripts periodically. Answer y if you want to use the standard cron daemon instead. Default answer is n (no). + diff --git a/common.c b/common.c index 03a1c93..93e8456 100644 --- a/common.c +++ b/common.c @@ -185,8 +185,6 @@ void init_nls(void) /* *************************************************************************** * Test whether given name is a device or a partition, using sysfs. - * This is more straightforward that using ioc_iswhole() function from - * ioconf.c which should be used only with kernels that don't have sysfs. * * IN: * @sysdev sysfs location. @@ -196,7 +194,7 @@ void init_nls(void) * /sys/block//device link exists. * * RETURNS: - * TRUE if @name is not a partition. + * TRUE if @name is a device, and FALSE if it's a partition. *************************************************************************** */ int is_device(char *sysdev, char *name, int allow_virtual) diff --git a/rd_stats.h b/rd_stats.h index 42d7e22..e05ba32 100644 --- a/rd_stats.h +++ b/rd_stats.h @@ -122,7 +122,7 @@ struct stats_cpu { /* * Structure for task creation and context switch statistics. - * The attribute (aligned(16)) is necessary so that sizeof(structure) has + * The attribute (aligned(8)) is necessary so that sizeof(structure) has * the same value on 32 and 64-bit architectures. */ struct stats_pcsw { diff --git a/sa.h b/sa.h index 85d87dd..b84f06f 100644 --- a/sa.h +++ b/sa.h @@ -786,13 +786,14 @@ struct record_header { * Indicate that activity's metrics have persistent values when devices * are registered again (this means that when the device is registered again, * the metrics pick the values they had when they had been unregistered). - * Exclusively used for CPU related statistics at the present time. + * Exclusively used for CPU related statistics at the present time + * (e.g. A_CPU and A_NET_SOFT). */ #define AO_PERSISTENT 0x08 /* * This flag should be set for every activity closing a markup used * by several activities. Used by sadf f_xml_print() functions to - * display XML output. + * display XML output, and also by f_json_print() functions to display JSON output. */ #define AO_CLOSE_MARKUP 0x10 /* @@ -895,11 +896,11 @@ struct activity { * or equal to 0. * * A value of -1 indicates that the number of items - * is a constant (and @nr is set to this value). + * is a constant (and @nr_ini is set to this value). * - * These functions are called even if corresponding activities have not - * been selected, to make sure that all items have been calculated - * (including #CPU, etc.) + * This function may be called even if corresponding activity has not + * been selected if flag AO_ALWAYS_COUNTED is set, to make sure that + * all items have been calculated (e.g. #CPU) * * The count() function may also be used to know if an activity (with * AO_DETECTED flag) can actually be collected based on the presence of @@ -964,7 +965,7 @@ struct activity { __nr_t (*f_count_new) (struct activity *, int); /* * Linked list containing item names. This is either all the different items - * found in a file for activities that have a @f_count_function() (used by sadf), + * found in a file for activities that have a @f_count_new() function (used by sadf), * or a list entered on the command line (used by sadf and sar). */ struct sa_item *item_list; @@ -1013,7 +1014,7 @@ struct activity { /* * Number of items on the system, as counted when the system is initialized. * A negative value (-1) is the default value and indicates that this number - * has still not been calculated by the f_count() function. + * has still not been calculated by the function whose index is in @f_count_index. * A value of 0 means that this number has been calculated, but no items have * been found. * A positive value (>0) has either been calculated or is a constant. @@ -1029,11 +1030,11 @@ struct activity { * been found. * A positive value (>0) has either been calculated or is a constant. * Rules: - * 1) IF @nr2 = 0 THEN @nr = 0 - * Note: If @nr = 0, then @nr2 is undetermined (may be -1, 0 or >0). - * 2) IF @nr > 0 THEN @nr2 > 0. - * Note: If @nr2 > 0 then @nr is undetermined (may be -1, 0 or >0). - * 3) IF @nr <= 0 THEN @nr2 = -1 (this is the default value for @nr2, + * 1) IF @nr2 = 0 THEN @nr_ini = 0 + * Note: If @nr_ini = 0, then @nr2 is undetermined (may be -1, 0 or >0). + * 2) IF @nr_ini > 0 THEN @nr2 > 0. + * Note: If @nr2 > 0 then @nr_ini is undetermined (may be -1, 0 or >0). + * 3) IF @nr_ini <= 0 THEN @nr2 = -1 (this is the default value for @nr2, * meaning that it has not been calculated). */ __nr_t nr2; @@ -1070,7 +1071,7 @@ struct activity { * Optional flags for activity. This is eg. used when AO_MULTIPLE_OUTPUTS * option is set. * 0x0001 - 0x0080 : Multiple outputs (eg. AO_F_MEMORY, AO_F_SWAP...) - * 0x0100 - 0x8000 : If bit set then display complete header (hdr_line) for + * 0x0100 - 0x8000 : If bit set then display complete header (@hdr_line) for * corresponding output * 0x010000+ : Optional flags */ diff --git a/sa_common.c b/sa_common.c index 0737a82..45d8e41 100644 --- a/sa_common.c +++ b/sa_common.c @@ -566,8 +566,6 @@ char *get_devname_from_sysfs(unsigned int major, unsigned int minor) /* *************************************************************************** * Get device real name if possible. - * Warning: This routine may return a bad name on 2.4 kernels where - * disk activities are read from /proc/stat. * * IN: * @major Major number of the device. diff --git a/sadc.c b/sadc.c index 40c3b46..fca0ccf 100644 --- a/sadc.c +++ b/sadc.c @@ -609,7 +609,7 @@ void write_new_cpu_nr(int ofd) * * IN: * @ofd Output file descriptor. - * @rtype Record type to write (dummy or comment). + * @rtype Record type to write (restart or comment). *************************************************************************** */ void write_special_record(int ofd, int rtype) diff --git a/sadf.h b/sadf.h index 5628d28..1a2d22b 100644 --- a/sadf.h +++ b/sadf.h @@ -50,7 +50,8 @@ #define FO_LC_NUMERIC_C 0x01 /* - * Indicate that output should stop after the header is displayed. + * Indicate that option -H may be used with corresponding format + * so that only the header is displayed. */ #define FO_HEADER_ONLY 0x02 diff --git a/sysstat.ioconf b/sysstat.ioconf index 6b806f8..eefe875 100644 --- a/sysstat.ioconf +++ b/sysstat.ioconf @@ -5,8 +5,8 @@ # # Maintained by Sebastien Godard (sysstat [at] orange.fr) # -# This file gives iostat and sadc a clue about how to find whole -# disk devices in /proc/partitions and /proc/diskstats +# This file gives iostat, sar, and sadf a clue about how to find whole +# disk devices in /proc/diskstats. # Authoritative source is: linux/Documentation/devices.txt or # linux/Documentation/admin-guide/devices.txt #