This file aims to be a guide to Cyrus coding style/conventions/useful utilities
for people trying to approach the code in a sane way.  It's not well organized
right now but hopefully that will improve with time ;)

- Memory Allocation:
  - All cyrus memory allocation should be done through the libcyrus functions.
    These are all written to correctly call fatal() in the event of an
    out-of-memory condition.
  - In addition to xmalloc and xrealloc, we provide replacements for
    strdup, strndup, and a malloc that will guarantee zeroed block of memory
    (xzmalloc).
  - If you are going to need to do a large number of small allocations, and
    then free them all at once, you should look at the memory pool routines,
    which are much faster, but will leak memory until you free the entire
    pool at once.

- strlcpy vs strncpy vs memcpy
  - use strlcpy when you know the size of the buffer, e.g.:
    char buf[50];
    strlcpy(buf, src, sizeof(buf));

  - use memcpy to truncate a string into a buffer you know is large enough.
    Note that when you do this the resulting buffer will
    NOT BE NULL TERMINATED.
    memcpy(buf, src, 4);
    buf[5] = '\0'

  - you should try to avoid strncpy, since it is much slower than memcpy 
    (it zero-fills the rest of the buffer) and isn't as safe as strlcpy.

  - Use of the functions in this way will reduce the confusion involved in
    their various behaviors. In other words, this avoids things that look like:
    strncpy(buf, src, sizeof(buf)-1);

- map_refresh and map_free

  - In many cases, it is far more effective to read a file via the operating
    system's mmap facility than it is to via the traditional read() and
    lseek system calls.  To this end, Cyrus provides an operating system
    independent wrapper around the mmap() services (or lack thereof) of the
    operating system.

  - Cyrus currently only supports read-only memory maps, all writes back
    to a file need to be done via the more traditional facilities.  This is
    to enable very low-performance support for operating systems which do not
    provide an mmap() facility via a fake userspace mmap.

  - To create a map, simply call map_refresh on the map (details are in
    lib/map.h).  To free it, call map_free on the same map.

  - Despite the fact that the maps are read-only, it is often useful to open
    the file descriptors O_RDWR, especially if the file decriptors could
    possibly be used for writing elsewhere in the code. Some operating
    systems REQUIRE file descriptors that are mmap()ed to be opened
    O_RDWR, so just do it.

- Network Functions
  - Cyrus abstracts socket stream access to a concept we refer to as
    "prot streams"  Prot Streams take care of all of the necessary 
    SASL and TLS/SSL encrpytion that may need to happen before data
    goes out/comes in from the network.  The API is documented in
    lib/prot.h

- (todo) Authorization Modules

Some general hints that all made it into my 11/15 16:47 commit that I
think may be generally useful to people hacking on the cyrus source:

- Command line apps should link cli_fatal.o so they all fatal()
in the same way, unless there is a really good reason they need to do
something unique.
- If you call config_init() you must call cyrus_done() before you exit.
- No one should ever call DB->init() or DB->done() cyrusdb functions
except for in libcyrus_init()
- I've been trying to keep #include statements for libcyrus and libimap
alphabetical, and below any system includes, but this is merely my personal
style
- Don't exit at the bottom of main with exit(x) use return instead.
- For all the command line utilities that need to be sure that they are
running as cyrus, it should be the first thing they do, and they should
exit with an appropriate fatal() call
- All services should have a shut_down call.  It should be the ONLY way of
exiting the application.  fatal() should always make an attempt to call
shut_down() if it can (though it should have a recursive fatal() trap just
in case).  Similarly, commandline utilities probably don't need a shut_down().