[libc][docs][POSIX] flush out documentation for the POSIX defined headers

[nickdesaulniers]

If you go to https://pubs.opengroup.org/onlinepubs/9799919799/, then 14. Headers in the bottom left, you get a list of headers mandated by POSIX. I'd like to document them from https://libc.llvm.org/headers/index.html. We do so by manually curating some metadata about functions and preprocessor defines in yaml files. The yaml files are currently in https://github.com/llvm/llvm-project/tree/main/libc/utils/docgen. https://github.com/llvm/llvm-project/blob/main/libc/utils/docgen/arpa/inet.yaml is an example of arpa/inet.h as per POSIX. POSIX also tries to be a superset of C (though FWICT POSIX1.2024 missed C23 additions...), so most headers we have entries for already (though we should triple check since POSIX can add functions to existing C standard headers).

Once we've added entries for the new POSIX headers, you should configure your build with the 2 additional cmake flags:

1. -DLLVM_ENABLE_SPHINX=ON
2. -DLIBC_INCLUDE_DOCS=ON

Then you can do ninja docs-libc-html to build html you can view locally in {build_dir}/libc/docs/html/headers/**.html.

Good pull requests should implement one header at a time, and not send a PR that implements documentation for more than one header at a time. If that means that this issue is a "meta" issue for which multiple PRs will link against, so be it.

[llvmbot]

Hi!

This issue may be a good introductory issue for people new to working on LLVM. If you would like to work on this issue, your first steps are:

1. Check that no other contributor has already been assigned to this issue. If you believe that no one is actually working on it despite an assignment, ping the person. After one week without a response, the assignee may be changed.
2. In the comments of this issue, request for it to be assigned to you, or just create a pull request after following the steps below. Mention this issue in the description of the pull request.
3. Fix the issue locally.
4. Run the test suite locally. Remember that the subdirectories under test/ create fine-grained testing targets, so you can e.g. use make check-clang-ast to only run Clang's AST tests.
5. Create a Git commit.
6. Run git clang-format HEAD~1 to format your changes.
7. Open a pull request to the upstream repository on GitHub. Detailed instructions can be found in GitHub's documentation. Mention this issue in the description of the pull request.

If you have any further questions about this issue, don't hesitate to ask via a comment in the thread below.

[llvmbot]

@llvm/issue-subscribers-libc

Author: Nick Desaulniers (nickdesaulniers)

If you go to https://pubs.opengroup.org/onlinepubs/9799919799/, then `14. Headers` in the bottom left, you get a list of headers mandated by POSIX. I'd like to document them from https://libc.llvm.org/headers/index.html. We do so by manually curating some metadata about functions and preprocessor defines in yaml files. The yaml files are currently in https://github.com/llvm/llvm-project/tree/main/libc/utils/docgen. https://github.com/llvm/llvm-project/blob/main/libc/utils/docgen/arpa/inet.yaml is an example of arpa/inet.h as per POSIX. POSIX also tries to be a superset of C (though FWICT POSIX1.2024 missed C23 additions...), so most headers we have entries for already (though we should triple check since POSIX can add functions to existing C standard headers).

Once we've added entries for the new POSIX headers, you should configure your build with the 2 additional cmake flags:

1. -DLLVM_ENABLE_SPHINX=ON
2. -DLIBC_INCLUDE_DOCS=ON

Then you can do ninja docs-libc-html to build html you can view locally in {build_dir}/libc/docs/html/headers/**.html.

Good pull requests should implement one header at a time, and not send a PR that implements documentation for more than one header at a time. If that means that this issue is a "meta" issue for which multiple PRs will link against, so be it.

[llvmbot]

@llvm/issue-subscribers-good-first-issue

Author: Nick Desaulniers (nickdesaulniers)

If you go to https://pubs.opengroup.org/onlinepubs/9799919799/, then `14. Headers` in the bottom left, you get a list of headers mandated by POSIX. I'd like to document them from https://libc.llvm.org/headers/index.html. We do so by manually curating some metadata about functions and preprocessor defines in yaml files. The yaml files are currently in https://github.com/llvm/llvm-project/tree/main/libc/utils/docgen. https://github.com/llvm/llvm-project/blob/main/libc/utils/docgen/arpa/inet.yaml is an example of arpa/inet.h as per POSIX. POSIX also tries to be a superset of C (though FWICT POSIX1.2024 missed C23 additions...), so most headers we have entries for already (though we should triple check since POSIX can add functions to existing C standard headers).

Once we've added entries for the new POSIX headers, you should configure your build with the 2 additional cmake flags:

1. -DLLVM_ENABLE_SPHINX=ON
2. -DLIBC_INCLUDE_DOCS=ON

Then you can do ninja docs-libc-html to build html you can view locally in {build_dir}/libc/docs/html/headers/**.html.

Good pull requests should implement one header at a time, and not send a PR that implements documentation for more than one header at a time. If that means that this issue is a "meta" issue for which multiple PRs will link against, so be it.

[StarOne01]

Looks like a good issue to start with, could I work on this?

[StarOne01]

From my understanding, what i want to do is:

• Check whether all the headers mandated by POSIX can be found in LLVM's reference.
• If a header is missing form LLVM's reference, create a new yaml with the functions and macros of the header from POSIX reference (also create a entry in index.rs in libc/docs/headers).
• Check and update the current status of functions and macros of all headers in POSIX.

Now, i got some questions,

• What's the role of C23 Standard Section in the reference?

[StarOne01]

Please correct me if i misunderstand something, somewhere. Thanks!

[nickdesaulniers]

Looks like a good issue to start with, could I work on this?

Sure! I'll add you as an assignee. Feel free to work through as many as you'd like. Happy to add others to help out if folks are interested, since this is an embarrassingly parallel problem!

Check whether all the headers mandated by POSIX can be found in LLVM's reference.

Yep, each header should have a corresponding .yaml file under libc/utils/docgen/ (or a subdir of that for things like arpa/ sys/ etc).

also create a entry in index.rs in libc/docs/headers

s/index.rs/index.rst/ but yes, good catch! I forgot to mention that in the bug description. Please keep that list alphabetically sorted, too.

What's the role of C23 Standard Section in the reference?

The intent of that field is when a function/macro has a definition as per the ISO C spec, what section should folks look at to understand what that function's specified semantics are.

If a function is POSIX only, and not in ISO C, then the c23 standard section is optional, and may be omitted.

[StarOne01]

Hey @nickdesaulniers , i just made a pull request for including (aio.h) and do i have to create a separate PR for every header ?

[marcury122]

Hi @nickdesaulniers, I would also like to work on this issue and help contribute, It would be great If you could assign me also on this, @StarOne01 Would like to work together as there are many headers to be listed. Thanks!

[StarOne01]

Hey @marcury122 , let's work on this in parallel, please tell me which header(s) you gonna work on