NDT-DEV email list created

Revision: 615
Author:   

Date:     Thu Sep  8 09:20:22 2011
Log:      Adding inline documentation for utility and logging related  
functions
http://code.google.com/p/ndt/source/detail?r=615

Modified:
 /branches/kkumar_code_organize/src/logging.c
 /branches/kkumar_code_organize/src/mrange.c
 /branches/kkumar_code_organize/src/usage.c
 /branches/kkumar_code_organize/src/utils.h

=======================================
--- /branches/kkumar_code_organize/src/logging.c        Sun May  8 04:04:21 
2011
+++ /branches/kkumar_code_organize/src/logging.c        Thu Sep  8 09:20:22 
2011
@@ -31,9 +31,24 @@
 static time_t             timestamp;
 static long int                  utimestamp;

-/* #ifdef HAVE_ZLIB_H */
-/* Compress snaplog, tcpdump, and cputime files to save disk space.  These  
files compress by 2 to 3 orders of
- * magnitude (100 - 1000 times).  This can save a lot of disk space.   
9/9/09  RAC
+/**
+ * Compress snaplog, tcpdump, and cputime files to save disk space.
+ * These files compress by 2 to 3 orders of
+ * magnitude (100 - 1000 times).  This can save a lot of disk space.
+ *   9/9/09  RAC
+ *
+ *  @param pointer to string containing the source file name
+ *  @return integer 0 on success, error code on failure
+ *   Possible error codes are:
+ *     -3: Failure to open source file for reading
+ *     -4: Failure to open dest file for writing
+ *     -1: Z_ERRNOd as defind by zlib library
+ *     other error codes as defined by zlib's deflateInit(0 method:
+ *             Z_MEM_ERROR if there was not enough memory,
+ *             Z_STREAM_ERROR if level is not a valid compression level,
+ *             Z_VERSION_ERROR if the zlib library version (zlib_version)
+ *  			is incompatible with the version assumed by the caller  
(ZLIB_VERSION)
+ *
  */

 int zlib_def(char *src_fn) {
@@ -106,7 +121,7 @@
 }
 /* #endif */

-/*
+/**
  * Function name: log_init
  * Description: Initializes the logging system.
  * Arguments: progname - the name of the program
@@ -136,7 +151,7 @@
   _debuglevel = debuglvl;
 }

-/*
+/**
  * Function name: log_free
  * Description: Free malloc'ed memmory after child process ends.   
Allocation without
  * a corresponding free() causes a memory leak, and the main process never  
ends so
@@ -152,7 +167,7 @@
   free(_errorhandler_nl);
 }

-/*
+/**
  * Function name: set_debuglvl
  * Description: Sets the debug level to the given value.
  * Arguments: debuglvl - the new debug level
@@ -164,7 +179,7 @@
   _debuglevel = debuglvl;
 }

-/*
+/**
  * Function name: set_logfile
  * Description: Sets the log filename.
  * Arguments: filename - new log filename
@@ -176,7 +191,7 @@
   LogFileName = filename;
 }

-/*
+/**
  * Function name: get_debuglvl
  * Description: Returns the current debug level.
  * Returns: The current debug level
@@ -188,7 +203,7 @@
   return _debuglevel;
 }

-/*
+/**
  * Function name: get_logfile
  * Description: Returns the log filename.
  * Returns: The log filename
@@ -200,7 +215,7 @@
   return LogFileName;
 }

-/*
+/**
  * Function name: get_errhandle
  * Description: Returns the error handle, that writes the messages
  *              with the new line.
@@ -213,7 +228,7 @@
   return _errorhandler_nl;
 }

-/*
+/**
  * Function name: ndt_print
  * Description: Logs the message with the given lvl.
  * Arguments: lvl - the level of the message
@@ -235,7 +250,7 @@
   va_end(ap);
 }

-/*
+/**
  * Function name: ndt_println
  * Description: Logs the message with the given lvl. New line character
  *              is appended to the error stream.
@@ -304,6 +319,7 @@
  * Function name get_YYYY
  * Description: Returns a character string YYYY for the current year
  * Author: Rich Carlson - 6/29/09
+ * @param Pointer to the string indicating the year
  */

 void
@@ -325,6 +341,7 @@
  * Function name get_MM
  * Description: Returns a character string MM for the current year
  * Author: Rich Carlson - 6/29/09
+ * @param Pointer to the string indicating month
  */

 void
@@ -349,6 +366,7 @@
  * Function name get_DD
  * Description: Returns a character string DD for the current year
  * Author: Rich Carlson - 6/29/09
+ * @param Pointer to the string indicating day
  */

 void
@@ -374,6 +392,7 @@
  *             used to create snaplog and trace file names
  * Returns: character string with ISO time string.
  * Author: Rich Carlson - 5/6/09
+ * @param Pointer to the string indicating ISO time
  */

 char *
@@ -424,140 +443,201 @@
 return isoTime;
 }

-/* Write meta data out to log file.  This file contains details and
+/**
+ * Write meta data out to log file.  This file contains details and
  * names of the other log files.
+ * @param compress integer flag indicating whether log file compression
+ *                     is enabled
+ * @param cputime integer flag indicating if cputime trace logging is on
+ * @param snaplog integer flag indicating if snaplogging is enabled
+ * @param tcpdump integer flag indicating if tcpdump trace logging is on
+ *
  * RAC 7/7/09
  */

 void writeMeta(int compress, int cputime, int snaplog, int tcpdump)
 {
-    FILE *fp;
-    char tmpstr[256], dir[128], tmp2str[256];
-    char isoTime[64], filename[256];
-    size_t tmpstrlen=sizeof(tmpstr);
-    socklen_t len;
-    DIR *dp;
-
-/* Get the clients domain name and same in metadata file
- * changed to use getnameinfo 7/24/09
- * RAC 7/7/09
- */
-
+       FILE * fp;
+       char tmpstr[256], dir[128], tmp2str[256];
+       char isoTime[64], filename[256];
+       size_t tmpstrlen = sizeof(tmpstr);
+       socklen_t len;
+       DIR *dp;
+
+       /* Get the clients domain name and same in metadata file
+        * changed to use getnameinfo 7/24/09
+        * RAC 7/7/09
+        */
+
+       // get socketaddr size based on whether IPv6/IPV4 address was used
 #ifdef AF_INET6
-    if (meta.family == AF_INET6)
-       len = sizeof(struct sockaddr_in6);
+       if (meta.family == AF_INET6)
+               len = sizeof(struct sockaddr_in6);
 #endif
-    if (meta.family == AF_INET)
-       len = sizeof(struct sockaddr_in);
-
-    if (getnameinfo((struct sockaddr *)&meta.c_addr, len, tmpstr,  
tmpstrlen,
-       NULL, 0, NI_NAMEREQD))
-       memcpy(meta.client_name, "No FQDN name", 12);
-    else {
-       log_println(2, "extracting hostname %s", tmpstr);
-       memcpy(meta.client_name, tmpstr, strlen(tmpstr));
-    }
-
-    memset(tmpstr, 0, tmpstrlen);
-    strncpy(tmpstr, DataDirName, strlen(DataDirName));
-    if ((dp = opendir(tmpstr)) == NULL && errno == ENOENT)
-            mkdir(tmpstr, 0755);
-    closedir(dp);
-    get_YYYY(dir);
-    strncat(tmpstr, dir, 4);
-    if ((dp = opendir(tmpstr)) == NULL && errno == ENOENT)
-            mkdir(tmpstr, 0755);
-    closedir(dp);
-    strncat(tmpstr, "/", 1);
-    get_MM(dir);
-    strncat(tmpstr, dir, 2);
-    if ((dp = opendir(tmpstr)) == NULL && errno == ENOENT)
-            mkdir(tmpstr, 0755);
-    closedir(dp);
-    strncat(tmpstr, "/", 1);
-    get_DD(dir);
-    strncat(tmpstr, dir, 2);
-    if ((dp = opendir(tmpstr)) == NULL && errno == ENOENT)
-            mkdir(tmpstr, 0755);
-    closedir(dp);
-    memcpy(tmp2str, tmpstr, tmpstrlen);
-    strncat(tmpstr, "/", 1);
-    sprintf(dir, "%s_%s:%d.meta", get_ISOtime(isoTime), meta.client_ip,  
meta.ctl_port);
-    strncat(tmpstr, dir, strlen(dir));
-
-    log_println(6, "Should compress snaplog and tcpdump files  
compress=%d", compress);
-/* #ifdef HAVE_ZLIB_H */
-    if (compress == 1) {
-	log_println(5, "Compression is enabled, compress all files in '%s'  
basedir", tmp2str);
-      if (snaplog) {
-       memset(filename, 0, 256);
-       sprintf(filename, "%s/%s", tmp2str, meta.c2s_snaplog);
-       if (zlib_def(filename) != 0)
-           log_println(5, "compression failed");
-       else
-         strncat(meta.c2s_snaplog, ".gz", 3);
-       memset(filename, 0, 256);
-       sprintf(filename, "%s/%s", tmp2str, meta.s2c_snaplog);
-       if (zlib_def(filename) != 0)
-           log_println(5, "compression failed");
-       else
-         strncat(meta.s2c_snaplog, ".gz", 3);
-      }
-      if (tcpdump) {
-       memset(filename, 0, 256);
-       sprintf(filename, "%s/%s", tmp2str, meta.c2s_ndttrace);
-       if (zlib_def(filename) != 0)
-           log_println(5, "compression failed");
-       else
-         strncat(meta.c2s_ndttrace, ".gz", 3);
-       memset(filename, 0, 256);
-       sprintf(filename, "%s/%s", tmp2str, meta.s2c_ndttrace);
-       if (zlib_def(filename) != 0)
-           log_println(5, "compression failed");
-       else
-         strncat(meta.s2c_ndttrace, ".gz", 3);
-      }
-      if (cputime) {
-       memset(filename, 0, 256);
-       sprintf(filename, "%s/%s", tmp2str, meta.CPU_time);
-       if (zlib_def(filename) != 0)
-           log_println(5, "compression failed");
-       else
-         strncat(meta.CPU_time, ".gz", 3);
-      }
-      else
-	log_println(5, "Zlib compression disabled, log files will not be  
compressed");
-    }
-/* #endif */
-
-    fp = fopen(tmpstr,"w");
-    if (fp == NULL) {
-        log_println(1, "Unable to open metadata log file, continuing on  
without logging");
-    }
-    else {
-        log_println(5, "Opened '%s' metadata log file", tmpstr);
-        fprintf(fp, "Date/Time: %s\n", meta.date);
-        fprintf(fp, "c2s_snaplog file: %s\n", meta.c2s_snaplog);
-        fprintf(fp, "c2s_ndttrace file: %s\n", meta.c2s_ndttrace);
-        fprintf(fp, "s2c_snaplog file: %s\n", meta.s2c_snaplog);
-        fprintf(fp, "s2c_ndttrace file: %s\n", meta.s2c_ndttrace);
-        fprintf(fp, "cputime file: %s\n", meta.CPU_time);
-        fprintf(fp, "server IP address: %s\n", meta.server_ip);
-        fprintf(fp, "server hostname: %s\n", meta.server_name);
-        fprintf(fp, "server kernel version: %s\n", meta.server_os);
-        fprintf(fp, "client IP address: %s\n", meta.client_ip);
-        fprintf(fp, "client hostname: %s\n", meta.client_name);
-        fprintf(fp, "client OS name: %s\n", meta.client_os);
-        fprintf(fp, "client_browser name: %s\n", meta.client_browser);
-        fprintf(fp, "Summary data: %s\n", meta.summary);
-        if (meta.additional) {
-          fprintf(fp, " * Additional data:\n");
-          struct metaentry* entry = meta.additional;
-          while (entry) {
-            fprintf(fp, "%s: %s\n", entry->key, entry->value);
-            entry = entry->next;
-          }
-        }
-        fclose(fp);
-    }
-}
+       if (meta.family == AF_INET)
+               len = sizeof(struct sockaddr_in);
+
+	// Look up the host name and service name information for given struct  
sockaddress and length
+       if (getnameinfo((struct sockaddr *) &meta.c_addr, len, tmpstr, 
tmpstrlen,
+                       NULL, 0, NI_NAMEREQD))
+       {
+               // No fully qualified domain name
+               memcpy(meta.client_name, "No FQDN name", 12);
+       }
+       else
+       {
+               // copy client's hostname into meta structure
+               log_println(2, "extracting hostname %s", tmpstr);
+               memcpy(meta.client_name, tmpstr, strlen(tmpstr));
+       }
+
+       // reset tmpstr
+       memset(tmpstr, 0, tmpstrlen);
+
+	// The following section of code creates a log directory to record meta  
data,
+	// if one is not already present with the details needed. The log file  
location,
+       // and name themselves record the year, month, date, time and client 
name.
+	// The "primary" location for this log file is obtained as a command line  
option
+	// from the user, or is the default location of BASE_DIR+LOG_DIR of the  
NDT installation
+
+       strncpy(tmpstr, DataDirName, strlen(DataDirName));
+       // Open the directory or create one if not yet present
+       if ((dp = opendir(tmpstr)) == NULL && errno == ENOENT)
+               mkdir(tmpstr, 0755);
+       closedir(dp); // close opened directory
+       get_YYYY(dir); // get current year
+       strncat(tmpstr, dir, 4);
+       if ((dp = opendir(tmpstr)) == NULL && errno == ENOENT)
+               mkdir(tmpstr, 0755); // create directory with year appended
+       closedir(dp); // close the opened directory
+       strncat(tmpstr, "/", 1);
+       get_MM(dir); // get month info
+       strncat(tmpstr, dir, 2); // append month info to the directory name
+       if ((dp = opendir(tmpstr)) == NULL && errno == ENOENT)
+               mkdir(tmpstr, 0755);
+       closedir(dp);
+       strncat(tmpstr, "/", 1);
+       get_DD(dir); // get date
+       strncat(tmpstr, dir, 2); // append date info to directory name
+       if ((dp = opendir(tmpstr)) == NULL && errno == ENOENT)
+               mkdir(tmpstr, 0755);
+       closedir(dp);
+
+       // end block creating log directory
+
+
+	memcpy(tmp2str, tmpstr, tmpstrlen); // tmp2str now contains the dir name  
intended
+       // tmpstr will henceforth refer to the log file's name
+       strncat(tmpstr, "/", 1);
+       sprintf(dir, "%s_%s:%d.meta", get_ISOtime(isoTime), meta.client_ip,
+                       meta.ctl_port); // now get ISO time, the client's 
name and port
+       strncat(tmpstr, dir, strlen(dir)); // append above details to log 
filename
+
+
+       log_println(6, "Should compress snaplog and tcpdump files 
compress=%d",
+                       compress);
+       /* #ifdef HAVE_ZLIB_H */
+
+       // If compression is enabled, compress files in the "log" directory
+       if (compress == 1)
+       {
+               log_println(5,
+                               "Compression is enabled, compress all files in 
'%s' basedir",
+                               tmp2str);
+               if (snaplog)
+               { // if snaplog is enabled, compress those into .gz formats
+
+                       // Try compressing C->S test snaplogs
+                       memset(filename, 0, 256);
+                       sprintf(filename, "%s/%s", tmp2str, meta.c2s_snaplog);
+                       if (zlib_def(filename) != 0)
+                               log_println(5, "compression failed");
+                       else
+                               strncat(meta.c2s_snaplog, ".gz", 3);
+
+                       // Try compressing S->C test snaplogs
+                       memset(filename, 0, 256);
+                       sprintf(filename, "%s/%s", tmp2str, meta.s2c_snaplog);
+                       if (zlib_def(filename) != 0)
+                               log_println(5, "compression failed");
+                       else
+                               strncat(meta.s2c_snaplog, ".gz", 3);
+               }
+
+               // If tcpdump file writing is enabled, compress those
+               if (tcpdump)
+               {
+
+                       // Try compressing C->S test tcpdump
+                       // the tcpdump file extension is as specified
+                       memset(filename, 0, 256);
+                       sprintf(filename, "%s/%s", tmp2str, 
meta.c2s_ndttrace);
+                       if (zlib_def(filename) != 0)
+                               log_println(5, "compression failed");
+                       else
+                               strncat(meta.c2s_ndttrace, ".gz", 3);
+
+                       // Try compressing S->C test tcpdumps
+                       memset(filename, 0, 256);
+                       sprintf(filename, "%s/%s", tmp2str, 
meta.s2c_ndttrace);
+                       if (zlib_def(filename) != 0)
+                               log_println(5, "compression failed");
+                       else
+                               strncat(meta.s2c_ndttrace, ".gz", 3);
+               }
+
+               // If writing "cputime" file is enabled, compress those log 
files too
+               if (cputime)
+               {
+                       memset(filename, 0, 256);
+                       sprintf(filename, "%s/%s", tmp2str, meta.CPU_time);
+                       if (zlib_def(filename) != 0)
+                               log_println(5, "compression failed");
+                       else
+                               strncat(meta.CPU_time, ".gz", 3);
+               }
+               else
+                       log_println(
+                                       5,
+                                       "Zlib compression disabled, log files will 
not be compressed");
+       }
+       /* #endif */
+
+       // Try logging metadata into the metadata logfile
+       fp = fopen(tmpstr, "w");
+       if (fp == NULL)
+       { // error, unable to open file in write mode
+               log_println(
+                               1,
+                               "Unable to open metadata log file, continuing on 
without logging");
+       }
+       else
+       {
+               log_println(5, "Opened '%s' metadata log file", tmpstr);
+               fprintf(fp, "Date/Time: %s\n", meta.date);
+               fprintf(fp, "c2s_snaplog file: %s\n", meta.c2s_snaplog);
+               fprintf(fp, "c2s_ndttrace file: %s\n", meta.c2s_ndttrace);
+               fprintf(fp, "s2c_snaplog file: %s\n", meta.s2c_snaplog);
+               fprintf(fp, "s2c_ndttrace file: %s\n", meta.s2c_ndttrace);
+               fprintf(fp, "cputime file: %s\n", meta.CPU_time);
+               fprintf(fp, "server IP address: %s\n", meta.server_ip);
+               fprintf(fp, "server hostname: %s\n", meta.server_name);
+               fprintf(fp, "server kernel version: %s\n", meta.server_os);
+               fprintf(fp, "client IP address: %s\n", meta.client_ip);
+               fprintf(fp, "client hostname: %s\n", meta.client_name);
+               fprintf(fp, "client OS name: %s\n", meta.client_os);
+               fprintf(fp, "client_browser name: %s\n", meta.client_browser);
+               fprintf(fp, "Summary data: %s\n", meta.summary);
+               if (meta.additional)
+               {
+                       fprintf(fp, " * Additional data:\n");
+                       struct metaentry* entry = meta.additional;
+                       while (entry)
+                       {
+                               fprintf(fp, "%s: %s\n", entry->key, 
entry->value);
+                               entry = entry->next;
+                       }
+               }
+               fclose(fp);
+       }
+}
=======================================
--- /branches/kkumar_code_organize/src/mrange.c Tue Oct 13 07:49:45 2009
+++ /branches/kkumar_code_organize/src/mrange.c Thu Sep  8 09:20:22 2011
@@ -14,9 +14,9 @@
 #include "logging.h"

 typedef struct range {
-  int min;
-  int max;
-  struct range *next;
+  int min; /**< lower end of the range */
+  int max;  /**< upper end of the range */
+  struct range *next;  /**< pointer to the next range member */
 } Range;

 static Range* mrange_root;
@@ -44,11 +44,14 @@
     return 1;
   }
   strcpy(tmp, text);
+  // tokenize based on a "," character.
+  // An example of the string : 2003:3000,4000:5000
   ptr = strtok(tmp, ",");
-  while (ptr != NULL) {
-    if ((sptr = strchr(ptr, ':')) != NULL) {
+  while (ptr != NULL) { // tokens found
+    if ((sptr = strchr(ptr, ':')) != NULL) { // also found a ":" character,
+                                                                             
   // with sptr pointing to its location
       *sptr++ = 0;
-      if (strchr(sptr, ':') != NULL) {
+      if (strchr(sptr, ':') != NULL) { // should not find any more range
         return 1;
       }
     }
@@ -62,19 +65,25 @@
     if (*ptr == 0) {
       ptr = "1";
     }
-    if (check_rint(ptr, &mr_ptr->min, 1, 65535)) {
+    // Check if the input string is within range and store
+    // result as "minimum"
+    // For ex: Is 2003 in a string like "2003:4000" within integer range ?
+    // If not, free the memory allocated to store the range and return
+    if (check_rint(ptr, &mr_ptr->min, 1, MAX_TCP_PORT)) {
       free(mr_ptr);
       return 1;
     }
     if (*sptr == 0) {
-      sptr = "65535";
-    }
-    if (check_rint(sptr, &mr_ptr->max, 1, 65535)) {
+      sptr = MAX_TCP_PORT_STR;
+    }
+    // now validate if "maximum" is within range  and store
+    // result as "maximum"
+    if (check_rint(sptr, &mr_ptr->max, 1, MAX_TCP_PORT)) {
       free(mr_ptr);
-      return 1;
+      return 1; // if invalid range, free allocated memory and return
     }
     mr_ptr->next = mrange_root;
-    mrange_root = mr_ptr;
+    mrange_root = mr_ptr; // ready to point to next member
     ptr = strtok(NULL, ",");
   }
   free(mr_ptr);
@@ -82,12 +91,15 @@
 }

 /*
- * Function name: mrange_parse
- * Description: Parses the string argument and adds the ranges to
- *              the free pool.
- * Arguments: text - the string containing ranges
- * Returns: 0 - the string was parsed correctly
- *          1 - there was a syntax error in the string
+ * Function name: mrange_next
+ * Description: Checks if a given number (passed in as string argument)
+ *  is available as a valid integer in the free pool. For example,
+ *  if we construct a list of valid port ranges, then this function
+ *  could be used to parse through the list to check for a usable port
+ *
+ * Arguments: text - the string containing port
+ * Returns: char* containing 0 if the argument port is invalid
+ *          char* containing the port number if port is valid
  */

 char*
@@ -98,16 +110,17 @@

   assert(port);

-  if (check_rint(port, &val, 0, 65535)) {
+  if (check_rint(port, &val, 0, MAX_TCP_PORT)) { // check if valid
     log_println(0, "WARNING: invalid port number");
-    sprintf(port, "0");
+    sprintf(port, RESERVED_PORT);
     return port;
   }
   val++;
-  while (val < 65536) {
+  while (val <= MAX_TCP_PORT) { // Maximum port number not exceeded
     ptr = mrange_root;
-    while (ptr != NULL) {
-      if ((val >= ptr->min) && (val <= ptr->max)) {
+    while (ptr != NULL) { // While there is some data
+      if ((val >= ptr->min) && (val <= ptr->max)) { // check range
+                                                                             
                  // and return port if valid
         sprintf(port, "%d", val);
         return port;
       }
@@ -115,6 +128,6 @@
     }
     val++;
   }
-  sprintf(port, "0");
+  sprintf(port, RESERVED_PORT);
   return port;
 }
=======================================
--- /branches/kkumar_code_organize/src/usage.c  Wed Sep  9 14:00:45 2009
+++ /branches/kkumar_code_organize/src/usage.c  Thu Sep  8 09:20:22 2011
@@ -68,7 +68,7 @@
     printf("  -T, --refresh #time    - specify the refresh time of the  
admin page\n");
     printf("  --mrange #range        - set the port range used in  
multi-test mode\n");
     printf("                           Note: this enables multi-test  
mode\n");
-    printf("  -A, --adminfile #FN    - specify atlernate filename for  
Admin web page\n");
+    printf("  -A, --adminfile #FN    - specify alternate filename for  
Admin web page\n");
     printf("                           Note: this doesn't  
enable 'adminview'\n");
     printf("  -L, --log_dir DIR      - specify the base directory for  
snaplog and tcpdump files\n");
     printf("                           (default %s/serverdata)\n",  
BASEDIR);
=======================================
--- /branches/kkumar_code_organize/src/utils.h  Sun Aug 19 03:26:07 2007
+++ /branches/kkumar_code_organize/src/utils.h  Thu Sep  8 09:20:22 2011
@@ -19,3 +19,10 @@

 #endif

+// Numbers 1 and 65535 are used in mrange.c for determining "valid" ranges
+// While the methods could be used for any "range" comparison,
+// NDT uses them for porta
+#define MAX_TCP_PORT 65535
+#define MIN_TCP_PORT 1
+#define RESERVED_PORT "0"
+#define MAX_TCP_PORT_STR "65535"