OpenMPI  0.1.1
argv.h
Go to the documentation of this file.
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 */
OPAL_DECLSPEC char ** opal_argv_split_with_empty(const char *src_string, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
Split a string into a NULL-terminated argv array.
Definition: argv.c:254
OPAL_DECLSPEC char ** opal_argv_copy(char **argv) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
Copy a NULL-terminated argv array.
Definition: argv.c:413
OPAL_DECLSPEC int opal_argv_insert_element(char ***target, int location, char *source)
Insert one argv element in front of a specific position in an array.
Definition: argv.c:547
OPAL_DECLSPEC int opal_argv_insert(char ***target, int start, char **source)
Insert one argv array into the middle of another.
Definition: argv.c:494
OPAL_DECLSPEC size_t opal_argv_len(char **argv)
Return the number of bytes consumed by an argv array.
Definition: argv.c:392
OPAL_DECLSPEC int opal_argv_append_nosize(char ***argv, const char *arg)
Append to an argv-style array, but ignore the size of the array.
Definition: argv.c:53
OPAL_DECLSPEC int opal_argv_count(char **argv)
Return the length of a NULL-terminated argv array.
Definition: argv.c:262
OPAL_DECLSPEC void opal_argv_free(char **argv)
Free a NULL-terminated argv array.
Definition: argv.c:157
OPAL_DECLSPEC int opal_argv_delete(int *argc, char ***argv, int start, int num_to_delete)
Delete one or more tokens from the middle of an argv.
Definition: argv.c:441
OPAL_DECLSPEC char ** opal_argv_split(const char *src_string, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
Split a string into a NULL-terminated argv array.
Definition: argv.c:249
OPAL_DECLSPEC int opal_argv_prepend_nosize(char ***argv, const char *arg)
Insert the provided arg at the beginning of the array.
Definition: argv.c:93
OPAL_DECLSPEC char * opal_argv_join(char **argv, int delimiter) __opal_attribute_malloc__ __opal_attribute_warn_unused_result__
Join all the elements of an argv array into a single newly-allocated string.
Definition: argv.c:281
OPAL_DECLSPEC int opal_argv_append_unique_nosize(char ***argv, const char *arg, bool overwrite)
Append to an argv-style array, but only if the provided argument doesn't already exist somewhere in t...
Definition: argv.c:127
BEGIN_C_DECLS OPAL_DECLSPEC int opal_argv_append(int *argc, char ***argv, const char *arg) __opal_attribute_nonnull__(1) __opal_attribute_nonnull__(3)
Append a string (by value) to an new or existing NULL-terminated argv array.
Definition: argv.c:39