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