= Using the Apache Portable Runtime (APR) =

The goal of the [http://apr.apache.org APR] project is to provide an API to which software developers may code and be assured of predictable if not identical behaviour regardless of the platform on which their software is built, relieving them of the need to code special-case conditions to work around or take advantage of platform-specific deficiencies or features.

It contains, among other things, the following functionality:
	
 * Reading and writing of files
 * Character set conversion
 * Network communications using sockets
 * String management like C++ including natural order management
 * Filename canonicalization
 * Memory management
 * Global lock management
 * Threads and process management
 * Dynamic library loading routines
 * Memory mapped and shared memory
 * UNIX Password management routines
 * Time management used for internet type conversions
	

== Missing documentation/introductory material ==
	
Unfortunately, the official documentation consists of only a Doxygen generated description of the complete [http://apr.apache.org/docs/apr/1.2/ API] (which is, function by function, quite thorough). There is a tutorial at http://dev.ariel-networks.com/apr/apr-tutorial/, but strangely this is not mentioned on the project web site. Moreover, this tutorial is from 2005.

There seems to be no official tutorial.

For specific questions, it might be helpful to browse the [http://mail-archives.apache.org/mod_mbox/apr-dev/ mailing list archives] (which are not searchable, unfortunately).

A good example of a bad documentation is the description of the functions apr_setup_signal_thread() and apr_signal_thread() in the section [http://apr.apache.org/docs/apr/1.2/group__apr__thread__proc.html Threads and Process Functions]. What the hell does this mean?

== APR Hello World ==

The following is a minimal program that makes use of the APR library:

{{{
#include <stdio.h>
#include <apr_general.h>

int main(int argc, const char *argv[])
{
    apr_status_t rv;

    rv = apr_initialize();
    if( rv != APR_SUCCESS ) {
      char errbuf[256];
      apr_strerror(rv, errbuf, sizeof(errbuf));
      puts(errbuf);  /* show the error description */
      return -1;
    }

    printf( "Hello APR world!\n");

    apr_terminate();
    return 0;
}
}}}



=== Compiling under Unix ===

You have to define the macro `LARGEFILE64_SOURCE` and link against the `apr-1` library::

{{{
cc -o try-helloworld-APR try-helloworld-APR.c -D_LARGEFILE64_SOURCE -I/usr/include/apr-1.0/ -lapr-1
}}}


=== Compiling under Windows ===

I (Joachim) do not know. I managed to build the libs and run the test suite with Visual Studio as described on http://apr.apache.org/compiling_win32.html, but I do not know where the headers and libs have gone to and how I can link against them. This is more a problem of "How do I develop under Windows" than an APR specific problem. 

Nevertheless, the project web site merely says

{{{
 Integrating the Library

    We should tell ya'll 'bout this, no?
}}}


== FAQ ==

'''Q''': How can I do getpid() with APR?

 '''A''': There is no such concept as a PID on all OSes, so there is no getpid() in APR. See also [http://markmail.org/message/pplgn3urie67htbc#query:+page:1+mid:jjbynsslecwuww3g+state:results this posting].

'''Q''': Which versions of MS-Windows are POSIX compliant? What does this mean for UNIX library function like sleep()? do they exist on windows and have the same behavior? (Are they portable?)

 '''A''': ???

'''Q''': How do I sleep() with APR?

 '''A''': ???

'''Q''': How do I send and catch signals with APR?

 '''A''': ???

'''Q''': Where can I read the latest POSIX.1 specification online?

 '''A''': Go to http://www.unix.org/version3/online.html, enable cookies, and click "Register to read or download the specification". You might also like to read the [http://www.opengroup.org/austin/papers/posix_faq.html POSIX FAQ].