UNINM_FIND_NAMES_DB(3)

NAME
uninm_find_names_db, uninm_names_db_open, uninm_names_db_close, uninm_name, uninm_annotation - retrieve names and annotations of Unicode code points

LIBRARY
libunicodenames

SYNOPSIS
#include <libunicodenames.h>
char *
uninm_find_names_db(const char *locale_base);
uninm_names_db
uninm_names_db_open(const char *filename);
void
uninm_names_db_close(uninm_names_db handle);
const char *
uninm_name(uninm_names_db handle, unsigned int codepoint);
const char *
uninm_annotation(uninm_names_db handle, unsigned int codepoint);

DESCRIPTION
The uninm_find_names_db() function returns the path of the names database for the current locale. The caller should call free(3) on the string when done with it. If locale_base is not NULL, then use it as the base directory for MO (compiled gettext) files; otherwise use the compiled-in locale directory. Databases accessible through the compiled-in directory are /usr/share/libunicodenames/en.names-db and /usr/share/libunicodenames/fr.names-db, corresponding to English and French locales, respectively.

The uninm_names_db_open() function open a names database, given its path, returning an opaque pointer to act as a handle.

The uninm_names_db_close() closes a names database, given its handle. Afterwards the value of handle is meaningless.

The uninm_name() and uninm_annotation() functions return, respectively, name and annotation strings associated with a given Unicode code point. The handle parameter must refer to an open names database. The caller must not try to free the returned string.

RETURN VALUES
On success, the uninm_find_names_db() function returns a pointer to a null-terminated string, which eventually should be freed by calling free(3). On failure, uninm_find_names_db() returns NULL.

On success, the uninm_names_db_open() function returns an open handle for a names database. On failure, it returns NULL.

The uninm_name() and uninm_annotation() functions return a pointer to a null-terminated string, if there is a database entry corresponding to the given code point; otherwise they return NULL. The caller must not call free(3) with the string.

FILES
/usr/share/libunicodenames/en.names-db, /usr/share/libunicodenames/fr.names-db

EXAMPLE
The following program prints names and annotations corresponding to the code points between 0 and 999, inclusive.

    #include <libunicodenames.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <locale.h>
    int
    main (int argc, char **argv)
    {
      unsigned int codepoint;
      char *dbfile;
      uninm_names_db db;
      const char *name, *annot;
      setlocale (LC_ALL, "");
      dbfile = uninm_find_names_db (NULL);
      if (dbfile == NULL)
        exit (1);
      db = uninm_names_db_open (dbfile);
      free (dbfile);
      if (db == NULL)
        exit (1);
      for (codepoint = 0; codepoint <= 999; codepoint++)
        {
          name = uninm_name (db, codepoint);
          annot = uninm_annotation (db, codepoint);
          name = (name == NULL) ? "--none--" : name;
          annot = (annot == NULL) ? "--none--" : annot;
          printf ("--\ncode point: %u\nname: %s\nannotation:\n%s\n",
    	      codepoint, name, annot);
        }
      uninm_names_db_close (db);
    }

SEE ALSO
uninm_find_blocks_db(3)

AUTHORS
Barry Schwartz

BUGS
The French translation of the Unicode names list is based on an older Unicode standard.