localelist

, localelistfree

- query installed locales

Synopsis

#include <locale.h>

int localelist(lclist_t **list, int flag);

void localelistfree(lclist_t *list);

Description

The localelist() function checks on the current system and returns a list of installed locales by allocating a memory for the list and data field of lclist_t type components as needed.

The localelist() function is always guaranteed to return at least the “C” locale in the list, unless there is an error.

When there is no memory that can be allocated, the localelist() function deallocates any memory blocks so far allocated in the list and instead sets NULL to the corresponding addresses, as needed, before returning -1 and setting errno to ENOMEM.

The data field of lclist_t type is like the following:

char *locale

Locale name as a string that can be used to set LANG environment variable.

The following values can be bitwise-inclusive-OR combined and requested to the function via flag argument:

LCLIST_QUERY

Check on the current system and return the list of installed locales.

By default, “C” and “POSIX” are always included in the list.

The list returned will be in ascending order based on 7-bit ASCII character codes of the locale name.

LCLIST_VALIDATE

Normally, when a locale is found from file system hierarchy, by default, it is not validated and added to the list of installed locales.

If this flag value is specified, however, the function actually validates the locale to find out if the locale is actually usable or not and add to the list only if it is actually usable. (This prevents any possible bogus locales being added to the list.)

LCLIST_KEEP

When LCLIST_VALIDATE is used, after a locale is validated, the locale loaded into system memory is marked to be unloaded from the memory. However, if this flag value is specified, the function does not do that so that the locale can be reused later.

When you're calling localelist() multiple times with LCLIST_VALIDATE and if you have enough memory space, using this flag may yield a better performance in the subsequent calls to the function.

When LCLIST_VALIDATE is not specified, this flag is ignored.

LCLIST_DO_NOT_DLCLOSE

By default, after a locale is validated, the function unloads the locale. If this flag value is specified, however, the function does not unload the locale.

This will yield a better performance if you have enough free memory space and frequently reuse locales in your running program.

LCLIST_DO_NOT_INCLUDE_POSIX

If this flag is set, “POSIX” locale is not included in the list.

LCLIST_EXCLUDE_SYMBOLIC_LINKS

Occasionally, locales are presented by using a symbolic link to other locales as an alias. When this flag value is specified, such locales are excluded from the list.

LCLIST_INCLUDE_LC_MESSAGES

If this flag is set, the function also includes locales in the list that do not have complete locale database components but have an LC_MESSAGES directory in the locale database directory hierarchy. In this case, setlocale(3C) with LC_MESSAGES can be successful.

The localelistfree() deallocates any allocated and associated memory blocks with the list by the localelist() function.

Return Values

Upon successful completion, the localelist() function returns the number of locales in the list. Otherwise, the localelist() returns -1 and sets an errno to indicate the error. The localelistfree() neither returns a specific value nor sets an errno.

Errors

The localelist() function will fail if:

ENOMEM

Cannot allocate memory.

Examples

Example 1 Query and print installed locales.

#include <locale.h>

        :
lclist_t *lclp;
int count;
int i;
        :

count = localelist(&lclp, LCLIST_QUERY);

if (count > 0) {
        for (i = 0; i < count; i++)
                printf("Locale name = %s\n", lclp[i].locale);
}

localelistfree(lclp);

Example 2 Query and print installed locales including locales that do not have locale shared object but LC_MESSAGES directory.

#include <locale.h>

        :
lclist_t *lclp;
int count;
int i;
        :

count = localelist(&lclp, LCLIST_QUERY | LCLIST_INCLUDE_LC_MESSAGES);

if (count > 0) {
        for (i = 0; i < count; i++)
                printf("Locale name = %s\n", lclp[i].locale);
}

localelistfree(lclp);

Example 3 Query and print installed locales but exclude any locales that are symbolic links to other locales.

#include <locale.h>

        :
lclist_t *lclp;
int count;
int i;
        :

count = localelist(&lclp, LCLIST_QUERY | LCLIST_EXCLUDE_SYMBOLIC_LINKS);

if (count > 0) {
        for (i = 0; i < count; i++)
                printf("Locale name = %s\n", lclp[i].locale);
}

localelistfree(lclp);

Example 4 Query and print installed locales with locale validations.

#include <locale.h>

        :
lclist_t *lclp;
int count;
int i;
        :

count = localelist(&lclp, LCLIST_QUERY | LCLIST_VALIDATE);

if (count > 0) {
        for (i = 0; i < count; i++)

}

localelistfree(lclp);

Files

/usr/lib/locale/locale

locale database directory for locale

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

locale(1), setlocale(3C), attributes(5), environ(5), locale(5), standards(5)