src/util/pmix_os_dirpath.h

0001 /*
0002  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0003  *                         University Research and Technology
0004  *                         Corporation.  All rights reserved.
0005  * Copyright (c) 2004-2005 The University of Tennessee and The University
0006  *                         of Tennessee Research Foundation.  All rights
0007  *                         reserved.
0008  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0009  *                         University of Stuttgart.  All rights reserved.
0010  * Copyright (c) 2004-2005 The Regents of the University of California.
0011  *                         All rights reserved.
0012  * Copyright (c) 2019-2020 Intel, Inc.  All rights reserved.
0013  * Copyright (c) 2021-2023 Nanook Consulting  All rights reserved.
0014  * $COPYRIGHT$
0015  *
0016  * Additional copyrights may follow
0017  *
0018  * $HEADER$
0019  */
0020
0021 /** @file:
0022  * Creates a directory tree set to the specified permissions.
0023  *
0024  * The pmix_os_dirpath_create() function creates a directory
0025  * tree, with each directory that is created in the tree having the specified
0026  * access permissions. Existing directories within the tree are left
0027  * untouched - however, if they do not permit the user to create a directory
0028  * within them, the function will return an error condition.
0029  *
0030  * If the specified full path name already exists, the
0031  * pmix_os_dirpath_create() function will check to ensure that
0032  * the final directory in the tree has at least the specified access permission. In other
0033  * words, if the directory has read-write-execute for all, and the user
0034  * has requested read-write access for just the user, then the function
0035  * will consider the directory acceptable. If the minimal permissions are
0036  * not currently provided, the function will attempt to change the
0037  * access permissions of the directory to add the specified
0038  * permissions. The function will return PMIX_ERROR if this cannot
0039  * be done.
0040  **/
0041
0042 #ifndef PMIX_OS_DIRPATH_CREATE_H
0043 #define PMIX_OS_DIRPATH_CREATE_H
0044
0045 #include "src/include/pmix_config.h"
0046 #ifdef HAVE_SYS_STAT_H
0047 #    include <sys/stat.h>
0048 #endif
0049
0050 BEGIN_C_DECLS
0051
0052 /**
0053  * @param path A pointer to a string that contains the path name to be built.
0054  * @param mode A mode_t bit mask that specifies the access permissions for the
0055  * directories being constructed.
0056  * @retval PMIX_SUCCESS If the directory tree has been successfully created with
0057  * the specified access permissions.
0058  * @retval PMIX_ERROR If the directory tree could not be created with the
0059  * specified access permissions.
0060  */
0061
0062 PMIX_EXPORT int pmix_os_dirpath_create(const char *path, const mode_t mode);
0063
0064 /**
0065  * Check to see if a directory is empty
0066  *
0067  * @param path A pointer to a string that contains the path name to be checked.
0068  *
0069  * @retval true If the directory is empty
0070  * @retval false If the directory is not empty
0071  */
0072 PMIX_EXPORT bool pmix_os_dirpath_is_empty(const char *path);
0073
0074 /**
0075  * Stale function left for PRRTE backward compatility
0076  */
0077 PMIX_EXPORT int pmix_os_dirpath_access(const char *path, const mode_t mode);
0078
0079 /**
0080  * Callback for pmix_os_dirpath_destroy(). Call for every file/directory before
0081  * taking action to remove/unlink it.
0082  *
0083  * @param root A pointer to a string that contains the base path name (e.g., /tmp/foo from
0084  * /tmp/foo/bar)
0085  * @param path A pointer to a string that contains the file or directory (e.g., bar from
0086  * /tmp/foo/bar)
0087  *
0088  * @retval true  Allow the program to remove the file/directory
0089  * @retval false Do not allow the program to remove the file/directory
0090  */
0091 typedef bool (*pmix_os_dirpath_destroy_callback_fn_t)(const char *root, const char *path);
0092
0093 /**
0094  * Destroy a directory
0095  *
0096  * @param path A pointer to a string that contains the path name to be destroyed
0097  * @param recursive Recursively descend the directory removing all files and directories.
0098  *                  if set to 'false' then the directory must be empty to succeed.
0099  * @param cbfunc A function that will be called before removing a file or directory.
0100  *               If NULL, then assume all remove.
0101  *
0102  * @retval PMIX_SUCCESS If the directory was successfully removed or removed to the
0103  *                      specification of the user (i.e., obeyed the callback function).
0104  * @retval PMIX_ERR_NOT_FOUND If directory does not exist.
0105  * @retval PMIX_ERROR If the directory cannot be removed, accessed properly, or contains
0106  *                    directories that could not be removed..
0107  */
0108 PMIX_EXPORT int pmix_os_dirpath_destroy(const char *path, bool recursive,
0109                                         pmix_os_dirpath_destroy_callback_fn_t cbfunc);
0110
0111 END_C_DECLS
0112
0113 #endif