[PATCH v1] man/man3attr/gnu::aligned.3: Add page

[PATCH v1] man/man3attr/gnu::aligned.3: Add page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@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

[PATCH v2] man/man3attr/gnu::aligned.3: Add page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi!

Here's a second revision, with some slight improvements, plus more
detailed HISTORY, thanks to Aaron's feedback.

(I took "always" as meaning since 1.0 --assuming 1.0 existed and was
 called like that--.)

The formatted page looks like this:

	$ MANWIDTH=64 diffman-git HEAD 2>/dev/null
	--- HEAD^:man/man3attr/gnu::aligned.3
	+++ HEAD:man/man3attr/gnu::aligned.3
	@@ -0,0 +1,48 @@
	+gnu::aligned(3attr)                         gnu::aligned(3attr)
	+
	+NAME
	+       gnu::aligned - set alignment of an object
	+
	+SYNOPSIS
	+       [[gnu::aligned(alignment)]]
	+       [[gnu::aligned]]
	+
	+DESCRIPTION
	+       This attribute can be applied to a type or a variable,
	+       and sets its alignment in bytes.
	+
	+       If the alignment is not specified, the maximum alignment
	+       is used.  This is equivalent to
	+
	+           [[gnu::aligned(alignof(max_align_t))]]
	+
	+VERSIONS
	+       Different dialects provide similar attributes.
	+
	+           __attribute__((aligned(alignment)))  // GNU
	+           __declspec(align(alignment))         // MSVC
	+
	+       There’s also the alignas() type specifier since C23.
	+
	+STANDARDS
	+       GNU.
	+
	+HISTORY
	+       [[gnu::aligned(alignment)]]
	+              gcc X.X, clang 11, clang++ 2.8.0.
	+
	+       __attribute__((aligned(alignment)))
	+              gcc Y.Y, clang 1.0, clang++ 1.0.
	+
	+       __declspec(align(alignment))
	+              clang Z.Z, clang++ A.A.
	+
	+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)

Have a lovely day!
Alex


 man/man3attr/gnu::aligned.3 | 65 +++++++++++++++++++++++++++++++++++++
 1 file changed, 65 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..cfdf254a2
--- /dev/null
+++ b/man/man3attr/gnu::aligned.3
@@ -0,0 +1,65 @@
+.\" 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 an object
+.SH SYNOPSIS
+.nf
+.BI [[gnu::aligned( alignment )]]
+.BI [[gnu::aligned]]
+.fi
+.SH DESCRIPTION
+This attribute can be applied to a type or a variable,
+and sets its
+.I alignment
+in bytes.
+.P
+If the
+.I alignment
+is not specified,
+the maximum alignment is used.
+This is equivalent to
+.P
+.in +4n
+.EX
+[[gnu::aligned(alignof(max_align_t))]]
+.EE
+.in
+.SH VERSIONS
+Different dialects provide similar attributes.
+.P
+.in +4n
+.nf
+.BI __attribute__((aligned( alignment ))) "  \f[R]// GNU\f[]"
+.BI __declspec(align( alignment )) "         \f[R]// MSVC\f[]"
+.fi
+.in
+.P
+There's also the
+.BR alignas ()
+type specifier since C23.
+.SH STANDARDS
+GNU.
+.SH HISTORY
+.TP
+.BI [[gnu::aligned( alignment )]]
+gcc X.X,
+clang 11,
+clang++ 2.8.0.
+.TP
+.BI __attribute__((aligned( alignment )))
+gcc Y.Y,
+clang 1.0,
+clang++ 1.0.
+.TP
+.BI __declspec(align( alignment ))
+clang Z.Z,
+clang++ A.A.
+.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