Introduction to Hotpatch=========================Hotpatch is a library that can be used to dynamically load a shared library(.so) file on Linux from one process into another already running process,without affecting the execution of the target process. The API is a C API, butalso supported in C++.The current version is 0.2.The limitations, directions on how to use, and possible uses of hotpatch will beexplained in this document.The main idea of hotpatch stems from the fact that in Linux, it is not easy toload a library into another already running process. In Windows, there is an APIcalled CreateRemoteThread() that can load a library into another process veryeasily with a couple of API calls. Hotpatch makes this functionality availableto Linux users and developers, with a single API call. Unlike other availableinjection libraries, hotpatch restores the execution of the process to itsoriginal state.The user can do the following with hotpatch:- load his/her own .so file into an already running process- invoke a custom symbol/function in that .so file- pass arguments to that function as long as it is serialized to the form of a  byte buffer and length of the buffer. This shall be explained more later.Hotpatch is available as an API with a header file called "hotpatch.h" and a.so file called "libhotpatch.so", and also a commandline application called"hotpatcher" which can inject .so files into processes via the commandlineitself. Hotpatch also comes with a test .so called "libhotpatchtest.so"which can be used via the commandline "hotpatcher" application to test outthe working of hotpatch on any system. The "libhotpatchtest.so" has a symbol"mysym" that can be invoked, and it writes to the "/tmp/hotpatchtest.log" filewith the timestamp at which the .so file was injected and anything else.Limitations============NOTE: Currently if hotpatch is compiled in 64-bit mode, it can inject librariesonly in 64-bit processes, and if compiled in 32-bit mode can inject librariesonly in 32-bit processes. It cannot inject from a 64-bit to a 32-bit process orfrom a 32-bit to a 64-bit process.There are some limitations, the main being that the user can inject a library.so file only in a process on which the user has privileges over. For example,as the root user, hotpatch can inject libraries into any process, but as aregular non-root user, hotpatch can inject libraries into only those processesthat hotpatch has access to, i.e. the user's processes and any other via sudoprivileges.The other limitation is that if the user needs to compile his shared librarywith the linker options "-fPIC -nostartfiles" so that hotpatch can reliably loadthe .so file.Another limitation is that injection for a particular .so file can happen onlyonce in the target process. Each library that is injected can be injected onlyonce into the target process.Usage: API===========The "hotpatch.h" header file needs to be included by the user. There are 3 mainAPI calls that matter. Each of them have to be called in the order as shownbelow in the sample program.- hotpatch_t *hotpatch_create(pid_t pid, int verbose);This function takes a PID of the target process, and the verbosity level(between 0 to 6), and returns an opaque object which contains further intimatedetails about the process such as current library mappings, and locations of theimportant functions needed for hotpatch to do its work.- int hotpatch_inject_library(hotpatch_t *hp,							  const char *sofile,							  const char *symbol,							  const unsigned char *data,							  size_t datalen,							  uintptr_t *out_addr,							  uintptr_t *out_result);This function takes the newly created hotpatch object, along with a path to theshared library in the variable "sofile", the optional function "symbol" to invoke,along with the serialized arguments to the function provided in "data" and"datalen" which are also optional. The return address of where the library wasloaded is returned in "out_addr" and the return value of the invocation of"symbol" is returned in "out_result". On success this returns 0 and on failurereturns -1.The verbosity levels can be adjusted accordingly from 0 to 6 to see debugginginformation for investigating errors.The usefulness of the "data" and "datalen" parameters is extremely high. Supposethe user has a custom function they want to invoke, and the arguments of thefunction is a big struct or a class. The user can then write a wrapper functionthat takes a serialized buffer of this struct/class along with the length of thebuffer and invoke that wrapper function. This wrapper function can thendeserialize this buffer into the struct/class as needed and call the actualfunction that the user really wanted to invoke. This functionality is onlyavailable by the API and not by the "hotpatcher" executable.- void hotpatch_destroy(hotpatch_t *hp);This function cleans up memory and resources used by the hotpatch opaque object.Sample Program==============#include 
      
       int main(int argc, char **argv){	pid_t pid = argc > 1 ? atoi(argv[1]) : 0;	hotpatch_t *hp = hotpatch_create(pid, 1);	if (hp) {		unsigned char *data = (unsigned char *)"my custom serialized data";		size_t datalen = strlen((char *)data) + 1;		uintptr_t result1, result2;		hotpatch_inject_library(hp, "libhotpatchtest.so", "mysym",						data, datalen, &result1, &result2);		hotpatch_destroy(hp);	}	return 0;}Usage: Hotpatcher==================The commandline "hotpatcher" can be executed with the "-h" option to see thevarious options that are supported.A sample execution of "hotpatcher" into the current running shell can be done asbelow:Let's say the library libhotpatchtest.so is in the current directory.bash> ./hotpatcher -l ./libhotpatchtest.so -s mysym -v1 $$On success the "/tmp/hotpatchtest.log" file can be checked if it has thetimestamp of the injection.Uses of Hotpatch=================Most uses of hotpatch are related to custom modifications of processes for whichthe users do not have source code available.- System administrators can use hotpatch to inject their own custom libraries in  already running processes and change behavior as per requirement. Some suchbehavior could be adding a library that creates a thread and heartbeats to amonitoring system.- Many software applications, that are not mission critical, are not built with  mechanisms to update their software without having to stop the application andrestarting it. Hotpatch can help modify applications to restart and do otherfancy tricks without losing the PID and the other states such as file handles ofthe applications that might be very useful or too risky to let go.- Users can inject a library and then set up RPC service calls for the target  application without changing any code.- Users can inject a library and with import table modifications can instrument  the target application for things like profiling, reverse engineering and alsodebugging. This is useful as it does not necessarily need the application to berecompiled and performance numbers can be extracted. The code to do import tablemodifications is currently outside the scope of hotpatch.- Users can create threads in other processes and make them work like a cluster  of processes that they control.- Users can modify another application and make it perform better by doing  tricks in the injected code.License & Copyright===================The license/copyright can be found in the COPYRIGHT document in the source code.==THE END==