UNINM_FIND_BLOCKS_DB(3)

NAME
uninm_find_blocks_db, uninm_blocks_db_open, uninm_blocks_db_close, uninm_name, uninm_annotation - retrieve names and annotations of Unicode code points

LIBRARY
libunicodenames

SYNOPSIS
#include <libunicodenames.h>
char *
uninm_find_blocks_db(const char *locale_base);
uninm_blocks_db
uninm_blocks_db_open(const char *filename);
void
uninm_blocks_db_close(uninm_blocks_db handle);
size_t
uninm_num_blocks(uninm_blocks_db handle);
unsigned int
uninm_block_start(uninm_blocks_db handle, int block_number);
unsigned int
uninm_block_end(uninm_blocks_db handle, int block_number);
const char *
uninm_block_name(uninm_blocks_db handle, int block_number);

DESCRIPTION
The uninm_find_blocks_db() function returns the path of the blocks 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.blocks-db and /usr/share/libunicodenames/fr.blocks-db, corresponding to English and French locales, respectively.

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

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

To read the data, given an open blocks database handle, use the uninm_num_blocks(), uninm_block_start(), uninm_block_end(), and uninm_block_name() functions. The uninm_num_blocks() function returns the total number of blocks. In calls to the other functions, the blocks are identified by their number starting from zero. The uninm_block_start() and uninm_block_end() functions return, respectively, the least-valued and greatest-valued code points in the block. The uninm_block_name() function returns the name string of the block; the caller must not try to free the string.

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

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

The uninm_num_blocks() function returns the total number of Unicode blocks. There is no return value to indicate an error.

On success, the uninm_block_start() and uninm_block_end() functions return a Unicode code point. On failure (due to an out of range block number) they return 0xffffffff.

On success, the uninm_block_name() function returns a pointer to a null-terminated string containing the name of the Unicode block; on failure it returns NULL. The caller must not call free(3) with the string.

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

EXAMPLE
The following program prints the start points, end points, and names of the Unicode blocks.

    #include <libunicodenames.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <locale.h>
    int
    main (int argc, char **argv)
    {
      size_t numblocks, i;
      unsigned int start, end;
      char *dbfile;
      uninm_blocks_db db;
      const char *name;
      setlocale (LC_ALL, "");
      dbfile = uninm_find_blocks_db (NULL);
      if (dbfile == NULL)
        exit (1);
      db = uninm_blocks_db_open (dbfile);
      free (dbfile);
      if (db == NULL)
        exit (1);
      numblocks = uninm_num_blocks (db);
      for (i = 0; i < numblocks; i++)
        {
          start = uninm_block_start (db, i);
          end = uninm_block_end (db, i);
          name = uninm_block_name (db, i);
          if (name == NULL)
    	exit (2);
          printf ("--\ni: %u\nstart: %d\nend: %d\nblock name: %s\n",
    	      (unsigned int) i, start, end, name);
        }
      uninm_blocks_db_close (db);
    }

SEE ALSO
uninm_find_names_db(3)

AUTHORS
Barry Schwartz

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