Document the encoding of paths in filesystem functions
Nobody has claimed this yet.
- 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:
- It's the filename exactly as stored in the filesystem. True on Linux and OS X, false on Windows.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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