OpenMPI  0.1.1
session_dir.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2006 The University of Tennessee and The University
6  * of Tennessee Research Foundation. All rights
7  * reserved.
8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9  * University of Stuttgart. All rights reserved.
10  * Copyright (c) 2004-2005 The Regents of the University of California.
11  * All rights reserved.
12  * $COPYRIGHT$
13  *
14  * Additional copyrights may follow
15  *
16  * $HEADER$
17  */
18 /** @file:
19  *
20  * Find and/or create Open MPI session directory.
21  *
22  * The orte_session_dir() function searches for a temporary directory
23  * that is used by the Open MPI system for storing system-critical
24  * information. For a given system and user, the function attempts to
25  * find (or create, if not found and create is requested) a directory
26  * that will be used to independently house information for multiple
27  * universes, as the user creates them. Thus, the function pursues a
28  * directory tree of the form:
29  *
30  * \par \em [prefix-dir] An absolute path that identifies a temporary
31  * directory that is read-write-execute accessible to everyone. The
32  * function first checks to see if the user has specified the [prefix]
33  * directory on the command line. If so, then the function will use
34  * that [prefix] if the access permissions are correct, or will return
35  * an error condition if not - the function will not search for
36  * alternative locations if the user provides the [prefix] name.
37  *
38  * \par If the [prefix] is not provided by the user, the function
39  * searches for a suitable directory in a specific order, taking the
40  * first option that meets the access permission requirement, using:
41  * (a) the "OMPI_PREFIX_ENV" environment variable; (b) the "TMPDIR"
42  * environment variable; and (c) the "TMP" environment variabley. If
43  * none of those environmental variables have been defined and/or the
44  * function was unable to create a suitable directory within any of
45  * them, then the function tries to use a default location of "/tmp",
46  * where the "/" represents the top-level directory of the local
47  * system. If none of these options are successful, the function
48  * returns an error code.
49  *
50  * \par \em [openmpi-sessions]-[user-id]@[host]:[batchid] This serves
51  * as a concentrator for all Open MPI session directories for this
52  * user on the local system. If it doesn't already exist, this
53  * directory is created with read-write-execute permissions
54  * exclusively restricted to the user. If it does exist, the access
55  * permissions are checked to ensure they are correct - if not, the
56  * program attempts to correct them. If they can't' be changed to the
57  * correct values, an error condition is returned. The [host] and
58  * [batchid] fields are included to provide uniqueness on shared file
59  * systems and batch schedulers, respectively.
60  *
61  * \par Note: The [prefix]/openmpi-sessions-[user-id]@[host]:[batchid]
62  * directory is left on the system upon termination of an application
63  * and/or an Open MPI universe for future use by the user. Thus, when
64  * checking a potential location for the directory, the
65  * orte_session_tree_init() function first checks to see if an
66  * appropriate directory already exists, and uses it if it does.
67  *
68  * \par \em [universe-name] A directory is created for the specified
69  * universe name. This is the directory that will be used to house all
70  * information relating to the specific universe. If the directory
71  * already exists (indicating that the user is joining an existing
72  * universe), then the function ensures that the user has exclusive
73  * read-write-execute permissions on the directory.
74  *
75  * \par \em [job] A directory is created for the specified job
76  * name. This will house all information relating to that specific
77  * job, including directories for each process within that job on this
78  * host.
79  *
80  * \par \em [process] A directory for the specific process, will house
81  * all information for that process.
82  *
83  * \par If \c create is \c true, the directory will be created and the
84  * proc_info structure will be updated. If proc_info is false,
85  */
86 
87 #ifndef ORTE_SESSION_DIR_H_HAS_BEEN_INCLUDED
88 #define ORTE_SESSION_DIR_H_HAS_BEEN_INCLUDED
89 
90 #include "orte_config.h"
91 #include "orte/types.h"
92 
93 BEGIN_C_DECLS
94 
95 /** @param create A boolean variable that indicates whether or not to
96  * create the specified directory. If set to "false",
97  * the function only checks to see if an existing
98  * directory can be found. This is typically used to
99  * locate an already existing universe for reconnection
100  * purposes. If set to "true", then the function
101  * creates the directory, if possible.
102  * @param prefix A string variable indicating where the user
103  * stipulated the directory should be found or
104  * placed. A value of "NULL" indicates that the user
105  * specified no location - hence, the function explores
106  * a range of "standard" locations.
107  * @param hostid Name of the host on which the session directory is
108  * being built. Used to build the name of the
109  * "openmpi-sessions-[user]@[host]:[batch]" branch of
110  * the directory tree. NULL indicates that the nodename
111  * found in orte_process_info is to be used.
112  * @param batchid Batch job name, used in batch scheduling
113  * systems. NULL indicates that the default of "0" is
114  * to be used.
115  * @param proc Pointer to a process name for which the session
116  * dir name is desired
117  *
118  * @retval ORTE_SUCCESS The directory was found and/or created with
119  * the proper permissions.
120  * @retval OMPI_ERROR The directory cannot be found (if create is
121  * "false") or created (if create is "true").
122  */
123 ORTE_DECLSPEC int orte_session_dir(bool create, char *prefix, char *hostid,
124  char *batchid, orte_process_name_t *proc);
125 
126 /*
127  * Construct the session directory name from the input parameters.
128  * This function does no checking that the directory exists, or can be used
129  */
130 ORTE_DECLSPEC int orte_session_dir_get_name(char **fulldirpath,
131  char **prfx,
132  char **frontend,
133  char *hostid,
134  char *batchid,
135  orte_process_name_t *proc);
136 
137 /** The orte_session_dir_finalize() function performs a cleanup of the
138  * session directory tree. It first removes the session directory for
139  * the calling process. It then checks to see if the job-level session
140  * directory is now empty - if so, it removes that level as
141  * well. Finally, it checks to see if the universe-level session
142  * directory is now empty - if so, it also removes that level. This
143  * three-part "last-one-out" procedure ensures that the directory tree
144  * is properly removed if all processes and applications within a
145  * universe have completed.
146  *
147  * @param None
148  * @retval ORTE_SUCCESS If the directory tree is properly cleaned up.
149  * @retval OMPI_ERROR If something prevents the tree from being
150  * properly cleaned up.
151  */
152 ORTE_DECLSPEC int orte_session_dir_finalize(orte_process_name_t *proc);
153 
154 /** The orte_session_dir_cleanup() function performs a cleanup of the
155  * session directory tree when a job is aborted. It cleans up all
156  * process directories for a given job and then backs up the tree.
157  *
158  * @param jobid
159  * @retval OMPI_SUCCESS If the directory tree is properly cleaned up.
160  * @retval OMPI_ERROR If something prevents the tree from being
161  * properly cleaned up.
162  */
163 ORTE_DECLSPEC int orte_session_dir_cleanup(orte_jobid_t jobid);
164 
165 END_C_DECLS
166 
167 #endif /* ORTE_SESSION_DIR_H_HAS_BEEN_INCLUDED */
uint32_t orte_jobid_t
Set the allowed range for ids in each space.
Definition: types.h:76
Definition: types.h:146
ORTE_DECLSPEC int orte_session_dir_finalize(orte_process_name_t *proc)
The orte_session_dir_finalize() function performs a cleanup of the session directory tree...
Definition: session_dir.c:589
BEGIN_C_DECLS ORTE_DECLSPEC int orte_session_dir(bool create, char *prefix, char *hostid, char *batchid, orte_process_name_t *proc)
Definition: session_dir.c:370
ORTE_DECLSPEC int orte_session_dir_cleanup(orte_jobid_t jobid)
The orte_session_dir_cleanup() function performs a cleanup of the session directory tree when a job i...
Definition: session_dir.c:519