00001 /** 00002 * @file 00003 * 00004 * Miscellaneous, uncategorized functions for libapol. 00005 * 00006 * @author Jeremy A. Mowery jmowery@tresys.com 00007 * @author Jason Tang jtang@tresys.com 00008 * 00009 * Copyright (C) 2001-2007 Tresys Technology, LLC 00010 * 00011 * This library is free software; you can redistribute it and/or 00012 * modify it under the terms of the GNU Lesser General Public 00013 * License as published by the Free Software Foundation; either 00014 * version 2.1 of the License, or (at your option) any later version. 00015 * 00016 * This library is distributed in the hope that it will be useful, 00017 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00019 * Lesser General Public License for more details. 00020 * 00021 * You should have received a copy of the GNU Lesser General Public 00022 * License along with this library; if not, write to the Free Software 00023 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 00024 */ 00025 00026 #ifndef APOL_UTIL_H 00027 #define APOL_UTIL_H 00028 00029 #ifdef __cplusplus 00030 extern "C" 00031 { 00032 #endif 00033 00034 #include "vector.h" 00035 00036 #include <stdint.h> 00037 #include <stdio.h> 00038 #include <stdlib.h> 00039 00040 /** 00041 * Return an immutable string describing this library's version. 00042 * 00043 * @return String describing this library. 00044 */ 00045 extern const char *libapol_get_version(void); 00046 00047 /** 00048 * Given a portcon protocol, return a read-only string that describes 00049 * that protocol. 00050 * 00051 * @param protocol Portcon protocol, one of IPPROTO_TCP or IPPROTO_UDP 00052 * from netinet/in.h. 00053 * 00054 * @return A string that describes the protocol, or NULL if the 00055 * protocol is invalid. <b>Do not free() this string.</b> 00056 */ 00057 extern const char *apol_protocol_to_str(uint8_t protocol); 00058 00059 /** 00060 * Given the name of a portcon protocol, return its numeric value. 00061 * 00062 * @param protocol_str Portcon protocol, one of "tcp", "TCP", "udp", or "UDP". 00063 * 00064 * @return Numeric value for the protocol, one of IPPROTO_TCP or IPPROTO_UDP 00065 * from netinet/in.h. Upon error return 0. 00066 */ 00067 extern uint8_t apol_str_to_protocol(const char *protocol_str); 00068 00069 /** 00070 * Given a string representing and IP value (mask or address, IPv4 or 00071 * IPv6), write to an array that value in the same bit order that 00072 * qpol uses. If the IP was in IPv4 format, only write to the first 00073 * element and zero the remainder. 00074 * 00075 * @param str A string representing and IP value, either in IPv4 or 00076 * IPv6 format. 00077 * @param ip Array to which write converted value. 00078 * 00079 * @return QPOL_IPV4 if the string is in IPv4 format, QPOL_IPV6 if 00080 * in IPv6, < 0 on error. 00081 */ 00082 extern int apol_str_to_internal_ip(const char *str, uint32_t ip[4]); 00083 00084 /** 00085 * Given a genfscon object class, return a read-only string that 00086 * describes that class. 00087 * 00088 * @param objclass Object class, one of QPOL_CLASS_BLK_FILE, 00089 * QPOL_CLASS_CHR_FILE, etc. 00090 * 00091 * @return A string that describes the object class, or NULL if the 00092 * object class is invalid. <b>Do not free() this string.</b> 00093 * 00094 * @see <qpol/genfscon_query.h> for a list of valid object classes. 00095 */ 00096 extern const char *apol_objclass_to_str(uint32_t objclass); 00097 00098 /** 00099 * Given a string representing a genfscon object class, return its 00100 * numeric identifier. Valid strings may be obtained by calling 00101 * apol_objclass_to_str(). 00102 * 00103 * @param objclass Object class, one of "any", "file", etc. 00104 * 00105 * @return Numeric identifier for object class, or 0 if unknown. 00106 * 00107 * @see <qpol/genfscon_query.h> for a list of valid object classes. 00108 */ 00109 extern uint32_t apol_str_to_objclass(const char *objclass); 00110 00111 /** 00112 * Given a fs_use behavior type, return a read-only string that 00113 * describes that fs_use behavior. 00114 * 00115 * @param behavior A fs_use behavior, one of QPOL_FS_USE_PSID, 00116 * QPOL_FS_USE_XATTR, etc. 00117 * 00118 * @return A string that describes the behavior, or NULL if the 00119 * behavior is invalid. <b>Do not free() this string.</b> 00120 */ 00121 extern const char *apol_fs_use_behavior_to_str(uint32_t behavior); 00122 00123 /** 00124 * Given a fs_use behavior string, return its numeric value. 00125 * 00126 * @param behavior A fs_use behavior, one of "fs_use_psid", 00127 * "fs_use_xattr", etc. 00128 * 00129 * @return A numeric representation for the behavior, one of 00130 * QPOL_FS_USE_PSID, QPOL_FS_USE_XATTR, etc, or < 0 if the string is 00131 * invalid. 00132 */ 00133 extern int apol_str_to_fs_use_behavior(const char *behavior); 00134 00135 /** 00136 * Given a rule type, return a read-only string that describes that 00137 * rule. 00138 * 00139 * @param rule_type A policy rule type, one of QPOL_RULE_ALLOW, 00140 * QPOL_RULE_TYPE_CHANGE, etc. 00141 * 00142 * @return A string that describes the rule, or NULL if the rule_type 00143 * is invalid. <b>Do not free() this string.</b> 00144 */ 00145 extern const char *apol_rule_type_to_str(uint32_t rule_type); 00146 00147 /** 00148 * Given a conditional expression type, return a read-only string that 00149 * describes that operator. 00150 * 00151 * @param expr_type An expression type, one of QPOL_COND_EXPR_BOOL, 00152 * QPOL_COND_EXPR_NOT, etc. 00153 * 00154 * @return A string that describes the expression, or NULL if the 00155 * expr_type is invalid. <b>Do not free() this string.</b> 00156 */ 00157 extern const char *apol_cond_expr_type_to_str(uint32_t expr_type); 00158 00159 /** 00160 * Given a file name, search and return that file's path on the 00161 * running system. First search the present working directory, then 00162 * the directory at APOL_INSTALL_DIR (an environment variable), then 00163 * apol's install dir. 00164 * 00165 * @param file_name File to find. 00166 * 00167 * @return File's path, or NULL if not found. Caller must free() this 00168 * string afterwards. 00169 */ 00170 extern char *apol_file_find(const char *file_name); 00171 00172 /** 00173 * Given a file name, search and return that file's full path 00174 * (directory + file name) on the running system. First search the 00175 * present working directory, then the directory at APOL_INSTALL_DIR 00176 * (an environment variable), then apol's install dir. 00177 * 00178 * @param file_name File to find. 00179 * 00180 * @return File's path + file name, or NULL if not found. Caller must 00181 * free() this string afterwards. 00182 */ 00183 extern char *apol_file_find_path(const char *file_name); 00184 00185 /** 00186 * Given a file name for a user configuration, search and return that 00187 * file's path + file name in the user's home directory. 00188 * 00189 * @param file_name File to find. 00190 * 00191 * @return File's path + file name, or NULL if not found. Caller must 00192 * free() this string afterwards. 00193 */ 00194 extern char *apol_file_find_user_config(const char *file_name); 00195 00196 /** 00197 * Given a file name, read the file's contents into a newly allocated 00198 * buffer. The caller must free() this buffer afterwards. 00199 * 00200 * @param fname Name of file to read. 00201 * @param buf Reference to a newly allocated buffer. 00202 * @param len Reference to the number of bytes read. 00203 * 00204 * @return 0 on success, < 0 on error. 00205 */ 00206 extern int apol_file_read_to_buffer(const char *fname, char **buf, size_t * len); 00207 /** 00208 * Given a file pointer into a config file, read and return the value 00209 * for the given config var. The caller must free() the returned 00210 * string afterwards. 00211 * 00212 * @param var Name of configuration variable to obtain. 00213 * @param fp An open file pointer into a configuration file. This 00214 * function will not maintain the pointer's current location. 00215 * 00216 * @return A newly allocated string containing the variable's value, 00217 * or NULL if not found or error. 00218 */ 00219 extern char *apol_config_get_var(const char *var, FILE * fp); 00220 00221 /** 00222 * Given a string of tokens, allocate and return a vector of strings 00223 * initialized to those tokens. 00224 * 00225 * @param s String to split. 00226 * @param delim Delimiter for tokens, as per strsep(3). 00227 * 00228 * @return A newly allocated vector of strings containing the 00229 * variable's values, or NULL if not found or error. Note that the 00230 * vector could be empty if the config var does not exist or has an 00231 * empty value. The caller must call apol_vector_destroy() 00232 * afterwards. 00233 */ 00234 extern apol_vector_t *apol_str_split(const char *s, const char *delim); 00235 00236 /** 00237 * Given a vector of strings, allocate and return a string that joins 00238 * the vector using the given separator. The caller is responsible 00239 * for free()ing the string afterwards. 00240 * 00241 * @param list Vector of strings to join. 00242 * @param delim Delimiter character(s) for the concatenated string. 00243 * 00244 * @return An allocated concatenated string, or NULL upon error. If 00245 * the list is empty then return an empty string. The caller is 00246 * responsible for calling free() upon the return value. 00247 */ 00248 extern char *apol_str_join(const apol_vector_t * list, const char *delim); 00249 00250 /** 00251 * Given a mutable string, modify the string by removing both starting 00252 * and trailing whitespace characters. 00253 * 00254 * @param str String to modify. 00255 */ 00256 extern void apol_str_trim(char *str); 00257 00258 /** 00259 * Append a string to an existing dynamic mutable string, expanding 00260 * the target string if necessary. The caller must free() the target 00261 * string. If tgt is NULL then initially allocate the resulting 00262 * string. 00263 * 00264 * @param tgt Reference to a string to modify, or NULL to create a new 00265 * string. 00266 * @param tgt_sz Pointer to number of bytes currently allocated to 00267 * tgt. This will be updated with the new string size. If *tgt is 00268 * NULL then this existing value is ignored. (It will still be updated 00269 * afterwards). 00270 * @param str String to append. 00271 * 00272 * @return 0 on success. On error, return < 0 and set errno; tgt will be 00273 * free()d and set to NULL, tgt_sz will be set to 0. 00274 */ 00275 extern int apol_str_append(char **tgt, size_t * tgt_sz, const char *str); 00276 00277 /** 00278 * Append a string to an existing dynamic mutable string, expanding 00279 * the target string if necessary. The string to append is computed 00280 * using the format string, as per printf(3). The caller must free() 00281 * the target string. If tgt is NULL then initially allocate the 00282 * resulting string. 00283 * 00284 * @param tgt Reference to a string to modify, or NULL to create a new 00285 * string. 00286 * @param tgt_sz Pointer to number of bytes currently allocated to 00287 * tgt. This will be updated with the new string size. If *tgt is 00288 * NULL then the existing value is ignored. (It will still be updated 00289 * afterwards). 00290 * @param fmt Format for the string with which append, as per 00291 * printf(3). 00292 * 00293 * @return 0 on success. On error, return < 0 and set errno; tgt will be 00294 * free()d and set to NULL, tgt_sz will be set to 0. 00295 */ 00296 extern int apol_str_appendf(char **tgt, size_t * tgt_sz, const char *fmt, ...); 00297 00298 /* declaration duplicated below to satisfy doxygen */ 00299 extern int apol_str_appendf(char **tgt, size_t * tgt_sz, const char *fmt, ...) __attribute__ ((format(printf, 3, 4))); 00300 00301 /** 00302 * Test whether a given string is only white space. 00303 * 00304 * @param str String to test. 00305 * @return 1 if string is either NULL or only whitespace, 0 otherwise. 00306 */ 00307 extern int apol_str_is_only_white_space(const char *str); 00308 00309 /** 00310 * Wrapper around strcmp for use in vector and BST comparison functions. 00311 * 00312 * @param a String to compare. 00313 * @param b The other string to compare. 00314 * @param unused Not used. (exists to match expected function signature) 00315 * 00316 * @return Less than, equal to, or greater than 0 if string a is found 00317 * to be less than, identical to, or greater than string b 00318 * respectively. 00319 */ 00320 extern int apol_str_strcmp(const void *a, const void *b, void *unused __attribute__ ((unused))); 00321 00322 /** 00323 * Wrapper around strdup for use in vector and BST cloning functions. 00324 * 00325 * @param elem String to duplicate. 00326 * @param unused Not used. (exists to match expected function signature) 00327 * 00328 * @return A new string that is a duplicate of elem, or NULL upon error. 00329 */ 00330 extern void *apol_str_strdup(const void *elem, void *unused __attribute__ ((unused))); 00331 00332 #ifdef __cplusplus 00333 } 00334 #endif 00335 00336 #endif
