README

   1 Shishi README -- important introductory notes
   2 See the end for copying conditions.
   3
   4 Libstringprep is an implementation of the IETF stringprep
   5 specification, licensed under the LGPL.
   6
   7 Libstringprep is unstable and in its early steps of development.  You
   8 should expect it to not work as well as having security problems.
   9
  10 Things left to do below.  If you like to start working on anything,
  11 please let me know so work duplication can be avoided.
  12
  13   - Optimize it, the table searching is slow (but does it matter?).
  14   - Port applications to use libstringprep.
  15   - Include tables for more stringprep profiles.
  16   - Add texi documentation.
  17   - Implement rest of IDN?  Possibly separate project.
  18
  19 Currently the API include the following definitions and functions:
  20
  21 Function: int stringprep (char *in, int maxlen, int flags,
  22                           stringprep_profile * profile);
  23
  24      Perform stringprep on a zero terminated UTF-8 string.  Since the
  25      stringprep operation can expand the string, maxlen indicate how
  26      large the buffer holding the string is.  See below for valid
  27      flags options.  The profile indicates processing details, see the
  28      profile header files, such as stringprep_generic.h and
  29      stringprep_nameprep.h for two examples.  Your application can
  30      define new profiles, possibly re-using the generic stringprep
  31      tables that always will be part of the library.  Note that you
  32      must convert strings entered in the systems locale into UTF-8
  33      before using this function.
  34
  35 Macro: int stringprep_nameprep(char *in, int maxlen)
  36 Macro: int stringprep_kerberos5(char *in, int maxlen)
  37
  38      Short-hand macros for applying Nameprep and Kerberos 5
  39      stringprep profiles to strings, respectively.
  40
  41 Type: STRINGPREP_NO_NFKC
  42 Type: STRINGPREP_NO_BIDI
  43
  44      Valid options to the FLAGS parameter of stringprep().
  45      STRINGPREP_NO_NFKC disables the NFKC normalization, as well as
  46      selecting the non-NFKC case folding tables. STRINGPREP_NO_BIDI
  47      disables the BIDI step.  Usually the profile specifies this.
  48
  49 It also contains the following utility functions:
  50
  51 Function: int stringprep_unichar_to_utf8 (long c, char *outbuf);
  52 Function: long stringprep_utf8_to_unichar (const char *p);
  53
  54      Convert between Unicode (UCS4) and UTF-8, one character only.
  55
  56 Function: long *stringprep_utf8_to_ucs4 (const char *str, int  len,
  57                                       int *items_written);
  58 Function: char *stringprep_ucs4_to_utf8 (const long * str, int len,
  59                                       int * items_read, int * items_written);
  60
  61      Convert between Unicode (UCS4) and UTF-8, zero-terminated strings.
  62
  63 Function: char *stringprep_utf8_nfkc_normalize (const char *str, int len);
  64 Function: long *stringprep_ucs4_nfkc_normalize (long *str, int len);
  65
  66      Perform NFKC normalization on strings.
  67
  68 Function: const char *stringprep_locale_charset ();
  69 Function: char *stringprep_convert (const char *str,
  70                                  const char *to_codeset,
  71                                  const char *from_codeset);
  72 Function: char *stringprep_locale_to_utf8 (const char *str);
  73
  74      Convert strings between character sets.
  75
  76 Macro: STRINGPREP_VERSION
  77
  78      CPP definition, a string with version of the stringprep header file.
  79
  80 Function: extern char *stringprep_check_version (char *req_version);
  81
  82      Check that the the version of the library is at minimum the one
  83      given as a string in REQ_VERSION and return the actual version
  84      string of the library; return NULL if the condition is not met.
  85      If `NULL' is passed to this function no check is done and only the
  86      version string is returned.
  87
  88 Libstringprep has at some point in time passed the self tests on the
  89 following systems, but no guarantees.
  90
  91   - alphaev67-dec-osf5.0 (Tru64 UNIX C, Tru64 make -- iconv failed!)
  92   - i686-pc-linux-gnu (Debian Sid, iconv ok)
  93   - i686-pc-linux-gnu (RedHat 7.2, iconv ok)
  94   - mips-sgi-irix6.5 (MIPS C compiler, IRIX make, iconv ok)
  95   - rs6000-ibm-aix4.3.2.0 (GCC 2.9-aix43-000718, GNU make, iconv failed!)
  96   - rs6000-ibm-aix4.3.2.0 (IBM C for AIX compiler, AIX make, iconv failed!)
  97   - sparc-sun-solaris2.6 (Sun WorkShop Compiler C 5.0, non-GNU make)
  98   - sparc-sun-solaris2.8 (Sun WorkShop Compiler C 6.0U2, SUN make, iconv ok)
  99   - sparc-sun-solaris2.8 (GCC 3.1, GNU make, iconv ok)
 100
 101 Before it becomes a FAQ: This library do not link with GLIB for the
 102 UTF-8 functions for two reasons.  First, GLIB does not provide
 103 versioning of the Unicode tables (and the developers said it will not
 104 be added either) and this package must know the Unicode version used.
 105 Secondly, GLIB requires some things (e.g., threads) that would make
 106 this package less portable.
 107
 108 For more information see <URL:http://josefsson.org/libstringprep/>.
 109
 110 Send all bug reports by electronic mail to bug-libstringprep@josefsson.org.
 111
 112 ----------------------------------------------------------------------
 113 Copyright information:
 114
 115 Copyright (C) 2002 Simon Josefsson
 116
 117    Permission is granted to anyone to make or distribute verbatim copies
 118    of this document as received, in any medium, provided that the
 119    copyright notice and this permission notice are preserved,
 120    thus giving the recipient permission to redistribute in turn.
 121
 122    Permission is granted to distribute modified versions
 123    of this document, or of portions of it,
 124    under the above conditions, provided also that they
 125    carry prominent notices stating who last changed them.