1 /* 2 * Copyright (c) 2004-2007 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-2008 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) 2007 Los Alamos National Security, LLC. 13 * All rights reserved. 14 * Copyright (c) 2007 Voltaire. All rights reserved. 15 * Copyright (c) 2012 Los Alamos National Security, LLC. All rights reserved. 16 * 17 * $COPYRIGHT$ 18 * 19 * Additional copyrights may follow 20 * 21 * $HEADER$ 22 */ 23 24 /** 25 * @file 26 * 27 * Generic routines for "argv"-like handling. Helpful for creating 28 * arrays of strings, especially when creating command lines. 29 */ 30 31 #ifndef OPAL_ARGV_H 32 #define OPAL_ARGV_H 33 #include "opal_config.h" 34 35 #ifdef HAVE_SYS_TYPES_H 36 #include <sys/types.h> 37 #endif 38 39 BEGIN_C_DECLS 40 41 /** 42 * Append a string (by value) to an new or existing NULL-terminated 43 * argv array. 44 * 45 * @param argc Pointer to the length of the argv array. Must not be 46 * NULL. 47 * @param argv Pointer to an argv array. 48 * @param str Pointer to the string to append. 49 * 50 * @retval OPAL_SUCCESS On success 51 * @retval OPAL_ERROR On failure 52 * 53 * This function adds a string to an argv array of strings by value; 54 * it is permissable to pass a string on the stack as the str 55 * argument to this function. 56 * 57 * To add the first entry to an argv array, call this function with 58 * (*argv == NULL). This function will allocate an array of length 59 * 2; the first entry will point to a copy of the string passed in 60 * arg, the second entry will be set to NULL. 61 * 62 * If (*argv != NULL), it will be realloc'ed to be 1 (char*) larger, 63 * and the next-to-last entry will point to a copy of the string 64 * passed in arg. The last entry will be set to NULL. 65 * 66 * Just to reinforce what was stated above: the string is copied by 67 * value into the argv array; there is no need to keep the original 68 * string (i.e., the arg parameter) after invoking this function. 69 */ 70 OPAL_DECLSPEC int opal_argv_append(int *argc, char ***argv, const char *arg) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(3); 71 72 /** 73 * Append to an argv-style array, but ignore the size of the array. 74 * 75 * @param argv Pointer to an argv array. 76 * @param str Pointer to the string to append. 77 * 78 * @retval OPAL_SUCCESS On success 79 * @retval OPAL_ERROR On failure 80 * 81 * This function is identical to the opal_argv_append() function 82 * except that it does not take a pointer to an argc (integer 83 * representing the size of the array). This is handy for 84 * argv-style arrays that do not have integers that are actively 85 * maintaing their sizes. 86 */ 87 OPAL_DECLSPEC int opal_argv_append_nosize(char ***argv, const char *arg); 88 89 /** 90 * Insert the provided arg at the beginning of the array 91 * 92 * @param argv Pointer to an argv array 93 * @param str Pointer to the string to prepend 94 * 95 * @retval OPAL_SUCCESS On success 96 * @retval OPAL_ERROR On failure 97 */ 98 OPAL_DECLSPEC int opal_argv_prepend_nosize(char ***argv, const char *arg); 99 100 /** 101 * Append to an argv-style array, but only if the provided argument 102 * doesn't already exist somewhere in the array. Ignore the size of the array. 103 * 104 * @param argv Pointer to an argv array. 105 * @param str Pointer to the string to append. 106 * @param bool Whether or not to overwrite a matching value if found 107 * 108 * @retval OPAL_SUCCESS On success 109 * @retval OPAL_ERROR On failure 110 * 111 * This function is identical to the opal_argv_append_nosize() function 112 * except that it only appends the provided argument if it does not already 113 * exist in the provided array, or overwrites it if it is. 114 */ 115 OPAL_DECLSPEC int opal_argv_append_unique_nosize(char ***argv, const char *arg, bool overwrite); 116 117 /** 118 * Free a NULL-terminated argv array. 119 * 120 * @param argv Argv array to free. 121 * 122 * This function frees an argv array and all of the strings that it 123 * contains. Since the argv parameter is passed by value, it is not 124 * set to NULL in the caller's scope upon return. 125 * 126 * It is safe to invoke this function with a NULL pointer. It is 127 * not safe to invoke this function with a non-NULL-terminated argv 128 * array. 129 */ 130 OPAL_DECLSPEC void opal_argv_free(char **argv); 131 132 /** 133 * Split a string into a NULL-terminated argv array. Do not include empty 134 * strings in result array. 135 * 136 * @param src_string Input string. 137 * @param delimiter Delimiter character. 138 * 139 * @retval argv pointer to new argv array on success 140 * @retval NULL on error 141 * 142 * All strings are insertted into the argv array by value; the 143 * newly-allocated array makes no references to the src_string 144 * argument (i.e., it can be freed after calling this function 145 * without invalidating the output argv). 146 */ 147 OPAL_DECLSPEC char **opal_argv_split(const char *src_string, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__; 148 149 /** 150 * Split a string into a NULL-terminated argv array. Include empty 151 * strings in result array. 152 * 153 * @param src_string Input string. 154 * @param delimiter Delimiter character. 155 * 156 * @retval argv pointer to new argv array on success 157 * @retval NULL on error 158 * 159 * All strings are insertted into the argv array by value; the 160 * newly-allocated array makes no references to the src_string 161 * argument (i.e., it can be freed after calling this function 162 * without invalidating the output argv). 163 */ 164 OPAL_DECLSPEC char **opal_argv_split_with_empty(const char *src_string, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__; 165 166 /** 167 * Return the length of a NULL-terminated argv array. 168 * 169 * @param argv The input argv array. 170 * 171 * @retval 0 If NULL is passed as argv. 172 * @retval count Number of entries in the argv array. 173 * 174 * The argv array must be NULL-terminated. 175 */ 176 OPAL_DECLSPEC int opal_argv_count(char **argv); 177 178 /** 179 * Join all the elements of an argv array into a single 180 * newly-allocated string. 181 * 182 * @param argv The input argv array. 183 * @param delimiter Delimiter character placed between each argv string. 184 * 185 * @retval new_string Output string on success. 186 * @retval NULL On failure. 187 * 188 * Similar to the Perl join function, this function takes an input 189 * argv and joins them into into a single string separated by the 190 * delimiter character. 191 * 192 * It is the callers responsibility to free the returned string. 193 */ 194 OPAL_DECLSPEC char *opal_argv_join(char **argv, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__; 195 196 OPAL_DECLSPEC char *opal_argv_join_range(char **argv, size_t start, size_t end, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__; 197 198 /** 199 * Return the number of bytes consumed by an argv array. 200 * 201 * @param argv The input argv array. 202 * 203 * Count the number of bytes consumed by a NULL-terminated argv 204 * array. This includes the number of bytes used by each of the 205 * strings as well as the pointers used in the argv array. 206 */ 207 OPAL_DECLSPEC size_t opal_argv_len(char **argv); 208 209 /** 210 * Copy a NULL-terminated argv array. 211 * 212 * @param argv The input argv array. 213 * 214 * @retval argv Copied argv array on success. 215 * @retval NULL On failure. 216 * 217 * Copy an argv array, including copying all off its strings. 218 * Specifically, the output argv will be an array of the same length 219 * as the input argv, and strcmp(argv_in[i], argv_out[i]) will be 0. 220 */ 221 OPAL_DECLSPEC char **opal_argv_copy(char **argv) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__; 222 223 /** 224 * Delete one or more tokens from the middle of an argv. 225 * 226 * @param argv The argv to delete from 227 * @param start The index of the first token to delete 228 * @param num_to_delete How many tokens to delete 229 * 230 * @retval OPAL_SUCCESS Always 231 * 232 * Delete some tokens from within an existing argv. The start 233 * parameter specifies the first token to delete, and will delete 234 * (num_to_delete-1) tokens following it. argv will be realloc()ed 235 * to *argc - num_deleted size. 236 * 237 * If start is beyond the end of the argv array, this function is 238 * a no-op. 239 * 240 * If num_to_delete runs beyond the end of the argv array, this 241 * function will delete all tokens starting with start to the end 242 * of the array. 243 * 244 * All deleted items in the argv array will have their contents 245 * free()ed (it is assumed that the argv "owns" the memory that 246 * the pointer points to). 247 */ 248 OPAL_DECLSPEC int opal_argv_delete(int *argc, char ***argv, 249 int start, int num_to_delete); 250 251 /** 252 * Insert one argv array into the middle of another 253 * 254 * @param target The argv to insert tokens into 255 * @param start Index where the first token will be placed in target 256 * @param source The argv to copy tokens from 257 * 258 * @retval OPAL_SUCCESS upon success 259 * @retval OPAL_BAD_PARAM if any parameters are non-sensical 260 * 261 * This function takes one arg and inserts it in the middle of 262 * another. The first token in source will be insertted at index 263 * start in the target argv; all other tokens will follow it. 264 * Similar to opal_argv_append(), the target may be realloc()'ed 265 * to accomodate the new storage requirements. 266 * 267 * The source array is left unaffected -- its contents are copied 268 * by value over to the target array (i.e., the strings that 269 * source points to are strdup'ed into the new locations in 270 * target). 271 */ 272 OPAL_DECLSPEC int opal_argv_insert(char ***target, int start, char **source); 273 274 /** 275 * Insert one argv element in front of a specific position in an array 276 * 277 * @param target The argv to insert tokens into 278 * @param location Index where the token will be placed in target 279 * @param source The token to be inserted 280 * 281 * @retval OPAL_SUCCESS upon success 282 * @retval OPAL_BAD_PARAM if any parameters are non-sensical 283 * 284 * This function takes one arg and inserts it in the middle of 285 * another. The token will be inserted at the specified index 286 * in the target argv; all other tokens will be shifted down. 287 * Similar to opal_argv_append(), the target may be realloc()'ed 288 * to accomodate the new storage requirements. 289 * 290 * The source token is left unaffected -- its contents are copied 291 * by value over to the target array (i.e., the string that 292 * source points to is strdup'ed into the new location in 293 * target). 294 */ 295 OPAL_DECLSPEC int opal_argv_insert_element(char ***target, int location, char *source); 296 297 END_C_DECLS 298 299 #endif /* OPAL_ARGV_H */