1 /* 2 * Prototypes for vector handling. 3 * 4 * A vector is a list of strings, with dynamic resizing of the list as new 5 * strings are added and support for various operations on strings (such as 6 * splitting them on delimiters). 7 * 8 * Vectors require list of strings, not arbitrary binary data, and cannot 9 * handle data elements containing nul characters. 10 * 11 * This is based on the util/vector.c library, but that library uses xmalloc 12 * routines to exit the program if memory allocation fails. This is a 13 * modified version of the vector library that instead returns false on 14 * failure to allocate memory, allowing the caller to do appropriate recovery. 15 * 16 * Only the portions of the vector library used by PAM modules are 17 * implemented. 18 * 19 * The canonical version of this file is maintained in the rra-c-util package, 20 * which can be found at <https://www.eyrie.org/~eagle/software/rra-c-util/>. 21 * 22 * Written by Russ Allbery <eagle@eyrie.org> 23 * Copyright 2010-2011, 2014 24 * The Board of Trustees of the Leland Stanford Junior University 25 * 26 * Copying and distribution of this file, with or without modification, are 27 * permitted in any medium without royalty provided the copyright notice and 28 * this notice are preserved. This file is offered as-is, without any 29 * warranty. 30 * 31 * SPDX-License-Identifier: FSFAP 32 */ 33 34 #ifndef PAM_UTIL_VECTOR_H 35 #define PAM_UTIL_VECTOR_H 1 36 37 #include <config.h> 38 #include <portable/macros.h> 39 #include <portable/stdbool.h> 40 41 #include <stddef.h> 42 43 struct vector { 44 size_t count; 45 size_t allocated; 46 char **strings; 47 }; 48 49 BEGIN_DECLS 50 51 /* Default to a hidden visibility for all util functions. */ 52 #pragma GCC visibility push(hidden) 53 54 /* Create a new, empty vector. Returns NULL on memory allocation failure. */ 55 struct vector *vector_new(void) __attribute__((__malloc__)); 56 57 /* 58 * Create a new vector that's a copy of an existing vector. Returns NULL on 59 * memory allocation failure. 60 */ 61 struct vector *vector_copy(const struct vector *) 62 __attribute__((__malloc__, __nonnull__)); 63 64 /* 65 * Add a string to a vector. Resizes the vector if necessary. Returns false 66 * on failure to allocate memory. 67 */ 68 bool vector_add(struct vector *, const char *string) 69 __attribute__((__nonnull__)); 70 71 /* 72 * Resize the array of strings to hold size entries. Saves reallocation work 73 * in vector_add if it's known in advance how many entries there will be. 74 * Returns false on failure to allocate memory. 75 */ 76 bool vector_resize(struct vector *, size_t size) __attribute__((__nonnull__)); 77 78 /* 79 * Reset the number of elements to zero, freeing all of the strings for a 80 * regular vector, but not freeing the strings array (to cut down on memory 81 * allocations if the vector will be reused). 82 */ 83 void vector_clear(struct vector *) __attribute__((__nonnull__)); 84 85 /* Free the vector and all resources allocated for it. */ 86 void vector_free(struct vector *); 87 88 /* 89 * Split functions build a vector from a string. vector_split_multi splits on 90 * a set of characters. If the vector argument is NULL, a new vector is 91 * allocated; otherwise, the provided one is reused. Returns NULL on memory 92 * allocation failure, after which the provided vector may have been modified 93 * to only have partial results. 94 * 95 * Empty strings will yield zero-length vectors. Adjacent delimiters are 96 * treated as a single delimiter by vector_split_multi. Any leading or 97 * trailing delimiters are ignored, so this function will never create 98 * zero-length strings (similar to the behavior of strtok). 99 */ 100 struct vector *vector_split_multi(const char *string, const char *seps, 101 struct vector *) 102 __attribute__((__nonnull__(1, 2))); 103 104 /* 105 * Exec the given program with the vector as its arguments. Return behavior 106 * is the same as execv. Note the argument order is different than the other 107 * vector functions (but the same as execv). The vector_exec_env variant 108 * calls execve and passes in the environment for the program. 109 */ 110 int vector_exec(const char *path, struct vector *) 111 __attribute__((__nonnull__)); 112 int vector_exec_env(const char *path, struct vector *, const char *const env[]) 113 __attribute__((__nonnull__)); 114 115 /* Undo default visibility change. */ 116 #pragma GCC visibility pop 117 118 END_DECLS 119 120 #endif /* UTIL_VECTOR_H */ 121