BIND_TEXTDOMAIN_CODESET(3) Library Functions Manual BIND_TEXTDOMAIN_CODESET(3)

bindtextdomain bind_textdomain_codeset textdomain — text domain manipulation functions

#include <libintl.h>

char *bindtextdomain(const char *domainname, const char *dirname);
char *bind_textdomain_codeset(const char *domainname,
       const char *codeset);
char *textdomain(const char *domainname);

The textdomain () function shall set or query the name of the current text domain of the calling process. The application shall ensure that the domainname argument is either a null pointer (when querying), an empty string, or a string that, when used by the gettext family of functions to construct a pathname to a messages object, results in a valid pathname. For portable applications, it should only contain characters from the portable filename character set.

The text domain setting made by the last successful call to textdomain () shall remain in effect across subsequent calls to setlocale(3), uselocale(3), and the gettext family of functions.

Applications should not use text domains whose names begin with the strings "SYS_" or "libc". These prefixes are reserved for implementation use.

The current setting of the text domain can be queried without affecting the current state of the domain by calling textdomain () with domainname set to a null pointer. Calling textdomain () with a domainname argument of an empty string shall set the text domain to the default domain, "messages".

The bindtextdomain () function shall set or query the binding of a text domain to a dirname that is used by the gettext family of functions to construct a pathname to a messages object in the text domain:

  • If domainname is a null pointer or an empty string, bindtextdomain () shall make no changes and return a null pointer without changing errno.
  • Otherwise, if dirname is a non-empty string:
    • If domainname is not already bound, bindtextdomain () shall bind the text domain specified by domainname to the pathname pointed to by dirname and return the bound directory pathname on success or a null pointer on failure.
    • If domainname is already bound, bindtextdomain () shall replace the existing binding with the pathname pointed to by dirname and return the bound directory pathname on success or a null pointer on failure. On failure, the existing binding shall remain unchanged.

    It is unspecified whether the bindtextdomain () function performs pathname resolution on dirname, or whether that is done by the gettext family of functions.

  • Otherwise, if dirname is a null pointer:
    • If domainname is bound, the function shall return the bound directory pathname.
    • If domainname is not bound, the function shall return the implementation-defined default directory pathname used by the gettext family of functions.
  • Otherwise, dirname is an empty string and the behavior is unspecified.

If a text domain is bound to a relative pathname and the current working directory is changed after the binding is established, the pathnames used by the gettext family of functions to locate messages objects for that text domain are unspecified.

The bind_textdomain_codeset () function shall set or query the binding of a text domain to the output codeset used by the gettext family of functions for message strings retrieved from messages objects for the text domain specified by domainname:

  • If domainname is a null pointer or an empty string, bind_textdomain_codeset () shall make no changes and return a null pointer without changing errno.
  • Otherwise, if codeset is a non-empty string:
    • If domainname is not already bound, bind_textdomain_codeset () shall bind the text domain specified by domainname to the codeset pointed to by codeset and return the newly bound codeset on success or a null pointer on failure.
    • If domainname is already bound, bind_textdomain_codeset () shall replace the existing binding with the codeset pointed to by codeset and return the newly bound codeset on success or a null pointer on failure. On failure, the existing binding shall remain unchanged.

    The application shall ensure that the codeset argument, if non-empty, is a valid codeset name that can be used as the argument of the iconv_open(3) function, and that in the codeset it specifies, the <NUL> character corresponds to a single null byte.

  • Otherwise, if codeset is a null pointer:
    • If domainname is bound, the function shall return the bound codeset.
    • If domainname is not bound, the function shall return the implementation-defined default codeset used by the gettext family of functions.
  • Otherwise, codeset is an empty string and the behavior is unspecified.

If codeset is a null pointer and domainname is a non-empty string, bind_textdomain_codeset () shall return the current codeset for the named domain, or a null pointer if a codeset has not yet been set. The bind_textdomain_codeset () function can be called multiple times. If successfully called multiple times with the same domainname argument, the last such call shall override the setting made by the previous such call.

The return value from a successful textdomain () call shall be a pointer to a string containing the current setting of the text domain. If domainname is a null pointer, textdomain () shall return a pointer to the string containing the current text domain. If textdomain () was not previously called and domainname is a null string, the name of the default text domain shall be returned. The name of the default text domain shall be the string "messages". If textdomain () fails, a null pointer shall be returned and errno shall be set to indicate the error.

For bindtextdomain () return values see the DESCRIPTION. When bindtextdomain () is called with a non-empty domainname and returns a null pointer, it shall set errno to indicate the error. When bindtextdomain () returns a pathname for a bound text domain, the return value shall be a pointer to a copy of the dirname string passed to the bindtextdomain () call that created the binding. The returned string shall remain valid until the next successful call to bindtextdomain () with a non-empty dirname and same domainname. The application shall ensure that it does not modify the returned string.

A call to the bind_textdomain_codeset () function with a non-empty domainname argument shall return one of the following:

  • The currently bound codeset name for that text domain if codeset is a null pointer
  • The newly bound codeset if codeset is non-empty
  • A null pointer without changing errno if no codeset has yet been bound for that text domain

The application shall ensure that it does not modify the returned string. A subsequent call to bind_textdomain_codeset () with a non-empty domainname argument might invalidate the returned pointer or overwrite the string content. The returned pointer might also be invalidated if the calling thread is terminated. If bind_textdomain_codeset () fails, a null pointer shall be returned and errno shall be set to indicate the error.

For the conditions under which bindtextdomain ()—if it performs pathname resolution—fails and may fail, refer to open(3).

In addition, the textdomain (), bindtextdomain (), and bind_textdomain_codeset () functions may fail if:

Insufficient memory available.

See the examples for gettext(3).

A text domainname is limited to {TEXTDOMAIN_MAX} bytes.

Application developers are responsible for ensuring that the text domain used is not used by other applications. To minimize the chances of collision, developers can prefix text domains with their company or application name (or both) and an underscore. For example, if your application name was "foo" and you wanted to use the text domain "errors", you could instead use the text domain "foo_errors". Note that if an application can be installed with a configurable name, a text domain prefix based on the application name should change with the application name.

Specifying a relative pathname to the bindtextdomain () function should be avoided, since it may result in messages objects being searched for in a directory relative to the current working directory of the calling process; if the process calls the chdir(3) function, the directory searched for may also be changed.

Since pathname resolution of dirname might not be performed by bindtextdomain (), but could be performed later by the gettext family of functions, and since the latter have no way to report an error, applications should verify, using for example stat(3), that the directory is accessible if this is desired.

Although the return type of these functions ought to be , it is to match historical practice.

Pathname resolution of the dirname argument passed to bindtextdomain () may be performed by bindtextdomain () itself or by the gettext family of functions. If pathname resolution fails in one of the gettext family of functions, it is neither allowed to modify errno nor to return an error, but if pathname resolution fails in bindtextdomain (), it is required to report an error and set errno just like open(3) does.

Historically, bindtextdomain () did not perform pathname resolution. However, the standard developers decided to allow this as an option so that future implementations can, if desired, open a file descriptor for that directory in bindtextdomain () and then use that file descriptor with openat(3) in the gettext family of functions.

The dirname parameter to bindtextdomain () may need to be copied to avoid the possibility of the application releasing the memory used by the argument while the gettext family of functions may still need to reference it.

When bindtextdomain () is called with a non-empty domainname and an empty dirname, historical implementations of the gettext family of functions use the empty string for the dirname part of the messages object pathname, resulting in an absolute pathname of the form / / / . The standard developers did not believe this behavior to be useful. Using the empty dirname case as a way to remove an existing binding seemed to be a more useful behavior, and would be consistent with the behavior of textdomain (). However, because no historical implementations behave this way, the behavior is left unspecified.

Some implementations set errno to [EAGAIN] to signal memory allocation failures that might succeed if retried and [ENOMEM] for failures that are unlikely to ever succeed, for example due to configured limits. V2_chap02(3) permits this behavior; when multiple error conditions are simultaneously true there is no precedence between them.

A future version of this standard may require implementations to prefix implementation-provided text domains with either "SYS_" or a prefix related to the implementor's company name to avoid namespace collisions.

A future version of this standard may require bindtextdomain () to remove any binding for domainname when called with a non-empty domainname and an empty dirname.

gettext(3), iconv_open(3), setlocale(3), uselocale(3)

XBD <libintl.h>, <limits.h>

XCU msgfmt(1), xgettext(1)

First released in Issue 8.

June 14, 2024 posix.fail