OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

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_argv_split_with_empty
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_argv_copy
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_argv_insert_element
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_argv_insert
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_argv_len
OPAL_DECLSPEC size_t opal_argv_len(char **argv)
Return the number of bytes consumed by an argv array.
Definition: argv.c:392
opal_argv_append_nosize
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_argv_count
OPAL_DECLSPEC int opal_argv_count(char **argv)
Return the length of a NULL-terminated argv array.
Definition: argv.c:262
opal_argv_free
OPAL_DECLSPEC void opal_argv_free(char **argv)
Free a NULL-terminated argv array.
Definition: argv.c:157
opal_argv_delete
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_argv_split
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_argv_prepend_nosize
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_argv_join
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_argv_append_unique_nosize
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
opal_argv_append
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