libuv / libuv/libuv

Document the encoding of paths in filesystem functions

Open
#771 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

doc
Dominant language
C
Stars
27.2k
Forks
3.9k
Avg merge
2d 16h
Merged PRs (30d)
17

Description

Currently, the documentation doesn't state anything about the contents of the const char * parameters. This can lead to confusion and two possible interpretations:

  1. It's the filename exactly as stored in the filesystem. True on Linux and OS X, false on Windows.
  2. It's UTF-8. True on Windows, partially true on OS X, true under normal circumstances on Linux (but could be false if a file is intentionally created with a non-UTF-8 name).

Since the purpose of libuv is to allow writing portable cross-platform code, it should discourage writing non-portable code, which is what the first interpretation could lead to. Therefore, I propose that libuv document the following:

  • The filesystem is assumed to be UTF-8 on Linux and OS X and UTF-16 on Windows.
  • Filenames passed and received are encoded in UTF-8, unless the above precondition is violated, in which case the encoding is not guaranteed.

See nodejs/node#5616 for an example of applying the first interpretation and potentially adding more ways of writing non-portable code to Node.js core.

Contributor guide

Open the contributing guide

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 with the linked libuv filesystem documentation and locate the descriptions of functions that accept or return const char * path parameters. Update the documentation to state the platform assumptions and UTF-8 encoding behavior proposed in the issue, including the caveat for non-UTF-8 filesystems.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
documentation, operating-systems
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.