1 files changed, 336 insertions, 0 deletions
diff --git a/libapol/include/apol/util.h b/libapol/include/apol/util.h
new file mode 100644
index 0000000..99db168
--- /dev/null
+++ b/libapol/include/apol/util.h
@@ -0,0 +1,336 @@
+/**
+ * @file
+ *
+ * Miscellaneous, uncategorized functions for libapol.
+ *
+ * @author Jeremy A. Mowery jmowery@tresys.com
+ * @author Jason Tang  jtang@tresys.com
+ *
+ * Copyright (C) 2001-2007 Tresys Technology, LLC
+ *
+ *  This library is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU Lesser General Public
+ *  License as published by the Free Software Foundation; either
+ *  version 2.1 of the License, or (at your option) any later version.
+ *
+ *  This library is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ *  Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public
+ *  License along with this library; if not, write to the Free Software
+ *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
+#ifndef APOL_UTIL_H
+#define APOL_UTIL_H
+
+#ifdef	__cplusplus
+extern "C"
+{
+#endif
+
+#include "vector.h"
+
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+/**
+ * Return an immutable string describing this library's version.
+ *
+ * @return String describing this library.
+ */
+	extern const char *libapol_get_version(void);
+
+/**
+ * Given a portcon protocol, return a read-only string that describes
+ * that protocol.
+ *
+ * @param protocol Portcon protocol, one of IPPROTO_TCP or IPPROTO_UDP
+ * from netinet/in.h.
+ *
+ * @return A string that describes the protocol, or NULL if the
+ * protocol is invalid.  <b>Do not free() this string.</b>
+ */
+	extern const char *apol_protocol_to_str(uint8_t protocol);
+
+/**
+ * Given the name of a portcon protocol, return its numeric value.
+ *
+ * @param protocol_str Portcon protocol, one of "tcp", "TCP", "udp", or "UDP".
+ *
+ * @return Numeric value for the protocol, one of IPPROTO_TCP or IPPROTO_UDP
+ * from netinet/in.h.  Upon error return 0.
+ */
+	extern uint8_t apol_str_to_protocol(const char *protocol_str);
+
+/**
+ * Given a string representing and IP value (mask or address, IPv4 or
+ * IPv6), write to an array that value in the same bit order that
+ * qpol uses.  If the IP was in IPv4 format, only write to the first
+ * element and zero the remainder.
+ *
+ * @param str A string representing and IP value, either in IPv4 or
+ * IPv6 format.
+ * @param ip Array to which write converted value.
+ *
+ * @return QPOL_IPV4 if the string is in IPv4 format, QPOL_IPV6 if
+ * in IPv6, < 0 on error.
+ */
+	extern int apol_str_to_internal_ip(const char *str, uint32_t ip[4]);
+
+/**
+ * Given a genfscon object class, return a read-only string that
+ * describes that class.
+ *
+ * @param objclass Object class, one of QPOL_CLASS_BLK_FILE,
+ * QPOL_CLASS_CHR_FILE, etc.
+ *
+ * @return A string that describes the object class, or NULL if the
+ * object class is invalid.  <b>Do not free() this string.</b>
+ *
+ * @see <qpol/genfscon_query.h> for a list of valid object classes.
+ */
+	extern const char *apol_objclass_to_str(uint32_t objclass);
+
+/**
+ * Given a string representing a genfscon object class, return its
+ * numeric identifier.  Valid strings may be obtained by calling
+ * apol_objclass_to_str().
+ *
+ * @param objclass Object class, one of "any", "file", etc.
+ *
+ * @return Numeric identifier for object class, or 0 if unknown.
+ *
+ * @see <qpol/genfscon_query.h> for a list of valid object classes.
+ */
+	extern uint32_t apol_str_to_objclass(const char *objclass);
+
+/**
+ * Given a fs_use behavior type, return a read-only string that
+ * describes that fs_use behavior.
+ *
+ * @param behavior A fs_use behavior, one of QPOL_FS_USE_PSID,
+ * QPOL_FS_USE_XATTR, etc.
+ *
+ * @return A string that describes the behavior, or NULL if the
+ * behavior is invalid.  <b>Do not free() this string.</b>
+ */
+	extern const char *apol_fs_use_behavior_to_str(uint32_t behavior);
+
+/**
+ * Given a fs_use behavior string, return its numeric value.
+ *
+ * @param behavior A fs_use behavior, one of "fs_use_psid",
+ * "fs_use_xattr", etc.
+ *
+ * @return A numeric representation for the behavior, one of
+ * QPOL_FS_USE_PSID, QPOL_FS_USE_XATTR, etc, or < 0 if the string is
+ * invalid.
+ */
+	extern int apol_str_to_fs_use_behavior(const char *behavior);
+
+/**
+ * Given a rule type, return a read-only string that describes that
+ * rule.
+ *
+ * @param rule_type A policy rule type, one of QPOL_RULE_ALLOW,
+ * QPOL_RULE_TYPE_CHANGE, etc.
+ *
+ * @return A string that describes the rule, or NULL if the rule_type
+ * is invalid.  <b>Do not free() this string.</b>
+ */
+	extern const char *apol_rule_type_to_str(uint32_t rule_type);
+
+/**
+ * Given a conditional expression type, return a read-only string that
+ * describes that operator.
+ *
+ * @param expr_type An expression type, one of QPOL_COND_EXPR_BOOL,
+ * QPOL_COND_EXPR_NOT, etc.
+ *
+ * @return A string that describes the expression, or NULL if the
+ * expr_type is invalid.  <b>Do not free() this string.</b>
+ */
+	extern const char *apol_cond_expr_type_to_str(uint32_t expr_type);
+
+/**
+ * Given a file name, search and return that file's path on the
+ * running system.  First search the present working directory, then
+ * the directory at APOL_INSTALL_DIR (an environment variable), then
+ * apol's install dir.
+ *
+ * @param file_name File to find.
+ *
+ * @return File's path, or NULL if not found.  Caller must free() this
+ * string afterwards.
+ */
+	extern char *apol_file_find(const char *file_name);
+
+/**
+ * Given a file name, search and return that file's full path
+ * (directory + file name) on the running system.  First search the
+ * present working directory, then the directory at APOL_INSTALL_DIR
+ * (an environment variable), then apol's install dir.
+ *
+ * @param file_name File to find.
+ *
+ * @return File's path + file name, or NULL if not found.  Caller must
+ * free() this string afterwards.
+ */
+	extern char *apol_file_find_path(const char *file_name);
+
+/**
+ * Given a file name for a user configuration, search and return that
+ * file's path + file name in the user's home directory.
+ *
+ * @param file_name File to find.
+ *
+ * @return File's path + file name, or NULL if not found.  Caller must
+ * free() this string afterwards.
+ */
+	extern char *apol_file_find_user_config(const char *file_name);
+
+/**
+ * Given a file name, read the file's contents into a newly allocated
+ * buffer.  The caller must free() this buffer afterwards.
+ *
+ * @param fname Name of file to read.
+ * @param buf Reference to a newly allocated buffer.
+ * @param len Reference to the number of bytes read.
+ *
+ * @return 0 on success, < 0 on error.
+ */
+	extern int apol_file_read_to_buffer(const char *fname, char **buf, size_t * len);
+/**
+ * Given a file pointer into a config file, read and return the value
+ * for the given config var.  The caller must free() the returned
+ * string afterwards.
+ *
+ * @param var Name of configuration variable to obtain.
+ * @param fp An open file pointer into a configuration file.  This
+ * function will not maintain the pointer's current location.
+ *
+ * @return A newly allocated string containing the variable's value,
+ * or NULL if not found or error.
+ */
+	extern char *apol_config_get_var(const char *var, FILE * fp);
+
+/**
+ * Given a string of tokens, allocate and return a vector of strings
+ * initialized to those tokens.
+ *
+ * @param s String to split.
+ * @param delim Delimiter for tokens, as per strsep(3).
+ *
+ * @return A newly allocated vector of strings containing the
+ * variable's values, or NULL if not found or error.  Note that the
+ * vector could be empty if the config var does not exist or has an
+ * empty value.  The caller must call apol_vector_destroy()
+ * afterwards.
+ */
+	extern apol_vector_t *apol_str_split(const char *s, const char *delim);
+
+/**
+ * Given a vector of strings, allocate and return a string that joins
+ * the vector using the given separator.  The caller is responsible
+ * for free()ing the string afterwards.
+ *
+ * @param list Vector of strings to join.
+ * @param delim Delimiter character(s) for the concatenated string.
+ *
+ * @return An allocated concatenated string, or NULL upon error.  If
+ * the list is empty then return an empty string.  The caller is
+ * responsible for calling free() upon the return value.
+ */
+	extern char *apol_str_join(const apol_vector_t * list, const char *delim);
+
+/**
+ * Given a mutable string, modify the string by removing both starting
+ * and trailing whitespace characters.
+ *
+ * @param str String to modify.
+ */
+	extern void apol_str_trim(char *str);
+
+/**
+ * Append a string to an existing dynamic mutable string, expanding
+ * the target string if necessary.  The caller must free() the target
+ * string.  If tgt is NULL then initially allocate the resulting
+ * string.
+ *
+ * @param tgt Reference to a string to modify, or NULL to create a new
+ * string.
+ * @param tgt_sz Pointer to number of bytes currently allocated to
+ * tgt.  This will be updated with the new string size.  If *tgt is
+ * NULL then this existing value is ignored.  (It will still be updated
+ * afterwards).
+ * @param str String to append.
+ *
+ * @return 0 on success.  On error, return < 0 and set errno; tgt will be
+ * free()d and set to NULL, tgt_sz will be set to 0.
+ */
+	extern int apol_str_append(char **tgt, size_t * tgt_sz, const char *str);
+
+/**
+ * Append a string to an existing dynamic mutable string, expanding
+ * the target string if necessary.  The string to append is computed
+ * using the format string, as per printf(3).  The caller must free()
+ * the target string.  If tgt is NULL then initially allocate the
+ * resulting string.
+ *
+ * @param tgt Reference to a string to modify, or NULL to create a new
+ * string.
+ * @param tgt_sz Pointer to number of bytes currently allocated to
+ * tgt.  This will be updated with the new string size.  If *tgt is
+ * NULL then the existing value is ignored.  (It will still be updated
+ * afterwards).
+ * @param fmt Format for the string with which append, as per
+ * printf(3).
+ *
+ * @return 0 on success.  On error, return < 0 and set errno; tgt will be
+ * free()d and set to NULL, tgt_sz will be set to 0.
+ */
+	extern int apol_str_appendf(char **tgt, size_t * tgt_sz, const char *fmt, ...);
+
+/* declaration duplicated below to satisfy doxygen */
+	extern int apol_str_appendf(char **tgt, size_t * tgt_sz, const char *fmt, ...) __attribute__ ((format(printf, 3, 4)));
+
+/**
+ * Test whether a given string is only white space.
+ *
+ * @param str String to test.
+ * @return 1 if string is either NULL or only whitespace, 0 otherwise.
+ */
+	extern int apol_str_is_only_white_space(const char *str);
+
+/**
+ * Wrapper around strcmp for use in vector and BST comparison functions.
+ *
+ * @param a String to compare.
+ * @param b The other string to compare.
+ * @param unused Not used. (exists to match expected function signature)
+ *
+ * @return Less than, equal to, or greater than 0 if string a is found
+ * to be less than, identical to, or greater than string b
+ * respectively.
+ */
+	extern int apol_str_strcmp(const void *a, const void *b, void *unused __attribute__ ((unused)));
+
+/**
+ * Wrapper around strdup for use in vector and BST cloning functions.
+ *
+ * @param elem String to duplicate.
+ * @param unused Not used. (exists to match expected function signature)
+ *
+ * @return A new string that is a duplicate of elem, or NULL upon error.
+ */
+	extern void *apol_str_strdup(const void *elem, void *unused __attribute__ ((unused)));
+
+#ifdef	__cplusplus
+}
+#endif
+
+#endif