r201857 - Moving the documentation for the format attribute into AttrDocs.
Aaron Ballman
aaron at aaronballman.com
Fri Feb 21 06:36:14 PST 2014
Author: aaronballman
Date: Fri Feb 21 08:36:13 2014
New Revision: 201857
URL: http://llvm.org/viewvc/llvm-project?rev=201857&view=rev
Log:
Moving the documentation for the format attribute into AttrDocs.
Modified:
cfe/trunk/docs/AttributeReference.rst
cfe/trunk/docs/LanguageExtensions.rst
cfe/trunk/include/clang/Basic/Attr.td
cfe/trunk/include/clang/Basic/AttrDocs.td
Modified: cfe/trunk/docs/AttributeReference.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/AttributeReference.rst?rev=201857&r1=201856&r2=201857&view=diff
==============================================================================
--- cfe/trunk/docs/AttributeReference.rst (original)
+++ cfe/trunk/docs/AttributeReference.rst Fri Feb 21 08:36:13 2014
@@ -291,6 +291,71 @@ not ODR-equivalent.
Query for this feature with ``__has_attribute(enable_if)``.
+format (gnu::format)
+--------------------
+.. csv-table:: Supported Syntaxes
+ :header: "GNU", "C++11", "__declspec", "Keyword"
+
+ "X","X","",""
+
+Clang supports the ``format`` attribute, which indicates that the function
+accepts a ``printf`` or ``scanf``-like format string and corresponding
+arguments or a ``va_list`` that contains these arguments.
+
+Please see `GCC documentation about format attribute
+<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
+about attribute syntax.
+
+Clang implements two kinds of checks with this attribute.
+
+#. Clang checks that the function with the ``format`` attribute is called with
+ a format string that uses format specifiers that are allowed, and that
+ arguments match the format string. This is the ``-Wformat`` warning, it is
+ on by default.
+
+#. Clang checks that the format string argument is a literal string. This is
+ the ``-Wformat-nonliteral`` warning, it is off by default.
+
+ Clang implements this mostly the same way as GCC, but there is a difference
+ for functions that accept a ``va_list`` argument (for example, ``vprintf``).
+ GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
+ fuctions. Clang does not warn if the format string comes from a function
+ parameter, where the function is annotated with a compatible attribute,
+ otherwise it warns. For example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__scanf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning: format string is not a string literal
+ }
+
+ In this case we warn because ``s`` contains a format string for a
+ ``scanf``-like function, but it is passed to a ``printf``-like function.
+
+ If the attribute is removed, clang still warns, because the format string is
+ not a string literal.
+
+ Another example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__printf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning
+ }
+
+ In this case Clang does not warn because the format string ``s`` and
+ the corresponding arguments are annotated. If the arguments are
+ incorrect, the caller of ``foo`` will receive a warning.
+
+
no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)
-----------------------------------------------------------------------------------------------------------
.. csv-table:: Supported Syntaxes
Modified: cfe/trunk/docs/LanguageExtensions.rst
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LanguageExtensions.rst?rev=201857&r1=201856&r2=201857&view=diff
==============================================================================
--- cfe/trunk/docs/LanguageExtensions.rst (original)
+++ cfe/trunk/docs/LanguageExtensions.rst Fri Feb 21 08:36:13 2014
@@ -1647,63 +1647,3 @@ with :doc:`ThreadSanitizer`.
Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
with :doc:`MemorySanitizer`.
-
-Format String Checking
-======================
-
-Clang supports the ``format`` attribute, which indicates that the function
-accepts a ``printf`` or ``scanf``-like format string and corresponding
-arguments or a ``va_list`` that contains these arguments.
-
-Please see `GCC documentation about format attribute
-<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
-about attribute syntax.
-
-Clang implements two kinds of checks with this attribute.
-
-#. Clang checks that the function with the ``format`` attribute is called with
- a format string that uses format specifiers that are allowed, and that
- arguments match the format string. This is the ``-Wformat`` warning, it is
- on by default.
-
-#. Clang checks that the format string argument is a literal string. This is
- the ``-Wformat-nonliteral`` warning, it is off by default.
-
- Clang implements this mostly the same way as GCC, but there is a difference
- for functions that accept a ``va_list`` argument (for example, ``vprintf``).
- GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
- fuctions. Clang does not warn if the format string comes from a function
- parameter, where the function is annotated with a compatible attribute,
- otherwise it warns. For example:
-
- .. code-block:: c
-
- __attribute__((__format__ (__scanf__, 1, 3)))
- void foo(const char* s, char *buf, ...) {
- va_list ap;
- va_start(ap, buf);
-
- vprintf(s, ap); // warning: format string is not a string literal
- }
-
- In this case we warn because ``s`` contains a format string for a
- ``scanf``-like function, but it is passed to a ``printf``-like function.
-
- If the attribute is removed, clang still warns, because the format string is
- not a string literal.
-
- Another example:
-
- .. code-block:: c
-
- __attribute__((__format__ (__printf__, 1, 3)))
- void foo(const char* s, char *buf, ...) {
- va_list ap;
- va_start(ap, buf);
-
- vprintf(s, ap); // warning
- }
-
- In this case Clang does not warn because the format string ``s`` and
- the corresponding arguments are annotated. If the arguments are
- incorrect, the caller of ``foo`` will receive a warning.
Modified: cfe/trunk/include/clang/Basic/Attr.td
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/Attr.td?rev=201857&r1=201856&r2=201857&view=diff
==============================================================================
--- cfe/trunk/include/clang/Basic/Attr.td (original)
+++ cfe/trunk/include/clang/Basic/Attr.td Fri Feb 21 08:36:13 2014
@@ -672,7 +672,7 @@ def Format : InheritableAttr {
IntArgument<"FirstArg">];
let Subjects = SubjectList<[ObjCMethod, Block, HasFunctionProto], WarnDiag,
"ExpectedFunction">;
- let Documentation = [Undocumented];
+ let Documentation = [FormatDocs];
}
def FormatArg : InheritableAttr {
Modified: cfe/trunk/include/clang/Basic/AttrDocs.td
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/AttrDocs.td?rev=201857&r1=201856&r2=201857&view=diff
==============================================================================
--- cfe/trunk/include/clang/Basic/AttrDocs.td (original)
+++ cfe/trunk/include/clang/Basic/AttrDocs.td Fri Feb 21 08:36:13 2014
@@ -749,3 +749,66 @@ expression is compared to the type tag.
// is not a null pointer
}];
}
+
+def FormatDocs : Documentation {
+ let Category = DocCatFunction;
+ let Content = [{
+
+Clang supports the ``format`` attribute, which indicates that the function
+accepts a ``printf`` or ``scanf``-like format string and corresponding
+arguments or a ``va_list`` that contains these arguments.
+
+Please see `GCC documentation about format attribute
+<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details
+about attribute syntax.
+
+Clang implements two kinds of checks with this attribute.
+
+#. Clang checks that the function with the ``format`` attribute is called with
+ a format string that uses format specifiers that are allowed, and that
+ arguments match the format string. This is the ``-Wformat`` warning, it is
+ on by default.
+
+#. Clang checks that the format string argument is a literal string. This is
+ the ``-Wformat-nonliteral`` warning, it is off by default.
+
+ Clang implements this mostly the same way as GCC, but there is a difference
+ for functions that accept a ``va_list`` argument (for example, ``vprintf``).
+ GCC does not emit ``-Wformat-nonliteral`` warning for calls to such
+ fuctions. Clang does not warn if the format string comes from a function
+ parameter, where the function is annotated with a compatible attribute,
+ otherwise it warns. For example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__scanf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning: format string is not a string literal
+ }
+
+ In this case we warn because ``s`` contains a format string for a
+ ``scanf``-like function, but it is passed to a ``printf``-like function.
+
+ If the attribute is removed, clang still warns, because the format string is
+ not a string literal.
+
+ Another example:
+
+ .. code-block:: c
+
+ __attribute__((__format__ (__printf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning
+ }
+
+ In this case Clang does not warn because the format string ``s`` and
+ the corresponding arguments are annotated. If the arguments are
+ incorrect, the caller of ``foo`` will receive a warning.
+ }];
+}
\ No newline at end of file
More information about the cfe-commits
mailing list