php / php/doc-en

bind_textdomain_codeset() return value updates

Open
#4,311 9 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug
Dominant language
XML
Stars
596
Forks
890
Avg merge
1d 15h
Merged PRs (30d)
55

Description

bind_textdomain_codeset() is documented to return a string on success, and false on failure. But there is one success case that also returns false. If you query the codeset for a domain that has not been explicitly set (yet), you will also get false:

php > var_dump(bind_textdomain_codeset("foo", NULL));
bool(false)

This is because the C function returns NULL to indicate that the locale's codeset will be used. Quoting from https://pubs.opengroup.org/onlinepubs/9799919799.2024edition/functions/bind_textdomain_codeset.html

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.

I bring this up because musl only supports UTF-8, and always returns NULL from its bind_textdomain_codeset(). Its PHP counterpart therefore always appears to fail, when it is working as... well, not quite expected, but as documented.

To summarize:

  • false will also be returned if no codeset has been explicitly set for the domain
  • this function always returns false under musl libc where the only supported codeset is UTF-8

Edit: as of musl-1.2.6, a NULL is returned only when the requested codeset is not "UTF-8" (https://git.musl-libc.org/cgit/musl/commit/src/locale/bind_textdomain_codeset.c?id=cabbd8697d39c09ca37fb3d63b86b42526b81fda)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the PHP documentation entry for bind_textdomain_codeset() and review its documented return values alongside the POSIX and musl behavior cited in the issue. Update the return-value description to cover the unset-codeset and musl cases, then verify that the documentation accurately distinguishes success from failure.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.