src/util/pmix_basename.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 /**
0022  * @file
0023  *
0024  * Returns an OS-independant basename() of a given filename.
0025  */
0026
0027 #ifndef PMIX_BASENAME_H
0028 #define PMIX_BASENAME_H
0029
0030 #include "src/include/pmix_config.h"
0031 #include "pmix_common.h"
0032
0033 BEGIN_C_DECLS
0034
0035 /**
0036  * Return the basename of a filename.
0037  *
0038  * @param filename The filename to examine
0039  *
0040  * @returns A string containing the basename, or NULL if there is an error
0041  *
0042  * The contents of the \em filename parameter are unchanged.  This
0043  * function returns a new string containing the basename of the
0044  * filename (which must be eventually freed by the caller), or
0045  * NULL if there is an error.  Trailing "/" characters in the
0046  * filename do not count, unless it is in the only part of the
0047  * filename (e.g., "/" or "C:\").
0048  *
0049  * This function will do the Right Things on POSIX and
0050  * Windows-based operating systems.  For example:
0051  *
0052  * foo.txt returns "foo.txt"
0053  *
0054  * /foo/bar/baz returns "baz"
0055  *
0056  * /yow.c returns "yow.c"
0057  *
0058  * / returns "/"
0059  *
0060  * C:\foo\bar\baz returns "baz"
0061  *
0062  * D:foo.txt returns "foo.txt"
0063  *
0064  * E:\yow.c returns "yow.c"
0065  *
0066  * F: returns "F:"
0067  *
0068  * G:\ returns "G:"
0069  *
0070  * The caller is responsible for freeing the returned string.
0071  */
0072 PMIX_EXPORT char *
0073 pmix_basename(const char *filename) __pmix_attribute_malloc__ __pmix_attribute_warn_unused_result__;
0074
0075 /**
0076  * Return the dirname of a filename.
0077  *
0078  * @param filename The filename to examine
0079  *
0080  * @returns A string containing the dirname, or NULL if there is an error
0081  *
0082  * The contents of the \em filename parameter are unchanged.  This
0083  * function returns a new string containing the dirname of the
0084  * filename (which must be eventually freed by the caller), or
0085  * NULL if there is an error.  Trailing "/" characters in the
0086  * filename do not count, unless it is in the only part of the
0087  * filename (e.g., "/" or "C:\").
0088  *
0089  * This function will do the Right Things on POSIX and
0090  * Windows-based operating systems.  For example:
0091  *
0092  * foo.txt returns "foo.txt"
0093  *
0094  * /foo/bar/baz returns "/foo/bar"
0095  *
0096  * /yow.c returns "/"
0097  *
0098  * / returns ""
0099  *
0100  * C:\foo\bar\baz returns "C:\foo\bar"
0101  *
0102  * D:foo.txt returns "D:"
0103  *
0104  * E:\yow.c returns "E:"
0105  *
0106  * F: returns ""
0107  *
0108  * G:\ returns ""
0109  *
0110  * The caller is responsible for freeing the returned string.
0111  */
0112 PMIX_EXPORT char *
0113 pmix_dirname(const char *filename) __pmix_attribute_malloc__ __pmix_attribute_warn_unused_result__;
0114
0115 END_C_DECLS
0116
0117 #endif /* PMIX_BASENAME_H */