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-2005 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) 2019 Intel, Inc. All rights reserved. 13 * $COPYRIGHT$ 14 * 15 * Additional copyrights may follow 16 * 17 * $HEADER$ 18 */ 19 20 /** @file: 21 * Creates a directory tree set to the specified permissions. 22 * 23 * The pmix_os_dirpath_create() function creates a directory 24 * tree, with each directory that is created in the tree having the specified 25 * access permissions. Existing directories within the tree are left 26 * untouched - however, if they do not permit the user to create a directory 27 * within them, the function will return an error condition. 28 * 29 * If the specified full path name already exists, the 30 * pmix_os_dirpath_create() function will check to ensure that 31 * the final directory in the tree has at least the specified access permission. In other 32 * words, if the directory has read-write-execute for all, and the user 33 * has requested read-write access for just the user, then the function 34 * will consider the directory acceptable. If the minimal permissions are 35 * not currently provided, the function will attempt to change the 36 * access permissions of the directory to add the specified 37 * permissions. The function will return PMIX_ERROR if this cannot 38 * be done. 39 **/ 40 41 #ifndef PMIX_OS_DIRPATH_CREATE_H 42 #define PMIX_OS_DIRPATH_CREATE_H 43 44 #include "pmix_config.h" 45 #ifdef HAVE_SYS_STAT_H 46 #include <sys/stat.h> 47 #endif 48 49 BEGIN_C_DECLS 50 51 /** 52 * @param path A pointer to a string that contains the path name to be built. 53 * @param mode A mode_t bit mask that specifies the access permissions for the 54 * directories being constructed. 55 * @retval PMIX_SUCCESS If the directory tree has been successfully created with 56 * the specified access permissions. 57 * @retval PMIX_ERROR If the directory tree could not be created with the 58 * specified access permissions. 59 */ 60 61 PMIX_EXPORT int pmix_os_dirpath_create(const char *path, const mode_t mode); 62 63 /** 64 * Check to see if a directory is empty 65 * 66 * @param path A pointer to a string that contains the path name to be checked. 67 * 68 * @retval true If the directory is empty 69 * @retval false If the directory is not empty 70 */ 71 PMIX_EXPORT bool pmix_os_dirpath_is_empty(const char *path); 72 73 /** 74 * Check access to the directory 75 * 76 * @param path A pointer to a string that contains the path name to be checked. 77 * @param mode A mode_t bit mask that specifies the access permissions for the 78 * directory to be accessed. 79 * 80 * @retval PMIX_SUCCESS If directory exists, and permissions match 81 * @retval PMIX_ERR_NOT_FOUND If directory does not exist 82 * @retval PMIX_ERROR If directory exists, and permissions do not match 83 */ 84 PMIX_EXPORT int pmix_os_dirpath_access(const char *path, const mode_t mode ); 85 86 /** 87 * Callback for pmix_os_dirpath_destroy(). Call for every file/directory before 88 * taking action to remove/unlink it. 89 * 90 * @param root A pointer to a string that contains the base path name (e.g., /tmp/foo from /tmp/foo/bar) 91 * @param path A pointer to a string that contains the file or directory (e.g., bar from /tmp/foo/bar) 92 * 93 * @retval true Allow the program to remove the file/directory 94 * @retval false Do not allow the program to remove the file/directory 95 */ 96 typedef bool (*pmix_os_dirpath_destroy_callback_fn_t)(const char *root, const char *path); 97 98 /** 99 * Destroy a directory 100 * 101 * @param path A pointer to a string that contains the path name to be destroyed 102 * @param recursive Recursively desend the directory removing all files and directories. 103 * if set to 'false' then the directory must be empty to succeed. 104 * @param cbfunc A function that will be called before removing a file or directory. 105 * If NULL, then assume all remove. 106 * 107 * @retval PMIX_SUCCESS If the directory was successfully removed or removed to the 108 * specification of the user (i.e., obeyed the callback function). 109 * @retval PMIX_ERR_NOT_FOUND If directory does not exist. 110 * @retval PMIX_ERROR If the directory cannnot be removed, accessed properly, or contains 111 * directories that could not be removed.. 112 */ 113 PMIX_EXPORT int pmix_os_dirpath_destroy(const char *path, 114 bool recursive, 115 pmix_os_dirpath_destroy_callback_fn_t cbfunc); 116 117 END_C_DECLS 118 119 #endif