src/util/pmix_argv.h

0001 /*
0002  * Copyright (c) 2004-2007 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-2008 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) 2007      Los Alamos National Security, LLC.
0013  *                         All rights reserved.
0014  * Copyright (c) 2007      Voltaire. All rights reserved.
0015  * Copyright (c) 2012      Los Alamos National Security, LLC. All rights reserved.
0016  * Copyright (c) 2015-2020 Intel, Inc.  All rights reserved.
0017  *
0018  * Copyright (c) 2015-2019 Research Organization for Information Science
0019  *                         and Technology (RIST).  All rights reserved.
0020  * Copyright (c) 2021-2022 Nanook Consulting  All rights reserved.
0021  * $COPYRIGHT$
0022  *
0023  * Additional copyrights may follow
0024  *
0025  * $HEADER$
0026  */
0027
0028 /**
0029  * @file
0030  *
0031  * Generic routines for "argv"-like handling.  Helpful for creating
0032  * arrays of strings, especially when creating command lines.
0033  */
0034
0035 #ifndef PMIX_ARGV_H
0036 #define PMIX_ARGV_H
0037
0038 #include "src/include/pmix_config.h"
0039
0040 #ifdef HAVE_SYS_TYPES_H
0041 #    include <sys/types.h>
0042 #endif
0043
0044 #include "pmix_common.h"
0045
0046 BEGIN_C_DECLS
0047
0048 /**
0049  * Append a string (by value) to an new or existing NULL-terminated
0050  * argv array.
0051  *
0052  * @param argc Pointer to the length of the argv array.  Must not be
0053  * NULL.
0054  * @param argv Pointer to an argv array.
0055  * @param str Pointer to the string to append.
0056  *
0057  * @retval PMIX_SUCCESS On success
0058  * @retval PMIX_ERROR On failure
0059  *
0060  * This function adds a string to an argv array of strings by value;
0061  * it is permissible to pass a string on the stack as the str
0062  * argument to this function.
0063  *
0064  * To add the first entry to an argv array, call this function with
0065  * (*argv == NULL).  This function will allocate an array of length
0066  * 2; the first entry will point to a copy of the string passed in
0067  * arg, the second entry will be set to NULL.
0068  *
0069  * If (*argv != NULL), it will be realloc'ed to be 1 (char*) larger,
0070  * and the next-to-last entry will point to a copy of the string
0071  * passed in arg.  The last entry will be set to NULL.
0072  *
0073  * Just to reinforce what was stated above: the string is copied by
0074  * value into the argv array; there is no need to keep the original
0075  * string (i.e., the arg parameter) after invoking this function.
0076  */
0077 PMIX_EXPORT pmix_status_t pmix_argv_append(int *argc, char ***argv, const char *arg)
0078     __pmix_attribute_nonnull__(1) __pmix_attribute_nonnull__(3);
0079
0080 /**
0081  * Append to an argv-style array, but only if the provided argument
0082  * doesn't already exist somewhere in the array. Ignore the size of the array.
0083  * Defines the index of the found/added item in the array.
0084  *
0085  * @param idx Index the found/added item in the array.
0086  * @param argv Pointer to an argv array.
0087  * @param str Pointer to the string to append.
0088  *
0089  * @retval PMIX_SUCCESS On success
0090  * @retval PMIX_ERROR On failure
0091  *
0092  * This function is identical to the PMIx_Argv_append_unique_nosize() function
0093  * but it has an extra argument defining the index of the item in the array.
0094  */
0095 PMIX_EXPORT pmix_status_t pmix_argv_append_unique_idx(int *idx, char ***argv, const char *arg);
0096
0097 PMIX_EXPORT char *pmix_argv_join_range(char **argv, size_t start, size_t end, int delimiter)
0098     __pmix_attribute_malloc__ __pmix_attribute_warn_unused_result__;
0099
0100 /**
0101  * Return the number of bytes consumed by an argv array.
0102  *
0103  * @param argv The input argv array.
0104  *
0105  * Count the number of bytes consumed by a NULL-terminated argv
0106  * array.  This includes the number of bytes used by each of the
0107  * strings as well as the pointers used in the argv array.
0108  */
0109 PMIX_EXPORT size_t pmix_argv_len(char **argv);
0110
0111 /**
0112  * Delete one or more tokens from the middle of an argv.
0113  *
0114  * @param argv The argv to delete from
0115  * @param start The index of the first token to delete
0116  * @param num_to_delete How many tokens to delete
0117  *
0118  * @retval PMIX_SUCCESS Always
0119  *
0120  * Delete some tokens from within an existing argv.  The start
0121  * parameter specifies the first token to delete, and will delete
0122  * (num_to_delete-1) tokens following it.  argv will be realloc()ed
0123  * to *argc - num_deleted size.
0124  *
0125  * If start is beyond the end of the argv array, this function is
0126  * a no-op.
0127  *
0128  * If num_to_delete runs beyond the end of the argv array, this
0129  * function will delete all tokens starting with start to the end
0130  * of the array.
0131  *
0132  * All deleted items in the argv array will have their contents
0133  * free()ed (it is assumed that the argv "owns" the memory that
0134  * the pointer points to).
0135  */
0136 PMIX_EXPORT pmix_status_t pmix_argv_delete(int *argc, char ***argv, int start, int num_to_delete);
0137
0138 /**
0139  * Insert one argv array into the middle of another
0140  *
0141  * @param target The argv to insert tokens into
0142  * @param start Index where the first token will be placed in target
0143  * @param source The argv to copy tokens from
0144  *
0145  * @retval PMIX_SUCCESS upon success
0146  * @retval PMIX_BAD_PARAM if any parameters are non-sensical
0147  *
0148  * This function takes one arg and inserts it in the middle of
0149  * another.  The first token in source will be inserted at index
0150  * start in the target argv; all other tokens will follow it.
0151  * Similar to pmix_argv_append(), the target may be realloc()'ed
0152  * to accommodate the new storage requirements.
0153  *
0154  * The source array is left unaffected -- its contents are copied
0155  * by value over to the target array (i.e., the strings that
0156  * source points to are strdup'ed into the new locations in
0157  * target).
0158  */
0159 PMIX_EXPORT pmix_status_t pmix_argv_insert(char ***target, int start, char **source);
0160
0161 /**
0162  * Insert one argv element in front of a specific position in an array
0163  *
0164  * @param target The argv to insert tokens into
0165  * @param location Index where the token will be placed in target
0166  * @param source The token to be inserted
0167  *
0168  * @retval PMIX_SUCCESS upon success
0169  * @retval PMIX_BAD_PARAM if any parameters are non-sensical
0170  *
0171  * This function takes one arg and inserts it in the middle of
0172  * another.  The token will be inserted at the specified index
0173  * in the target argv; all other tokens will be shifted down.
0174  * Similar to pmix_argv_append(), the target may be realloc()'ed
0175  * to accommodate the new storage requirements.
0176  *
0177  * The source token is left unaffected -- its contents are copied
0178  * by value over to the target array (i.e., the string that
0179  * source points to is strdup'ed into the new location in
0180  * target).
0181  */
0182 PMIX_EXPORT pmix_status_t pmix_argv_insert_element(char ***target, int location, char *source);
0183
0184 PMIX_EXPORT
0185 char **pmix_argv_copy_strip(char **argv) __pmix_attribute_malloc__ __pmix_attribute_warn_unused_result__;
0186
0187
0188 END_C_DECLS
0189
0190 #endif /* PMIX_ARGV_H */