How to support a new operating system, platform or version thereof?
-------------------------------------------------------------------

Make sure 'port/guess_env' reliably detects the version of your
new operating system. If you have a new operating system choose
a new label for the platform like 'SUNOS'.

Never port for the future with 'OS_MINOR_VERSION >= 5', make sure
you check the new version first.

We try to follow the X-Open group if possible (and POSIX). Try
to avoid BSD emulations of functions on SysV systems and vice
versa.

Defines in 'port/sys.h'
-----------------------

Don't port using '#ifdef LINUX'! Instead use the platform flags
only in 'port/sys.h' and define descriptive macros for features
of the system like 'HAVE_VSNPRINTF'.
 
Currently there are the following definitions which must be set:
- HAVE_STDBOOL_H and HAVE_ENUM_BOOL:
  HAVE_STDBOOL_H whether the platform has a C99 bool type in stdbool.h
  HAVE_ENUM_BOOL for platforms which define an internal _Bool somewhere
  but not the official bool data type
- HAVE_VSNPRINTF, HAVE_SNPRINTF: vsnprintf and snprintf, there
  is a stub implementation if this function doesn't exist or
  is buggy (see http://www.jhweiss.de/software/snprintf.html)
- HAVE_STRDUP: a string duplication function (there is a stub for
  really old platforms)
- HAVE_STRERROR_R: whether we have a reentrant strerror function
- HAVE_LOCKF: whether we have a POSIX lockf interface. A stub implemented
  with fcntl is available for platform which don't have a lockf function.
- HAVE_STRCASECMP and HAVE_STRNCASECMP: whether we have 7-bit versions
  of str(n)casecmp (it's POSIX and BSD but some C libaries miss it)
- HAVE_STRINGS_H: old header file, usually it is nowadaus a dummy which
  includes <string.h>, but on some systems like Solaris 8 or also Linux
  they declare the prototypes for str(n)casecmp and some other BSDish
  string functions
- HAVE_LOCALTIME_R: whether we have a reentrant localtime function
- HAVE_PTHREADS: whether the system has POSIX thread support
- HAVE_STRLCPY, HAVE_STRLCAT, MUST_DEFINE_STRLCPY_PROTOTYPE and
  MUST_DEFINE_STRLCAT_PROTOTYPE: strlcpy and strlcat are very important
  in term of secure C programming, but _XOPEN_SOURCE doesn't define them.
  As we also don't want to include whatever for example _NETBSD_SOURCE
  defines we define some prototypes on platforms where the function
  exists in the C library. On other platforms like Linux we provide a
  stub
- HAVE_ITOA: handy function, we define it as on Windows (as the char*
  return value is more handy than void)
- HAVE_GETADDRINFO: if we have the GAI library functions getaddrinfo,
  freeaddrinfo and the counterpart getnameinfo, as well as the error
  message function gai_strerror
- HAVE_GAI_STRERROR_R: if we have a thread-safe version of gai_strerror
- HAVE_PTHREADS: whether we have POSIX threads on the platform. This
  also means all kind of special switches for compilers and thread
  libraries are necessary in platform.mk/compiler.mk

Defines in 'port/sys_internal.h'
--------------------------------

Locically exactly the same, but for portibility issues we don't want to
expose to normal user code, e.g. internally used functions which expose
a different interface in libwolf.

Currently tested on:
--------------------

- x86 Linux 2.6.x
- x86 FreeBSD 6.2
- x86 OpenBSD 4.2
- x86 NetBSD 4.0
- x86 Solaris 10
- SPARC Solaris 8
- x86 Cygwin 5.0
- native Windows W32 API, Windows 2000 

How to use the porting layer in your code
-----------------------------------------

Don't include system header files if there is a similar file in the
'port' subdir:

#include "port/limits.h"
#include "port/stdbool.h"
#include "port/stdio.h"
#include "port/string.h"
#include "port/unistd.h"

You also may to have new such stubs when porting to new platforms 
or when you start to use new features.