src/util/pmix_os_path.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) 2015-2020 Intel, Inc.  All rights reserved.
0013  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0014  * $COPYRIGHT$
0015  *
0016  * Additional copyrights may follow
0017  *
0018  * $HEADER$
0019  */
0020
0021 /** @file:
0022  * Creates an operating system-acceptable path name.
0023  *
0024  * The pmix_os_path() function takes a variable number of string arguments and
0025  * concatenates them into a path name using the path separator character appropriate
0026  * to the local operating system. NOTE: the string returned by this function has been
0027  * malloc'd - thus, the user is responsible for free'ing the memory used by
0028  * the string.
0029  *
0030  * CRITICAL NOTE: The input variable list MUST be terminated by a NULL value. Failure
0031  * to do this will cause the program to suffer a catastrophic failure - usually a
0032  * segmentation violation or bus error.
0033  *
0034  * The function calls orte_sys_info() to ensure that the path separator character
0035  * has been identified. If that value cannot be identified for some reason,
0036  * the function will return a NULL value. Likewise, specifying a path name that
0037  * exceeds the maximum allowable path name length on the local system will result
0038  * in the return of a NULL value.
0039  *
0040  *
0041  */
0042
0043 #ifndef PMIX_OS_PATH_H
0044 #define PMIX_OS_PATH_H
0045
0046 #include "src/include/pmix_config.h"
0047 #include "pmix_common.h"
0048
0049 #include <stdarg.h>
0050 #include <stdio.h>
0051
0052 BEGIN_C_DECLS
0053
0054 /**
0055  * @param relative A boolean that specifies if the path name is to be constructed
0056  * relative to the current directory or as an absolute path. If no path
0057  * elements are included in the function call, then the function returns
0058  * "." for a relative path name and "<path separator char>" -
0059  * the top of the directory tree - for an absolute path name.
0060  * @param elem1,elem2,... A variable number of (char *)path_elements
0061  * can be provided to the function, terminated by a NULL value. These
0062  * elements will be concatenated, each separated by the path separator
0063  * character, into a path name and returned.
0064  * @retval path_name A pointer to a fully qualified path name composed of the
0065  * provided path elements, separated by the path separator character
0066  * appropriate to the local operating system. The path_name string has been malloc'd
0067  * and therefore the user is responsible for free'ing the field.
0068  *
0069  * Note that the "relative" argument is int instead of bool, because
0070  * passing a parameter that undergoes default argument promotion to
0071  * va_start() has undefined behavior (according to clang warnings on
0072  * MacOS High Sierra).
0073  */
0074 PMIX_EXPORT char *pmix_os_path(int relative, ...)
0075     __pmix_attribute_malloc__ __pmix_attribute_sentinel__ __pmix_attribute_warn_unused_result__;
0076
0077 /**
0078  * Convert the path to be OS friendly. On UNIX this function will
0079  * be empty.
0080  */
0081 #define pmix_make_filename_os_friendly(PATH) (PATH)
0082
0083 END_C_DECLS
0084
0085 #endif /* PMIX_OS_PATH_H */