Signed-off-by: Alejandro Colomar <a...@kernel.org>
---
Hi all,
Aaron and I talked recently about improving some missing Clang
documentation. Attributes are significantly misdocumented in Clang, and
instead (or complementary to) improving the documentation of attributes
within Clang's internal documentation, I had the idea of providing
manual pages for the attributes, under a new man3attr section of the
manual.
Here's a first draft, documenting one attribute. At the bottom is the
manual page patch. Here's how it looks formatted:
$ MANWIDTH=64 diffman-git HEAD 2>/dev/null
--- HEAD^:man/man3attr/gnu::aligned.3
+++ HEAD:man/man3attr/gnu::aligned.3
@@ -0,0 +1,35 @@
+gnu::aligned(3attr) gnu::aligned(3attr)
+
+NAME
+ gnu::aligned - set alignment of object
+
+SYNOPSIS
+ [[gnu::aligned(n)]]
+
+DESCRIPTION
+ This attribute can be applied to a type or a variable,
+ and sets its alignment as n bytes.
+
+VERSIONS
+ Different dialects provide similar attributes.
+
+ __attribute__((aligned(n))) // GNU
+ __declspec(align(n)) // MSVC
+
+ There’s also the alignas type specifier since C23.
+
+STANDARDS
+ GNU C23.
+
+HISTORY
+ GNU C23.
+
+CAVEATS
+ This attribute can increase the natural alignment of a
+ type, but it can’t decrease it.
+
+ The linker may limit the maximum alignment that can be
+ applied.
+
+EXAMPLES
+Linux man‐pages (unreleased) (date) gnu::aligned(3attr)
I have a few questions about this attribute:
- In which Clang (or LLVM, I never know which name is appropriate)
version was it introduced? This is useful for the HISTORY section.
For this, it is interesting to know both the version for the old GNU
syntax and the C23 syntax.
- In which GCC version was it introduced?
- If the linker doesn't support an alignment, is it silently ignored or
coerced? Can we specify some rules which can be relied upon?
- Is there any further rule? Can I specify alignment as 7? I suspect
not.
- 'n' can be omitted. Is is exactly equivalent to
[[gnu::aligned(alignof(max_align_t))]]? Or may it be different in
some cases?
- Are the semantics exactly the same as alignas()? Or are there any
differences? (Other than that alignas not being allowed on types.)
Have a lovely day!
Alex
man/man3attr/gnu::aligned.3 | 39 +++++++++++++++++++++++++++++++++++++
1 file changed, 39 insertions(+)
create mode 100644 man/man3attr/gnu::aligned.3
diff --git a/man/man3attr/gnu::aligned.3 b/man/man3attr/gnu::aligned.3
new file mode 100644
index 000000000..792301c68
--- /dev/null
+++ b/man/man3attr/gnu::aligned.3
@@ -0,0 +1,39 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH gnu::aligned 3attr (date) "Linux man-pages (unreleased)"
+.SH NAME
+gnu::aligned \- set alignment of object
+.SH SYNOPSIS
+.nf
+.BI [[gnu::aligned( n )]]
+.fi
+.SH DESCRIPTION
+This attribute can be applied to a type or a variable,
+and sets its alignment as
+.I n
+bytes.
+.SH VERSIONS
+Different dialects provide similar attributes.
+.P
+.in +4n
+.nf
+.BI __attribute__((aligned( n ))) " \f[R]// GNU\f[]"
+.BI __declspec(align( n )) " \f[R]// MSVC\f[]"
+.fi
+.in
+.P
+There's also the
+.I alignas
+type specifier since C23.
+.SH STANDARDS
+GNU C23.
+.SH HISTORY
+GNU C23.
+.SH CAVEATS
+This attribute can increase the natural alignment of a type,
+but it can't decrease it.
+.P
+The linker may limit the maximum alignment that can be applied.
+.SH EXAMPLES
base-commit: 4044e31a053f6c370b2188deba583797018f04a2
prerequisite-patch-id: 9baedc3d2399d2f8d54d96511dac415f0d0ff04f
--
2.49.0
