Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

locale_fallback (3C)

Name

locale_fallback - list of locale name fallback locales

Synopsis

#include <locale.h>

char** locale_fallback(const char *locale,
                           int (*check)(const char *loc,
                                        const char *lang,
                                        const char *terr,
                                        const char *cset,
                                        const char *mod,
                                        int type,
                                        void *data),
                                        void* data);

Description

The locale_fallback() function returns list of possible fallback locales based on the *locale* locale name. If *locale* is NULL, current locale of the program is used.

The *check* argument is the name of the validation function, which is called with arguments that describe a possible fallback locale name. If the function returns 0, the name is not included in return list. If the function returns -1, the locale_fallback() function finishes immediately and returns NULL. If *check* is NULL, then all possible fallback locales are in the return list.

The *data* is passed to the check() function.

If the value of *type* is LCF_CANNONICAL_LOCALE, it means the locale name is a canonical locale.

If the value of *type* is LCF_ALIAS_LOCALE, it means the locale name is a locale alias.

If the value of *type* is LCF_OBSOLETE_LOCALE, it means the locale name is an obsolete locale name.

Return Values

Upon successful completion, the locale_fallback() function returns NULL terminated list of possible fallback locales. The list contains unique values in descending order by priority, which explains that, the first item is the most similar fallback locale. It returns NULL and sets errno to indicate the error, or the check() function is provided and the function returns -1 on some locale.

The list items and the list itself needs to be deallocated by using the free() function.

Errors

The locale_fallback() function will fail if:

ENOMEM

Cannot allocate memory

Examples

Example 1 Print program's current locale, fallback locales
char **list = locale_fallback(NULL, NULL, NULL);
if (list != NULL) {
        int i;

        for (i = 0; list[i] != NULL; i++) {
                printf("Fallback locale: %s\n", list[i]);
                free(list[i]);
        }
        free(list);
}

Or, the same with check function

int printit(const char *loc, const char *lang, const char *terr,
    const char *cset, const char *mod, int type, void *data)
{
    printf("Fallback locale: %s\n", loc);
    return (0);
}

...
char **empty_list;

empty_list = locale_fallback(NULL, printit, NULL);

/* assert(empty_list[0] == NULL); */

free(empty_list);
Example 2 Get territory of program's current locale
int get_terr(const char *loc, const char *lang, const char *terr,
    const char *cset, const char *mod, int type, void *data)
{
    if (type == 1 && (*data = strdup(terr)) == NULL)
        return -1;
    return (0);
}

...

char **empty_list;
char *terr = NULL;

empty_list = locale_fallback(NULL, get_terr, &terr);
if (empty_list != NULL and terr != NULL)
        printf("Current territory is %s\n", terr);
free(terr);
free(empty_list);
Example 3 Get list of fallback locales of message object 'myprg.mo' with current gettext fallback rules
int checkfn(const char *loc, const char *lang, const char *terr, const char *cset, const char *mod, int type, void *data)
    {
        char *fn;
        struct stat st;
        int ret;

        /*
         * locale fallback in gettext only tries to use
         * language_territory
         * language
         * LANGUAGE_TERRITORY
         * LANGUAGE
         */
        if (cset != NULL || mod != NULL || type == 3)
           return 0;

        /* check if file /usr/share/locale/%s/LC_MESSAGES/myprg.mo exists */
        if (asprintf(&fn, data, loc) < 0)
                return -1;
        ret = stat(fn, &st);
        free(fn);

        return ret == 0 ? 1 : 0;
    }

...

char **list;
int i;

/* get the list of locale fallbacks */
list = locale_fallback(NULL, checkfn, "/usr/share/locale/%s/LC_MESSAGES/myprg.mo");

if (list != NULL) {

    ... process list ...

    /* deallocate the list */
    for (i = 0; list[i]; i++)
        free(list[i]);
    free(list);
}

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
CSI
Enabled
Interface Stability
Uncommitted
MT-Level
MT-Safe