Initial import

1 files changed, 416 insertions, 0 deletions

diff --git a/src/libr.h b/src/libr.h
new file mode 100644
index 0000000..b1aa1d7
--- /dev/null
+++ b/src/libr.h
@@ -0,0 +1,416 @@
+/*
+ *
+ *  Copyright (c) 2008-2011 Erich Hoover
+ *
+ *  libr - Add resources into ELF binaries
+ *
+ * This program 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 program 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 General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ *
+ * To provide feedback, report bugs, or otherwise contact me:
+ * ehoover at mines dot edu
+ *
+ */
+
+#ifndef __LIBR_H
+#define __LIBR_H
+
+#include <sys/types.h>
+
+#define DEPRECATED_FN           __attribute__ ((deprecated))
+#define ALIAS_FN(fn)            __attribute__ ((weak, alias (#fn)))
+
+/**
+ * @addtogroup libr_status libr_status
+ * @brief Enumeration of possible libr status values.
+ * @{
+ * \#include <libr.h>
+ */
+/** Possible libr status values */
+typedef enum {
+	LIBR_OK                     =   0, /**< Success */
+	LIBR_ERROR_GETEHDR          =  -1, /**< Failed to obtain ELF header: */
+	LIBR_ERROR_NOTABLE          =  -2, /**< No ELF string table */
+	LIBR_ERROR_TABLE            =  -3, /**< Failed to open string table: */
+	LIBR_ERROR_GETDATA          =  -4, /**< Failed to obtain data of section */
+	LIBR_ERROR_GETSHDR          =  -5, /**< Failed to obtain ELF section header: */
+	LIBR_ERROR_SIZEMISMATCH     =  -6, /**< Section's data size does not make sense */
+	LIBR_ERROR_UPDATE           =  -7, /**< Failed to perform dynamic update: */
+	LIBR_ERROR_NEWSECTION       =  -8, /**< Failed to create new section */
+	LIBR_ERROR_NEWDATA          =  -9, /**< Failed to create data for section */
+	LIBR_ERROR_REMOVESECTION    = -10, /**< Failed to remove section: */
+	LIBR_ERROR_NOSECTION        = -11, /**< ELF resource section not found */
+	LIBR_ERROR_STRPTR           = -12, /**< Failed to obtain section string pointer: */
+	LIBR_ERROR_NOTRESOURCE      = -13, /**< Not a valid libr-resource */
+	LIBR_ERROR_EXPANDSECTION    = -14, /**< Failed to expand section */
+	LIBR_ERROR_WRONGFORMAT      = -15, /**< Invalid input file format */
+	LIBR_ERROR_SETFLAGS         = -16, /**< Failed to set flags for section */
+	LIBR_ERROR_NOPERM           = -17, /**< Open handle with LIBR_READ_WRITE access */
+	LIBR_ERROR_NOSIZE           = -18, /**< Failed to obtain file size */
+	LIBR_ERROR_SETFORMAT        = -19, /**< Failed to set output file format to input file format */
+	LIBR_ERROR_SETARCH          = -20, /**< Failed to set output file architecture to input file architecture */
+	LIBR_ERROR_OVERWRITE        = -21, /**< Section already exists, over-write not specified */
+	LIBR_ERROR_COMPRESS         = -22, /**< Failed to compress resource data */
+	LIBR_ERROR_INVALIDTYPE      = -23, /**< Invalid data storage type specified */
+	LIBR_ERROR_MEMALLOC         = -24, /**< Failed to allocate memory for data */
+	LIBR_ERROR_INVALIDPARAMS    = -25, /**< Invalid parameters passed to function */
+	LIBR_ERROR_UNCOMPRESS       = -26, /**< Failed to uncompress resource data */
+	LIBR_ERROR_ZLIBINIT         = -27, /**< zlib library initialization failed */
+	LIBR_ERROR_OPENFAILED       = -28, /**< Failed to open input file */
+	LIBR_ERROR_BEGINFAILED      = -29, /**< Failed to open ELF file: */
+	LIBR_ERROR_WRITEPERM        = -30, /**< No write permission for file */
+	LIBR_ERROR_UNSUPPORTED      = -31, /**< The requested operation is not supported by the backend */
+} libr_status;
+/**
+ * @}
+ */
+
+typedef enum {
+	LIBR_READ       = 0,
+	LIBR_READ_WRITE = 1,
+} libr_access_t;
+
+typedef enum {
+	LIBR_UNCOMPRESSED = 0,
+	LIBR_COMPRESSED   = 1
+} libr_type_t;
+
+typedef enum {
+	LIBR_NOOVERWRITE = 0,
+	LIBR_OVERWRITE   = 1
+} libr_overwrite_t;
+
+#ifdef __LIBR_BUILD__
+	#include "libr-internal.h"
+	#if __LIBR_BACKEND_libbfd__
+		#include "libr-bfd.h"
+	#elif __LIBR_BACKEND_libelf__
+		#include "libr-elf.h"
+	#elif __LIBR_BACKEND_readonly__
+		#include "libr-ro.h"
+	#else /* LIBR_BACKEND */
+		#error "Unhandled backend"
+	#endif /* LIBR_BACKEND */
+	#include "libr-backends.h"
+#else
+	struct _libr_file;
+	typedef struct _libr_file libr_file;
+#endif /* __LIBR_BUILD__ */
+
+/*************************************************************************
+ * libr Resource Management API
+ *************************************************************************/
+
+/**
+ * @page libr_clear Remove a resource from an ELF executable.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>int libr_clear(libr_file *handle, char *resourcename);</b>
+ * 
+ * @section DESCRIPTION
+ * 	Removes a libr-compatible resource from an ELF executable.  The handle
+ * 	must be opened using <b>libr_open</b>(3) with either <b>LIBR_WRITE</b>
+ * 	 or <b>LIBR_READ_WRITE</b> access in order to remove a resource.
+ * 
+ * 	Please note that resource removal does not occur until the handle is
+ * 	closed using <b>libr_close</b>(3).
+ * 	
+ * 	@param handle A handle returned by <b>libr_open</b>(3).
+ * 	@param resourcename The name of the libr-compatible resource to remove. 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_open</b>(3), <b>libr_close</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+int libr_clear(libr_file *handle, char *resourcename);
+
+/**
+ * @page libr_close Close a handle to an ELF executable.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>void libr_close(libr_file *handle);</b>
+ * 
+ * @section DESCRIPTION
+ * 	Handles opened with <b>libr_open</b>(3) should be closed with
+ * 	<b>libr_close</b>() when they are no-longer needed by the calling
+ * 	application. 
+ * 	
+ * 	@param handle The handle to close. 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_open</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+void libr_close(libr_file *handle);
+
+/**
+ * @page libr_errmsg Return a detailed description of the last
+ * 	libr-related error.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>char *libr_errmsg(void);</b>
+ * 
+ * @section DESCRIPTION
+ * 	Returns a detailed string describing the last error encountered by
+ * 	the libr resource library.  The string is an internal error
+ * 	description, so it should not be freed.
+ * 	
+ * 	If no errors have been encountered then NULL is returned. 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_errno</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+char *libr_errmsg(void);
+
+/**
+ * @page libr_errno Return a status code describing the last
+ * 	libr-related error.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>libr_status libr_errno(void);</b>
+ * 
+ * @section DESCRIPTION
+ * 	Returns a code corresponding to the last error encountered by
+ * 	the libr resource library.  For a detailed description of possible
+ * 	return values see <b>libr_status</b>(3).
+ * 	
+ * 	To get a user-readable string corresponding to the last error the
+ * 	<b>libr_errmsg</b>(3) function should be used instead. 
+ * 	
+ * 	If no errors have been encountered then <b>LIBR_OK</b> is returned. 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_errmsg</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+libr_status libr_errno(void);
+
+/**
+ * @page libr_list Obtain the name of a libr ELF resource (by index).
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>char *libr_list(libr_file *file_handle, unsigned int resourceid);</b>
+ * 
+ * @section DESCRIPTION
+ * 	Returns the name of a libr-compatible resource stored in an ELF binary
+ * 	corresponding to the given resource index.  The index value ranges from
+ * 	0 to the value returned by <b>libr_resources</b>(3), which returns the
+ * 	total number of libr-compatible resources stored in the ELF binary.
+ * 	
+ * 	@param handle A handle returned by <b>libr_open</b>(3).
+ * 	@param resourceid The index of the libr-compatible resource for which
+ * 		the name will be returned.
+ * 	
+ * 	@return Returns a string containing the name of the resource section.  This
+ * 		string is allocated when the function is called, so it <i>must be
+ * 		unallocated</i> with a call to <b>free</b>(3) when it is no-longer
+ * 		needed.  NULL is returned on failure.
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_open</b>(3), <b>free</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+char *libr_list(libr_file *file_handle, unsigned int resourceid);
+
+/**
+ * @page libr_malloc Obtain the data corresponding to a libr ELF resource.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>char *libr_malloc(libr_file *handle, char *resourcename, size_t *size);</b>
+ * 
+ * @section DESCRIPTION
+ * 	Returns the contents of a libr-compatible resource stored in an ELF binary
+ * 	corresponding to the given resource name.
+ * 	
+ * 	@param handle A handle returned by <b>libr_open</b>(3).
+ * 	@param resourcename The name of the libr-compatible resource for which
+ * 		the data will be returned.
+ * 	@param size A pointer for storing the length of the data contained in the
+ * 		the resource.  May be NULL.
+ * 	
+ * 	@return Returns NULL on failure, the pointer to a buffer containing the data
+ * 		for the resource on success.  When the buffer is no-longer used it must
+ * 		be unallocated using a call to <b>free</b>(3). 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_open</b>(3), <b>free</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+char *libr_malloc(libr_file *handle, char *resourcename, size_t *size);
+
+/**
+ * @page libr_open Open an ELF executable file for resource management.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>libr_file *libr_open(char *filename, libr_access_t access);</b>
+ * 
+ * @section DESCRIPTION
+ * 	<b>libr_open</b>() can be used on any ELF executable, however,
+ * 	<b>libr_open</b>() called with <b>LIBR_READ</b> access is only useful
+ * 	for executables that already contain libr-compatible stored resources.
+ * 	
+ * 	An application can easily access its own resources by passing NULL for
+ * 	the filename and requesting <b>LIBR_READ</b> access.  For the obvious
+ * 	reason that an actively-open application cannot edit itself, the
+ * 	calling binary may only request <b>LIBR_READ</b> access.
+ * 	
+ * 	@param filename ELF executable to manage.  Pass a NULL pointer as the
+ * 		filename in order to access the calling binary (<b>LIBR_READ</b>
+ * 		access only) @param access Requested access type (<b>LIBR_READ</b>,
+ * 		<b>LIBR_WRITE</b>, <b>LIBR_READ_WRITE</b>), the valid operations for
+ * 		the returned handle will be restricted based upon the requested access.
+ * 	@return Returns a libr file handle on success, NULL on failure.  The
+ * 		handle should be freed with <b>libr_close</b>(3) when no-longer used. 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_close</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+libr_file *libr_open(char *filename, libr_access_t access);
+
+/**
+ * @page libr_read Read out the contents of a libr ELF resource.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>int libr_read(libr_file *handle, char *resourcename, char *buffer);</b>
+ *
+ * @section WARNING
+ * 	This function does not allocate memory for the buffer, so the buffer must
+ * 	be large enough to fit the resource data.  For this reason it is suggested
+ * 	that <b>libr_malloc</b>(3) be used in preference over this function.
+ * 
+ * @section DESCRIPTION
+ * 	Reads the contents of a resource embedded in an ELF binary, the resource
+ * 	must be compatible with the libr specification.
+ * 	
+ * 	@param handle A handle returned by <b>libr_open</b>(3).
+ * 	@return Returns 1 on success, 0 on failure. 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_open</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+int libr_read(libr_file *handle, char *resourcename, char *buffer);
+
+/**
+ * @page libr_resources Returns the number of resources contained in
+ * 	the ELF binary.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>unsigned int libr_resources(libr_file *handle);</b>
+ *
+ * @section DESCRIPTION
+ * 	Returns the total number of libr-compatible resources contained
+ * 	in the ELF binary.  Intended to be used with <b>libr_list</b>(3)
+ * 	to return the full list of resources contained in the binary. 
+ * 	
+ * 	@param handle A handle returned by <b>libr_open</b>(3).
+ * 	@return The total number of libr resources in the binary.
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_open</b>(3), <b>libr_list</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+unsigned int libr_resources(libr_file *handle);
+
+/**
+ * @page libr_size Returns the uncompressed size of a libr resource.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>int libr_size(libr_file *handle, char *resourcename, size_t *size);</b>
+ *
+ * @section DESCRIPTION
+ * 	Obtain the total number of bytes consumed by the uncompressed
+ * 	version of the specific libr-resource.  Intended to be used with
+ * 	<b>libr_read</b>(3) in order to allocate a large enough buffer
+ * 	for the resource.
+ * 	
+ * 	@param handle A handle returned by <b>libr_open</b>(3).
+ * 	@param resourcename The name of the resource for which the
+ * 		size of the data section will be returned.
+ * 	@param size A pointer for storing the size of the data section.
+ * 		This pointer cannot be NULL.
+ * 	@return Returns 1 on success, 0 on failure. 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_open</b>(3), <b>libr_read</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+int libr_size(libr_file *handle, char *resourcename, size_t *size);
+
+/**
+ * @page libr_write Adds a libr resource to an ELF binary.
+ * @section SYNOPSIS
+ * 	\#include <libr.h>
+ * 	
+ * 	<b>int libr_write(libr_file *handle, char *resourcename, char *buffer, size_t size, libr_type_t type, libr_overwrite_t overwrite);</b>
+ *
+ * @section DESCRIPTION
+ * 	Adds a libr-compatible resource into the ELF binary.  The handle
+ * 	must be opened using <b>libr_open</b>(3) with either <b>LIBR_WRITE</b>
+ * 	or <b>LIBR_READ_WRITE</b> access in order to add a resource.
+ * 	
+ * 	@param handle A handle returned by <b>libr_open</b>(3).
+ * 	@param resourcename The name of the resource to create.
+ * 	@param buffer A string containing the data of the resource.
+ * 	@param size The total size of the buffer.
+ * 	@param type The method which should be used for storing the 
+ * 		data (either <b>LIBR_UNCOMPRESSED</b> or
+ * 		<b>LIBR_COMPRESSED</b>).
+ * 	@param overwrite Whether overwriting an existing resource
+ * 		should be permitted (either <b>LIBR_NOOVERWRITE</b> or
+ * 		<b>LIBR_OVERWRITE</b>). 
+ * 	@return Returns 1 on success, 0 on failure. 
+ * 
+ * @section SA SEE ALSO
+ * 	<b>libr_open</b>(3)
+ * 
+ * @section AUTHOR
+ * 	Erich Hoover <ehoover@mines.edu>
+ */
+int libr_write(libr_file *handle, char *resourcename, char *buffer, size_t size, libr_type_t type, libr_overwrite_t overwrite);
+
+#endif /* __LIBR_H */
+