Adds all the doxygen documentation for the new ompi_sys_info, ompi_create_dirpath, ompi_os_path, and ompi_session_dir_init functions. Adds the rte directories to the svn repository, along with the openmpi and ompi_session_dir_init routines. The rte functions are not ready for use yet, but they aren't callable by anyone either, so this shouldn't pose a problem.

The utility functions have all been checked by David and Tim, and Jeff before them. They have unit tests in the test trunk.

This commit was SVN r1165.

src/rte/universe/Makefile.am

@@ -0,0 +1,40 @@
+# -*- makefile -*-
+#
+# $HEADER$
+#
+
+include $(top_srcdir)/config/Makefile.options
+
+AM_CPPFLAGS = \
+            -DLAM_PREFIX="\"$(prefix)\"" \
+            -DLAM_BINDIR="\"$(bindir)\"" \
+            -DLAM_LIBDIR="\"$(libdir)\"" \
+            -DLAM_INCDIR="\"$(includedir)\"" \
+            -DLAM_PKGLIBDIR="\"$(pkglibdir)\"" \
+            -DLAM_SYSCONFDIR="\"$(sysconfdir)\"" \
+            -DLAM_CONFIGURE_USER="\"@LAM_CONFIGURE_USER@\"" \
+            -DLAM_CONFIGURE_HOST="\"@LAM_CONFIGURE_HOST@\"" \
+            -DLAM_CONFIGURE_DATE="\"@LAM_CONFIGURE_DATE@\""
+
+libs = $(top_builddir)/src/libmpi.la
+
+bin_PROGRAMS = openmpi
+openmpi_SOURCES = \
+        openmpi.h \
+        os_session_dir.c \
+        openmpi.c 
+
+openmpi_LDADD = \
+        $(libs) \
+        $(LIBMPI_EXTRA_LIBS) \
+        $(LIBLAM_EXTRA_LIBS) \
+        $(top_builddir)/src/util/os_path.lo \
+        $(top_builddir)/src/util/os_create_dirpath.lo \
+        $(top_builddir)/src/util/sys_info.lo
+
+openmpi_DFLAGS = $(LIBMPI_EXTRA_LDFLAGS) $(LIBLAM_EXTRA_LDFLAGS)
+openmpi_DEPENDENCIES = $(libs) \
+                       $(openmpi_LDADD)
+
+clean-local:
+	test -z "$(LAM_CXX_TEMPLATE_REPOSITORY)" || $(RM) -rf $(LAM_CXX_TEMPLATE_REPOSITORY)

src/rte/universe/openmpi.c

@@ -0,0 +1,111 @@
+/*
+openmpi.c - main program for spawning persistent universe.
+
+ --------------------------------------------------------------------------
+
+ Authors:	Ralph H. Castain <rhc@lanl.gov>
+
+ --------------------------------------------------------------------------
+
+*/
+
+#include "lam_config.h"
+
+#include <stdio.h>
+#include <string.h>
+
+#include "util/sys_info.h"
+#include "util/cmd_line.h"
+
+#include "rte/universe/os_session_dir.h"
+#include "rte/universe/openmpi.h"
+
+/**
+* Parse command line options and check for validity. Track which
+* ones have been provided to assess completeness of information.
+*
+* @retval OMPI_SUCCESS if all options provided are valid
+* @retval OMPI_ERROR if any option is not valid. Invalid options
+* will be reported to user but will not terminate processing.
+*/
+
+ompi_universe_t universe = {.name = NULL,
+			    .pid = -1,
+			    .session_file = NULL,
+                            .persistence = false,
+			    .web_server = false,
+			    .console_connected = false
+};
+
+
+int main(int argc, char *argv[])
+{
+    lam_cmd_line_t *cmd_line = NULL;
+    char *tmpdir_option = NULL;
+
+    cmd_line = lam_cmd_line_create();
+    if (NULL == cmd_line) {
+        fprintf(stderr,"openmpi: Command line handle could not be created - please report error to bugs@open-mpi.org"); 
+        exit(errno);
+    }
+
+    lam_cmd_line_make_opt(cmd_line, 'v', "version", 0,
+                        "Show version of Open MPI and this program");
+    lam_cmd_line_make_opt(cmd_line, 'u', "universe", 1,
+                        "User specified name for universe");
+    lam_cmd_line_make_opt(cmd_line, 't', "tmpdir", 1,
+			  "Temp directory to be used by universe");
+    lam_cmd_line_make_opt(cmd_line, 'w', "webserver", 1,
+                          "Web server available");
+
+    if ((LAM_SUCCESS != lam_cmd_line_parse(cmd_line, false, argc, argv)) ||
+        lam_cmd_line_is_taken(cmd_line, "help") || 
+	lam_cmd_line_is_taken(cmd_line, "h")) {
+        fprintf(stderr, "...showing openmpi help message...\n");
+        exit(1);
+    }
+
+    /* get universe name and store it, if user specified it */
+    /* otherwise, stick with default name */
+    if (lam_cmd_line_is_taken(cmd_line, "universe")) {
+	if (NULL == lam_cmd_line_get_param(cmd_line, "universe", 0, 0)) {
+	    fprintf(stderr, "error retrieving universe name - please report error to bugs@open-mpi.org\n");
+		exit(1);
+        }
+        universe.name = strdup(lam_cmd_line_get_param(cmd_line, "universe", 0, 0));
+    } else {
+	universe.name = strdup("ompi-default-universe");
+    }
+
+    /* get the pid and store it for later use */
+    universe.pid = getpid();
+
+    /* get the temporary directory name for the session directory, if provided on command line */
+    if (lam_cmd_line_is_taken(cmd_line, "tmpdir")) {
+	if (NULL == lam_cmd_line_get_param(cmd_line, "tmpdir", 0, 0)) {
+	    fprintf(stderr, "error retrieving tmpdir name - please report error to bugs@open-mpi.org\n");
+	    exit(1);
+	}
+	tmpdir_option = strdup(lam_cmd_line_get_param(cmd_line, "tmpdir", 0, 0));
+    }
+
+    /* get the system information */
+    ompi_system_info.init = false;
+    ompi_sys_info();
+    if (!ompi_system_info.init) {
+	fprintf(stderr, "Couldn't get system information\n");
+	exit(1);
+    }
+
+    /* create the session directory */
+    if (LAM_ERROR == ompi_session_dir_init(tmpdir_option, "test-universe")) {
+	fprintf(stderr, "error creating session directory - please report error to bugs@open-mpi.org");
+	exit(1);
+    }
+
+    /* store this session information */
+    /* first, check to see if we are rejoining an existing session */
+    /* yes, so read info from file */
+    /* no existing session, so create the file */
+    return(0);
+}

src/rte/universe/openmpi.h

@@ -0,0 +1,26 @@
+/*
+ * $HEADER$
+ */
+
+#include <sys/param.h>
+#include <stdlib.h>
+#include <stdbool.h>
+
+/* Define the structures underlying the Open MPI universe system */
+
+struct ompi_universe_t {
+    char *name;
+    pid_t pid;
+    char *session_file;
+    bool persistence;
+    bool web_server;
+    bool console_connected;
+};
+typedef struct ompi_universe_t ompi_universe_t;
+
+#ifndef MAXHOSTNAMELEN
+#define MAXHOSTNAMELEN 256
+#endif
+
+#define OMPI_RIDICULOUS_NAMELEN 1024
+

src/rte/universe/os_session_dir.c

@@ -0,0 +1,224 @@
+/*
+ * $HEADER$
+ *
+ *  $Id: tmpdir.c $
+ *
+ *  Function: - 
+ */
+
+#include <stdio.h>
+#include <pwd.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/param.h>
+#include <sys/types.h>
+#include <sys/stat.h>
+/*
+#include <sys/socket.h>
+#include <netdb.h>      MAXHOSTNAMELEN in Solaris
+#include <unistd.h>
+#include <errno.h>
+#include <dirent.h>
+   
+#include <lamdebug.h>
+#include <laminternal.h>
+#include <terror.h>
+#include <typical.h>
+#include <etc_misc.h>
+*/
+
+#include "lam_config.h"
+#include "include/constants.h"
+
+#include "util/sys_info.h"
+#include "util/os_path.h"
+#include "util/os_create_dirpath.h"
+
+static char *ompi_get_prefix(char *prefix);
+static int ompi_check_dir(char *directory);
+
+#define OMPI_DEFAULT_TMPDIR "tmp"
+
+static int ompi_check_dir(char *directory)
+{
+    struct stat buf;
+    mode_t my_mode = S_IRWXU;  /* at the least, I need to be able to do anything */
+    mode_t mode_all = S_IRWXU | S_IRWXG | S_IRWXO;  /* permissions for ompi-sessions directory - open to all */
+
+    if (0 == stat(directory, &buf)) { /* exists - check access */
+        if ((buf.st_mode & my_mode) == my_mode) { /* okay, I can work here */
+            return(LAM_SUCCESS);
+        }
+    }
+    return(ompi_os_create_dirpath(directory, mode_all)); /* try to create it, but ensure open to all */
+}
+
+static char *ompi_get_prefix(char *prefix)
+{
+    char *tmpprefix=NULL, *tmp=NULL;
+    char *sessions=NULL;
+
+    sessions = strdup("openmpi-sessions");
+
+    if (NULL != prefix) {
+	tmpprefix = strdup(ompi_os_path(false, prefix, sessions, NULL)); /* make sure it's an absolute pathname */
+	if (LAM_SUCCESS == ompi_check_dir(tmpprefix)) { /* check for existence and access, or create it */
+	    free(sessions);
+	    return(tmpprefix);
+	}
+	else {
+	    return(NULL); /* user specified location, but we can't access it nor create it */
+	}
+    }
+ 
+    if (NULL != getenv("LAM_PREFIX_ENV")) {
+	tmp = strdup(getenv("LAM_PREFIX_ENV"));
+	tmpprefix = strdup(ompi_os_path(false, tmp, sessions, NULL));
+	if (LAM_SUCCESS == ompi_check_dir(tmpprefix)) { /* check for existence and access, or create it */
+	    free(tmp);
+	    free(sessions);
+	    return(tmpprefix);
+	}
+    }
+   if (tmp != NULL) {
+        free(tmp);
+    }
+    if (tmpprefix != NULL) {
+        free(tmpprefix);
+    }
+
+    if (NULL != getenv("TMPDIR")) {
+	tmp = strdup(getenv("TMPDIR"));
+	tmpprefix = strdup(ompi_os_path(false, tmp, sessions, NULL));
+	if (LAM_SUCCESS == ompi_check_dir(tmpprefix)) { /* check for existence and access, or create it */
+	    free(tmp);
+	    free(sessions);
+	    return(tmpprefix);
+	}
+    }
+    if (tmp != NULL) {
+        free(tmp);
+    }
+    if (tmpprefix != NULL) {
+        free(tmpprefix);
+    }
+
+    if (NULL != getenv("TMP")) {
+	tmp = strdup(getenv("TMP"));
+	tmpprefix = strdup(ompi_os_path(false, tmp, sessions, NULL));
+	if (LAM_SUCCESS == ompi_check_dir(tmpprefix)) { /* check for existence and access, or create it */
+	    free(tmp);
+	    free(sessions);
+	    return(tmpprefix);
+	}
+    }
+    if (tmp != NULL) {
+        free(tmp);
+    }
+    if (tmpprefix != NULL) {
+        free(tmpprefix);
+    }
+
+    if (NULL != getenv("HOME")) {
+	tmp = strdup(getenv("HOME"));
+	tmpprefix = strdup(ompi_os_path(false, tmp, sessions, NULL));
+	if (LAM_SUCCESS == ompi_check_dir(tmpprefix)) { /* check for existence and access, or create it */
+	    free(tmp);
+	    free(sessions);
+	    return(tmpprefix);
+	}
+    }
+    if (tmp != NULL) {
+        free(tmp);
+    }
+    if (tmpprefix != NULL) {
+        free(tmpprefix);
+    }
+
+    tmp = strdup(OMPI_DEFAULT_TMPDIR);
+    tmpprefix = strdup(ompi_os_path(false, tmp, sessions, NULL));
+    if (LAM_SUCCESS == ompi_check_dir(tmpprefix)) { /* check for existence and access, or create it */
+	free(tmp);
+	free(sessions);
+	return(tmpprefix);
+    }
+
+    /* possibilities exhausted - time to surrender! */
+    if (tmp != NULL) {
+        free(tmp);
+    }
+    if (tmpprefix != NULL) {
+        free(tmpprefix);
+    }
+    if (sessions != NULL) {
+        free(sessions);
+    }
+    return(NULL);
+}
+
+
+/*
+ *  ompi_session_dir_init
+ *
+ *  Function: - set up tmpdir for Open MPI to store stuff
+ *      - creates directory, with "good" perms
+ *  Accepts:  - prefix to use, if provided by user
+ *  Returns:  - LAM_SUCCESS or LAM_ERROR
+ *      Notes:           - directory in form of:
+ *                         <prefix>/openmpi-sessions/uid
+ */
+int ompi_session_dir_init(char *prefix, char *universe)
+{
+
+    char *tmpsuffix = NULL;
+    char *tmpprefix = NULL;
+    char *name;
+
+    /* check if universe is specified - if not, error out */
+    if (NULL == universe) {
+	return(LAM_ERROR);
+    }
+
+    /* locate the ompi-sessions directory - create it if it doesn't exist */
+    if (NULL == (tmpprefix = ompi_get_prefix(prefix))) { /* couldn't find nor create the sessions directory */
+	return (LAM_ERROR);
+    }
+
+    /* set up the name of the user's session directory, which is prefix/<uid>, and try to create it */
+    name = ompi_os_path(false, tmpprefix, ompi_system_info.user, universe, NULL);
+    if (LAM_ERROR == ompi_os_create_dirpath(name, S_IRWXU)) { /* couldn't create the user directory */
+	free(tmpprefix);
+	free(name);
+	return(LAM_ERROR);
+    }
+
+    /* store the sessions directory information */
+    ompi_system_info.session_dir = strdup(name);
+
+    /* set up the prefix environment */
+    /* after careful consideration, it was decided not to put this
+     * back in the environment.  Processes that inherit from this
+     * process will have the right things to get the same answer.  But
+     * this became a major issue all around, because the session
+     * prefix is not always the same across nodes and setting the env
+     * caused MPIRUN to push the env variable out, which was just
+     * causing major badness. 
+     */
+
+    /* may need to include the ability to detect if the system is automatically putting a suffix
+     * on our files. Not sure what this means yet, so nothing is implemented at this time.
+     */
+
+    /* clean up */
+    if (tmpprefix != NULL) {
+	free(tmpprefix);
+    }
+    if (tmpsuffix != NULL) {
+	free(tmpsuffix);
+    }
+    if (name != NULL) {
+	free(name);
+    }
+
+    return(LAM_SUCCESS);
+}

src/rte/universe/os_session_dir.h

@@ -0,0 +1,85 @@
+/*
+ * $HEADER$
+ */
+/** @file:
+ *
+ * Creates Open MPI session directory.
+ *
+ * The ompi_session_dir_init() function creates a temporary directory that is
+ * used by the Open MPI system for storing system-critical information. For a given
+ * system and user, the function attempts to create a directory that will be used
+ * to independently house information for multiple universes, as the user creates
+ * them. Thus, the function creates a directory tree of the form:
+ *
+ * \par \em <prefix-dir>
+ * An absolute path that identifies a temporary directory that is
+ * read-write-execute accessible to everyone. The function first checks to see if
+ * the user has specified the <prefix> directory on the command line. If so, then the
+ * function will use that <prefix> if the access permissions are correct, or will return
+ * an error condition if not - the function will not search for alternative locations
+ * if the user provides the <prefix> name.
+ *
+ * \par
+ * If the <prefix> is not provided by the user, the function searches for a suitable 
+ * directory in a specific order, taking the first option that meets the access
+ * permission requirement, using: (a) the "LAM_PREFIX_ENV" environment variable;
+ * (b) the "TMPDIR" environment variable; (c) the "TMP" environment variable; and
+ * (d) the "HOME" environment variable, appended with a "tmp" directory. If none of
+ * those environmental variables have been defined and/or the function was unable
+ * to create a suitable directory within any of them, then the function tries to use a default
+ * location of "/tmp", where the "/" represents the top-level directory of the
+ * local system. If none of these options are successful, the function returns an
+ * error code.
+ *
+ * \par \em <openmpi-sessions>
+ * This is a fixed name that serves as a concentrator for all Open MPI session
+ * directories on the local system. If it doesn't already exist, this directory is
+ * created with read-write-execute permissions for all. If it does exist, the access
+ * permissions are checked to ensure they remain read-write-execute for all - if not,
+ * an error condition is returned.
+ *
+ * \par \em <user-id>
+ * The user's id on the local system. For security purposes, this directory is created
+ * with read-write-execute permissions exclusively restricted to the user. This also
+ * allows multiple users to specify identical universe names without conflict.
+ *
+ * \par
+ * Note: The <prefix>/openmpi-sessions/<user-id> directory is left on the system
+ * upon termination of an application and/or an Open MPI universe for future use
+ * by the user. Thus, when checking a potential location for the directory, the
+ * ompi_session_dir_init() function first checks to see if an appropriate directory
+ * already exists, and uses it if it does.
+ *
+ * \par \em <universe-name>
+ * Finally, a directory is created for the specified universe name. This is the directory
+ * that will be used to house all information relating to the specific universe. If the
+ * directory already exists (indicating that the user is joining an existing universe),
+ * then the function ensures that the user has exclusive read-write-execute permissions
+ * on the directory.
+ */
+
+/** 
+ * @param prefix A pointer to a string identifying the root to be used for the session directory.
+ * This value is provided by the user via the --tmpdir command-line option. If no value
+ * is provided, prefix is passed by the calling program as a NULL value, and the
+ * ompi_session_dir_init() function will attempt to find an appropriate root.
+ *
+ * @param universe A pointer to a string that specifies the name of the universe to be
+ * established. This name is used to create the universe-specific sessions directory in
+ * the user's openmpi-sessions directory. The universe-specific directory will be used
+ * to store information required for universe operations. A NULL value will result in an
+ * error condition being returned.
+ *
+ * @retval LAM_ERROR If the directory could not be created, or if an existing directory
+ * of the correct name is found, but cannot be set to the required access permissions.
+ *
+ * @retval LAM_SUCCESS If the directory was successfully created with the required access
+ * permissions
+ *
+ * In addition to the return values, the ompi_session_dir_init() function stores the
+ * absolute path name of the session directory in the ompi_system_info.session_dir field
+ * (see the ompi_sys_info() function for details on this structure).
+ *
+ */
+
+int ompi_session_dir_init(char *prefix, char *universe);

src/util/os_create_dirpath.c

@@ -2,7 +2,6 @@
  * $HEADER$
  */
 
-/** @file **/
 
 #include "lam_config.h"
 
@@ -27,7 +26,7 @@ int ompi_os_create_dirpath(const char *path, const mode_t mode)
 	if (mode == (mode & buf.st_mode)) { /* has correct mode */
 	    return(LAM_SUCCESS);
 	}
-	if (0 == chmod(path, mode)) { /* successfully change mode */
+	if (0 == chmod(path, (buf.st_mode | mode))) { /* successfully change mode */
 	    return(LAM_SUCCESS);
 	}
 	return(LAM_ERROR); /* can't set correct mode */

src/util/os_create_dirpath.h

@@ -2,9 +2,38 @@
  * $HEADER$
  */
 
-/** @file **/
+/** @file:
+ * Creates a directory tree set to the specified permissions.
+ *
+ * The ompi_os_create_dirpath() function creates a directory
+ * tree, with each directory that is created in the tree having the specified
+ * access permissions. Existing directories within the tree are left
+ * untouched - however, if they do not permit the user to create a directory
+ * within them, the function will return an error condition.
+ * 
+ * If the specified full path name already exists, the
+ * ompi_os_create_dirpath() function will check to ensure that
+ * the final directory in the tree has at least the specified access permission. In other
+ * words, if the directory has read-write-execute for all, and the user
+ * has requested read-write access for just the user, then the function
+ * will consider the directory acceptable. If the minimal permissions are
+ * not currently provided, the function will attempt to change the
+ * access permissions of the directory to add the specified
+ * permissions. The function will return LAM_ERROR if this cannot
+ * be done.
+ **/
 
 #include <stdio.h>
 #include <sys/stat.h>
 
+/**
+ * @param path A pointer to a string that contains the path name to be built.
+ * @param mode A mode_t bit mask that specifies the access permissions for the
+ * directories being constructed. 
+ * @retval LAM_SUCCESS If the directory tree has been successfully created with
+ * the specified access permissions.
+ * @retval LAM_ERROR If the directory tree could not be created with the
+ * specified access permissions.
+ */
+
 int ompi_os_create_dirpath(const char *path, const mode_t mode);

src/util/os_path.c

@@ -2,8 +2,6 @@
  * $HEADER$
  */
 
-/** @file **/
-
 #include "lam_config.h"
 
 #include <string.h>

src/util/os_path.h

@@ -2,10 +2,45 @@
  * $HEADER$
  */
 
-/** @file **/
+/** @file:
+ * Creates an operating system-acceptable path name.
+ *
+ * The ompi_os_path() function takes a variable number of string arguments and
+ * concatenates them into a path name using the path separator character appropriate
+ * to the local operating system. NOTE: the string returned by this function has been
+ * malloc'd - thus, the user is responsible for free'ing the memory used by
+ * the string.
+ *
+ * CRITICAL NOTE: The input variable list MUST be terminated by a NULL value. Failure
+ * to do this will cause the program to suffer a catastrophic failure - usually a
+ * segmentation violation or bus error.
+ *
+ * The function calls ompi_sys_info() to ensure that the path separator character
+ * has been identified. If that value cannot be identified for some reason,
+ * the function will return a NULL value. Likewise, specifying a path name that
+ * exceeds the maximum allowable path name length on the local system will result
+ * in the return of a NULL value.
+ *
+ *
+ */
 
 #include <stdio.h>
 #include <stdarg.h>
 #include <stdbool.h>
 
+/** 
+ * @param relative A boolean that specifies if the path name is to be constructed
+ * relative to the current directory or as an absolute path. If no path
+ * elements are included in the function call, then the function returns
+ * "." for a relative path name and "<path separator char>" - 
+ * the top of the directory tree - for an absolute path name.
+ * @param elem1,elem2,... A variable number of (char *)path_elements
+ * can be provided to the function, terminated by a NULL value. These
+ * elements will be concatenated, each separated by the path separator
+ * character, into a path name and returned.
+ * @retval path_name A pointer to a fully qualified path name composed of the
+ * provided path elements, separated by the path separator character
+ * appropriate to the local operating system. The path_name string has been malloc'd
+ * and therefore the user is responsible for free'ing the field.
+*/
 char *ompi_os_path(bool relative, ...);

src/util/sys_info.h

@@ -2,58 +2,63 @@
  * $HEADER$
  */
 
-/** @file **/
-
-/* sys_info populates a global variable with information about the system
- * upon which the process is executing. Each process executes this function - the universe
- * process through ompi_init(), and application processes via mpi_init().
- *
- * The structure contains the following fields:
- *
- * bool valid     - certifies that the ompi_sys_info has been called at least once
- *                  so fields have valid values
- *
- * char sysname[] - the name of the operating system in use
- *
- * char release[] - current release level of the operating system
- *
- * char version[] - current version level of the operating system
- *
- * char machine[] - type of hardware in use
- *
- * char nodename[] - the network node name of the host, same as that
- *                   returned by gethostname()
- *
- * char path_sep - the character used to separate directories in the path,
- *                 a value that is usually either a '\' or '/', depending
- *                 upon the operating system
- *
- * char tmp_dir - location of user-writable temp directory on this system.
- *                Space for string is allocated in ompi_sys_info().
+/** @file:
  *
+ * Populates global structure with system-specific information.
  */
 
+
 #include <stdbool.h>
 #include <sys/utsname.h>
 
+/**
+ * System information structure
+ *
+ * The ompi_sys_info() function fills the sysname, nodename, release, version, machine,
+ * path_sep, and user fields, but does not populate
+ * the session_dir, enviro, suffix, or sock_* fields. These latter fields are populated by other
+ * functions as required.
+ *
+ */
 struct ompi_sys_info_t {
-    bool init;             /** Certifies that values have been filled */
-    char *sysname;         /** Name of OS */
-    char *nodename;        /** Name of this network node */
-    char *release;	   /** Release level */
-    char *version;	   /** Version level */
-    char *machine;	   /** Hardware type */
-    /** ---------- above line = fields in utsname structure --------- 
-     *  Following fields are added to support Open MPI-specific needs
-     */
-    char *path_sep;        /** path separation char, saved as string */
-    char *user;            /** user id on this system */
-    char *session_dir;     /** location of user writable temp dir for storing session info */
-    char *enviro;          /** computing environment employed on this system */
-    char *suffix;          /** automatic suffix added to file names, if system does this */
-    char *sock_stdin;      /** path name to temp file for stdin */
-    char *sock_stdout;     /** path name to temp file for stdout */
-    char *sock_stderr;     /** path name to temp file for stderr */
+    bool init;             /**< Certifies that values have been filled.
+			    * Certifies that the ompi_sys_info() function has been
+			    * called at least once so fields have valid values
+			    */
+    char *sysname;         /**< Name of OS in use on this node. */
+    char *nodename;        /**< Fully qualified host name on the network. */
+    char *release;	   /**< Release level of the operating system. */
+    char *version;	   /**< Version of the operating system release. */
+    char *machine;	   /**< Type of hardware composing this node. */
+    char *path_sep;        /**< Path separation char, saved as string.
+			    * The character used to separate directories in the path - 
+			    * a value that is usually either a '\' or '/', depending
+			    * upon the operating system
+			    */
+    char *user;            /**< User id on this system. */
+    char *session_dir;     /**< Location of user writable temp dir.
+			    * The session directory has the form
+			    * <prefix><openmpi-sessions>, where the prefix
+			    * can either be provided by the user via the
+			    * --tmpdir command-line flag, the use of one of several
+			    * environmental variables, or else a default location. The
+			    * function ompi_session_dir_init() develops
+			    * the name of this directory, creates it, and stores the name
+			    * in this location.
+			    */
+    char *enviro;          /**< Computing environment employed on this system.
+			    * Indicates the local computing environment for managing
+			    * and scheduling resources - e.g., SLURM, PBS, LSF, or BProc
+			    */
+    char *suffix;          /**< Automatic suffix added to file names.
+			    * Some computing environments automatically "tag" files
+			    * created by applications with a computer-generated suffix
+			    * to ensure uniqueness of the file name. This field records
+			    * that value for future use.
+			    */
+    char *sock_stdin;      /**< Path name to temp file for stdin. */
+    char *sock_stdout;     /**< Path name to temp file for stdout. */
+    char *sock_stderr;     /**< Path name to temp file for stderr. */
 };
 typedef struct ompi_sys_info_t ompi_sys_info_t;
 
@@ -61,8 +66,11 @@ extern ompi_sys_info_t ompi_system_info;
 
 /**
  * Discover and record a wide range of information about the system upon which
- * this code is executing.
+ * this code is executing. ompi_sys_info populates a global variable with information about the system
+ * upon which the process is executing. This function can be executed multiple times - the universe
+ * process through ompi_init(), and each application process via mpi_init().
  *
  * @retval None
+ */
 
 void ompi_sys_info(void);