diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/AddressSanitizer.rst | 146 | ||||
| -rw-r--r-- | docs/AttributeReference.rst | 1115 | ||||
| -rw-r--r-- | docs/CMakeLists.txt | 3 | ||||
| -rw-r--r-- | docs/ClangFormatStyleOptions.rst | 19 | ||||
| -rw-r--r-- | docs/CommandGuide/clang.rst | 484 | ||||
| -rw-r--r-- | docs/CommandGuide/index.rst | 17 | ||||
| -rw-r--r-- | docs/DriverInternals.rst | 6 | ||||
| -rw-r--r-- | docs/LeakSanitizer.rst | 3 | ||||
| -rw-r--r-- | docs/LibASTMatchersReference.html | 10 | ||||
| -rw-r--r-- | docs/Makefile | 1 | ||||
| -rw-r--r-- | docs/ObjectiveCLiterals.rst | 62 | ||||
| -rw-r--r-- | docs/SafeStack.rst | 120 | ||||
| -rw-r--r-- | docs/conf.py | 40 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/tools/Makefile | 116 | ||||
| -rw-r--r-- | docs/tools/clang.pod | 614 | ||||
| -rw-r--r-- | docs/tools/manpage.css | 256 |
17 files changed, 807 insertions, 2206 deletions
diff --git a/docs/AddressSanitizer.rst b/docs/AddressSanitizer.rst index 6175433..66ed344 100644 --- a/docs/AddressSanitizer.rst +++ b/docs/AddressSanitizer.rst @@ -60,7 +60,28 @@ or: % clang -g -fsanitize=address example_UseAfterFree.o If a bug is detected, the program will print an error message to stderr and -exit with a non-zero exit code. To make AddressSanitizer symbolize its output +exit with a non-zero exit code. AddressSanitizer exits on the first detected error. +This is by design: + +* This approach allows AddressSanitizer to produce faster and smaller generated code + (both by ~5%). +* Fixing bugs becomes unavoidable. AddressSanitizer does not produce + false alarms. Once a memory corruption occurs, the program is in an inconsistent + state, which could lead to confusing results and potentially misleading + subsequent reports. + +If your process is sandboxed and you are running on OS X 10.10 or earlier, you +will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to +the ASan library that is packaged with the compiler used to build the +executable. (You can find the library by searching for dynamic libraries with +``asan`` in their name.) If the environment variable is not set, the process will +try to re-exec. Also keep in mind that when moving the executable to another machine, +the ASan library will also need to be copied over. + +Symbolizing the Reports +========================= + +To make AddressSanitizer symbolize its output you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your ``$PATH``): @@ -100,14 +121,63 @@ force disabled by setting ``ASAN_OPTIONS=symbolize=0``): Note that on OS X you may need to run ``dsymutil`` on your binary to have the file\:line info in the AddressSanitizer reports. -AddressSanitizer exits on the first detected error. This is by design. -One reason: it makes the generated code smaller and faster (both by -~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind, -it is often the case that users treat Valgrind warnings as false -positives (which they are not) and don't fix them. +Additional Checks +================= -``__has_feature(address_sanitizer)`` ------------------------------------- +Initialization order checking +----------------------------- + +AddressSanitizer can optionally detect dynamic initialization order problems, +when initialization of globals defined in one translation unit uses +globals defined in another translation unit. To enable this check at runtime, +you should set environment variable +``ASAN_OPTIONS=check_initialization_order=1``. + +Note that this option is not supported on OS X. + +Memory leak detection +--------------------- + +For more information on leak detector in AddressSanitizer, see +:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux; +however, it is not yet supported on other platforms. + +Issue Suppression +================= + +AddressSanitizer is not expected to produce false positives. If you see one, +look again; most likely it is a true positive! + +Suppressing Reports in External Libraries +----------------------------------------- +Runtime interposition allows AddressSanitizer to find bugs in code that is +not being recompiled. If you run into an issue in external libraries, we +recommend immediately reporting it to the library maintainer so that it +gets addressed. However, you can use the following suppression mechanism +to unblock yourself and continue on with the testing. This suppression +mechanism should only be used for suppressing issues in external code; it +does not work on code recompiled with AddressSanitizer. To suppress errors +in external libraries, set the ``ASAN_OPTIONS`` environment variable to point +to a suppression file. You can either specify the full path to the file or the +path of the file relative to the location of your executable. + +.. code-block:: bash + + ASAN_OPTIONS=suppressions=MyASan.supp + +Use the following format to specify the names of the functions or libraries +you want to suppress. You can see these in the error report. Remember that +the narrower the scope of the suppression, the more bugs you will be able to +catch. + +.. code-block:: bash + + interceptor_via_fun:NameOfCFunctionToSuppress + interceptor_via_fun:-[ClassName objCMethodToSuppress:] + interceptor_via_lib:NameOfTheLibraryToSuppress + +Conditional Compilation with ``__has_feature(address_sanitizer)`` +----------------------------------------------------------------- In some cases one may need to execute different code depending on whether AddressSanitizer is enabled. @@ -122,28 +192,19 @@ this purpose. # endif #endif -``__attribute__((no_sanitize_address))`` ------------------------------------------------ +Disabling Instrumentation with ``__attribute__((no_sanitize("address")))`` +-------------------------------------------------------------------------- Some code should not be instrumented by AddressSanitizer. One may use the -function attribute -:ref:`no_sanitize_address <langext-address_sanitizer>` -(or a deprecated synonym `no_address_safety_analysis`) -to disable instrumentation of a particular function. This attribute may not be -supported by other compilers, so we suggest to use it together with -``__has_feature(address_sanitizer)``. - -Initialization order checking ------------------------------ - -AddressSanitizer can optionally detect dynamic initialization order problems, -when initialization of globals defined in one translation unit uses -globals defined in another translation unit. To enable this check at runtime, -you should set environment variable -``ASAN_OPTIONS=check_initialization_order=1``. +function attribute ``__attribute__((no_sanitize("address")))`` +(which has deprecated synonyms +:ref:`no_sanitize_address <langext-address_sanitizer>` and +`no_address_safety_analysis`) to disable instrumentation of a particular +function. This attribute may not be supported by other compilers, so we suggest +to use it together with ``__has_feature(address_sanitizer)``. -Blacklist ---------- +Suppressing Errors in Recompiled Code (Blacklist) +------------------------------------------------- AddressSanitizer supports ``src`` and ``fun`` entity types in :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports @@ -172,24 +233,6 @@ problems happening in certain source files or with certain global variables. type:*BadInitClassSubstring*=init src:bad/init/files/*=init -Memory leak detection ---------------------- - -For the experimental memory leak detector in AddressSanitizer, see -:doc:`LeakSanitizer`. - -Supported Platforms -=================== - -AddressSanitizer is supported on - -* Linux i386/x86\_64 (tested on Ubuntu 12.04); -* MacOS 10.6 - 10.9 (i386/x86\_64). -* Android ARM -* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current) - -Ports to various other platforms are in progress. - Limitations =========== @@ -202,6 +245,19 @@ Limitations usually expected. * Static linking is not supported. +Supported Platforms +=================== + +AddressSanitizer is supported on: + +* Linux i386/x86\_64 (tested on Ubuntu 12.04) +* OS X 10.7 - 10.11 (i386/x86\_64) +* iOS Simulator +* Android ARM +* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current) + +Ports to various other platforms are in progress. + Current Status ============== diff --git a/docs/AttributeReference.rst b/docs/AttributeReference.rst index 115a217..a763dde 100644 --- a/docs/AttributeReference.rst +++ b/docs/AttributeReference.rst @@ -1,1116 +1,13 @@ .. ------------------------------------------------------------------- NOTE: This file is automatically generated by running clang-tblgen - -gen-attr-docs. Do not edit this file by hand!! + -gen-attr-docs. Do not edit this file by hand!! The contents for + this file are automatically generated by a server-side process. + + Please do not commit this file. The file exists for local testing + purposes only. ------------------------------------------------------------------- =================== Attributes in Clang -=================== -.. contents:: - :local: - -Introduction -============ - -This page lists the attributes currently supported by Clang. - -Function Attributes -=================== - - -interrupt ---------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on -ARM targets. This attribute may be attached to a function definition and -instructs the backend to generate appropriate function entry/exit code so that -it can be used directly as an interrupt service routine. - -The parameter passed to the interrupt attribute is optional, but if -provided it must be a string literal with one of the following values: "IRQ", -"FIQ", "SWI", "ABORT", "UNDEF". - -The semantics are as follows: - -- If the function is AAPCS, Clang instructs the backend to realign the stack to - 8 bytes on entry. This is a general requirement of the AAPCS at public - interfaces, but may not hold when an exception is taken. Doing this allows - other AAPCS functions to be called. -- If the CPU is M-class this is all that needs to be done since the architecture - itself is designed in such a way that functions obeying the normal AAPCS ABI - constraints are valid exception handlers. -- If the CPU is not M-class, the prologue and epilogue are modified to save all - non-banked registers that are used, so that upon return the user-mode state - will not be corrupted. Note that to avoid unnecessary overhead, only - general-purpose (integer) registers are saved in this way. If VFP operations - are needed, that state must be saved manually. - - Specifically, interrupt kinds other than "FIQ" will save all core registers - except "lr" and "sp". "FIQ" interrupts will save r0-r7. -- If the CPU is not M-class, the return instruction is changed to one of the - canonical sequences permitted by the architecture for exception return. Where - possible the function itself will make the necessary "lr" adjustments so that - the "preferred return address" is selected. - - Unfortunately the compiler is unable to make this guarantee for an "UNDEF" - handler, where the offset from "lr" to the preferred return address depends on - the execution state of the code which generated the exception. In this case - a sequence equivalent to "movs pc, lr" will be used. - - -acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability) ------------------------------------------------------------------------------------------------------------ -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -Marks a function as acquiring a capability. - - -assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability) -------------------------------------------------------------------------------------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -Marks a function that dynamically tests whether a capability is held, and halts -the program if it is not held. - - -availability ------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -The ``availability`` attribute can be placed on declarations to describe the -lifecycle of that declaration relative to operating system versions. Consider -the function declaration for a hypothetical function ``f``: - -.. code-block:: c++ - - void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); - -The availability attribute states that ``f`` was introduced in Mac OS X 10.4, -deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information -is used by Clang to determine when it is safe to use ``f``: for example, if -Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()`` -succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call -succeeds but Clang emits a warning specifying that the function is deprecated. -Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call -fails because ``f()`` is no longer available. - -The availability attribute is a comma-separated list starting with the -platform name and then including clauses specifying important milestones in the -declaration's lifetime (in any order) along with additional information. Those -clauses can be: - -introduced=\ *version* - The first version in which this declaration was introduced. - -deprecated=\ *version* - The first version in which this declaration was deprecated, meaning that - users should migrate away from this API. - -obsoleted=\ *version* - The first version in which this declaration was obsoleted, meaning that it - was removed completely and can no longer be used. - -unavailable - This declaration is never available on this platform. - -message=\ *string-literal* - Additional message text that Clang will provide when emitting a warning or - error about use of a deprecated or obsoleted declaration. Useful to direct - users to replacement APIs. - -Multiple availability attributes can be placed on a declaration, which may -correspond to different platforms. Only the availability attribute with the -platform corresponding to the target platform will be used; any others will be -ignored. If no availability attribute specifies availability for the current -target platform, the availability attributes are ignored. Supported platforms -are: - -``ios`` - Apple's iOS operating system. The minimum deployment target is specified by - the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*`` - command-line arguments. - -``macosx`` - Apple's Mac OS X operating system. The minimum deployment target is - specified by the ``-mmacosx-version-min=*version*`` command-line argument. - -A declaration can be used even when deploying back to a platform version prior -to when the declaration was introduced. When this happens, the declaration is -`weakly linked -<https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_, -as if the ``weak_import`` attribute were added to the declaration. A -weakly-linked declaration may or may not be present a run-time, and a program -can determine whether the declaration is present by checking whether the -address of that declaration is non-NULL. - -If there are multiple declarations of the same entity, the availability -attributes must either match on a per-platform basis or later -declarations must not have availability attributes for that -platform. For example: - -.. code-block:: c - - void g(void) __attribute__((availability(macosx,introduced=10.4))); - void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches - void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform - void g(void); // okay, inherits both macosx and ios availability from above. - void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch - -When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,: - -.. code-block:: objc - - @interface A - - (id)method __attribute__((availability(macosx,introduced=10.4))); - - (id)method2 __attribute__((availability(macosx,introduced=10.4))); - @end - - @interface B : A - - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later - - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4 - @end - - -_Noreturn ---------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "","","","X" - -A function declared as ``_Noreturn`` shall not return to its caller. The -compiler will generate a diagnostic for a function declared as ``_Noreturn`` -that appears to be capable of returning to its caller. - - -noreturn --------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "","X","","" - -A function declared as ``[[noreturn]]`` shall not return to its caller. The -compiler will generate a diagnostic for a function declared as ``[[noreturn]]`` -that appears to be capable of returning to its caller. - - -carries_dependency ------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -The ``carries_dependency`` attribute specifies dependency propagation into and -out of functions. - -When specified on a function or Objective-C method, the ``carries_dependency`` -attribute means that the return value carries a dependency out of the function, -so that the implementation need not constrain ordering upon return from that -function. Implementations of the function and its caller may choose to preserve -dependencies instead of emitting memory ordering instructions such as fences. - -Note, this attribute does not change the meaning of the program, but may result -in generation of more efficient code. - - -enable_if ---------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -.. Note:: Some features of this attribute are experimental. The meaning of - multiple enable_if attributes on a single declaration is subject to change in - a future version of clang. Also, the ABI is not standardized and the name - mangling may change in future versions. To avoid that, use asm labels. - -The ``enable_if`` attribute can be placed on function declarations to control -which overload is selected based on the values of the function's arguments. -When combined with the ``overloadable`` attribute, this feature is also -available in C. - -.. code-block:: c++ - - int isdigit(int c); - int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF"))); - - void foo(char c) { - isdigit(c); - isdigit(10); - isdigit(-10); // results in a compile-time error. - } - -The enable_if attribute takes two arguments, the first is an expression written -in terms of the function parameters, the second is a string explaining why this -overload candidate could not be selected to be displayed in diagnostics. The -expression is part of the function signature for the purposes of determining -whether it is a redeclaration (following the rules used when determining -whether a C++ template specialization is ODR-equivalent), but is not part of -the type. - -The enable_if expression is evaluated as if it were the body of a -bool-returning constexpr function declared with the arguments of the function -it is being applied to, then called with the parameters at the callsite. If the -result is false or could not be determined through constant expression -evaluation, then this overload will not be chosen and the provided string may -be used in a diagnostic if the compile fails as a result. - -Because the enable_if expression is an unevaluated context, there are no global -state changes, nor the ability to pass information from the enable_if -expression to the function body. For example, suppose we want calls to -strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of -strbuf) only if the size of strbuf can be determined: - -.. code-block:: c++ - - __attribute__((always_inline)) - static inline size_t strnlen(const char *s, size_t maxlen) - __attribute__((overloadable)) - __attribute__((enable_if(__builtin_object_size(s, 0) != -1))), - "chosen when the buffer size is known but 'maxlen' is not"))) - { - return strnlen_chk(s, maxlen, __builtin_object_size(s, 0)); - } - -Multiple enable_if attributes may be applied to a single declaration. In this -case, the enable_if expressions are evaluated from left to right in the -following manner. First, the candidates whose enable_if expressions evaluate to -false or cannot be evaluated are discarded. If the remaining candidates do not -share ODR-equivalent enable_if expressions, the overload resolution is -ambiguous. Otherwise, enable_if overload resolution continues with the next -enable_if attribute on the candidates that have not been discarded and have -remaining enable_if attributes. In this way, we pick the most specific -overload out of a number of viable overloads using enable_if. - -.. code-block:: c++ - - void f() __attribute__((enable_if(true, ""))); // #1 - void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2 - - void g(int i, int j) __attribute__((enable_if(i, ""))); // #1 - void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2 - -In this example, a call to f() is always resolved to #2, as the first enable_if -expression is ODR-equivalent for both declarations, but #1 does not have another -enable_if expression to continue evaluating, so the next round of evaluation has -only a single candidate. In a call to g(1, 1), the call is ambiguous even though -#2 has more enable_if attributes, because the first enable_if expressions are -not ODR-equivalent. - -Query for this feature with ``__has_attribute(enable_if)``. - - -flatten (gnu::flatten) ----------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -The ``flatten`` attribute causes calls within the attributed function to -be inlined unless it is impossible to do so, for example if the body of the -callee is unavailable or if the callee has the ``noinline`` attribute. - - -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. - - -noduplicate (clang::noduplicate) --------------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -The ``noduplicate`` attribute can be placed on function declarations to control -whether function calls to this function can be duplicated or not as a result of -optimizations. This is required for the implementation of functions with -certain special requirements, like the OpenCL "barrier" function, that might -need to be run concurrently by all the threads that are executing in lockstep -on the hardware. For example this attribute applied on the function -"nodupfunc" in the code below avoids that: - -.. code-block:: c - - void nodupfunc() __attribute__((noduplicate)); - // Setting it as a C++11 attribute is also valid - // void nodupfunc() [[clang::noduplicate]]; - void foo(); - void bar(); - - nodupfunc(); - if (a > n) { - foo(); - } else { - bar(); - } - -gets possibly modified by some optimizations into code similar to this: - -.. code-block:: c - - if (a > n) { - nodupfunc(); - foo(); - } else { - nodupfunc(); - bar(); - } - -where the call to "nodupfunc" is duplicated and sunk into the two branches -of the condition. - - -no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address) ------------------------------------------------------------------------------------------------------------ -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -.. _langext-address_sanitizer: - -Use ``__attribute__((no_sanitize_address))`` on a function declaration to -specify that address safety instrumentation (e.g. AddressSanitizer) should -not be applied to that function. - - -no_sanitize_memory ------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -.. _langext-memory_sanitizer: - -Use ``__attribute__((no_sanitize_memory))`` on a function declaration to -specify that checks for uninitialized memory should not be inserted -(e.g. by MemorySanitizer). The function may still be instrumented by the tool -to avoid false positives in other places. - - -no_sanitize_thread ------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -.. _langext-thread_sanitizer: - -Use ``__attribute__((no_sanitize_thread))`` on a function declaration to -specify that checks for data races on plain (non-atomic) memory accesses should -not be inserted by ThreadSanitizer. The function is still instrumented by the -tool to avoid false positives and provide meaningful stack traces. - - -no_split_stack (gnu::no_split_stack) ------------------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -The ``no_split_stack`` attribute disables the emission of the split stack -preamble for a particular function. It has no effect if ``-fsplit-stack`` -is not specified. - - -objc_method_family ------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Many methods in Objective-C have conventional meanings determined by their -selectors. It is sometimes useful to be able to mark a method as having a -particular conventional meaning despite not having the right selector, or as -not having the conventional meaning that its selector would suggest. For these -use cases, we provide an attribute to specifically describe the "method family" -that a method belongs to. - -**Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of -``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This -attribute can only be placed at the end of a method declaration: - -.. code-block:: objc - - - (NSString *)initMyStringValue __attribute__((objc_method_family(none))); - -Users who do not wish to change the conventional meaning of a method, and who -merely want to document its non-standard retain and release semantics, should -use the retaining behavior attributes (``ns_returns_retained``, -``ns_returns_not_retained``, etc). - -Query for this feature with ``__has_attribute(objc_method_family)``. - - -objc_requires_super -------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Some Objective-C classes allow a subclass to override a particular method in a -parent class but expect that the overriding method also calls the overridden -method in the parent class. For these cases, we provide an attribute to -designate that a method requires a "call to ``super``" in the overriding -method in the subclass. - -**Usage**: ``__attribute__((objc_requires_super))``. This attribute can only -be placed at the end of a method declaration: - -.. code-block:: objc - - - (void)foo __attribute__((objc_requires_super)); - -This attribute can only be applied the method declarations within a class, and -not a protocol. Currently this attribute does not enforce any placement of -where the call occurs in the overriding method (such as in the case of -``-dealloc`` where the call must appear at the end). It checks only that it -exists. - -Note that on both OS X and iOS that the Foundation framework provides a -convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this -attribute: - -.. code-block:: objc - - - (void)foo NS_REQUIRES_SUPER; - -This macro is conditionally defined depending on the compiler's support for -this attribute. If the compiler does not support the attribute the macro -expands to nothing. - -Operationally, when a method has this annotation the compiler will warn if the -implementation of an override in a subclass does not call super. For example: - -.. code-block:: objc - - warning: method possibly missing a [super AnnotMeth] call - - (void) AnnotMeth{}; - ^ - - -optnone (clang::optnone) ------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -The ``optnone`` attribute suppresses essentially all optimizations -on a function or method, regardless of the optimization level applied to -the compilation unit as a whole. This is particularly useful when you -need to debug a particular function, but it is infeasible to build the -entire application without optimization. Avoiding optimization on the -specified function can improve the quality of the debugging information -for that function. - -This attribute is incompatible with the ``always_inline`` attribute. - - -overloadable ------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Clang provides support for C++ function overloading in C. Function overloading -in C is introduced using the ``overloadable`` attribute. For example, one -might provide several overloaded versions of a ``tgsin`` function that invokes -the appropriate standard function computing the sine of a value with ``float``, -``double``, or ``long double`` precision: - -.. code-block:: c - - #include <math.h> - float __attribute__((overloadable)) tgsin(float x) { return sinf(x); } - double __attribute__((overloadable)) tgsin(double x) { return sin(x); } - long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); } - -Given these declarations, one can call ``tgsin`` with a ``float`` value to -receive a ``float`` result, with a ``double`` to receive a ``double`` result, -etc. Function overloading in C follows the rules of C++ function overloading -to pick the best overload given the call arguments, with a few C-specific -semantics: - -* Conversion from ``float`` or ``double`` to ``long double`` is ranked as a - floating-point promotion (per C99) rather than as a floating-point conversion - (as in C++). - -* A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is - considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are - compatible types. - -* A conversion from type ``T`` to a value of type ``U`` is permitted if ``T`` - and ``U`` are compatible types. This conversion is given "conversion" rank. - -The declaration of ``overloadable`` functions is restricted to function -declarations and definitions. Most importantly, if any function with a given -name is given the ``overloadable`` attribute, then all function declarations -and definitions with that name (and in that scope) must have the -``overloadable`` attribute. This rule even applies to redeclarations of -functions whose original declaration had the ``overloadable`` attribute, e.g., - -.. code-block:: c - - int f(int) __attribute__((overloadable)); - float f(float); // error: declaration of "f" must have the "overloadable" attribute - - int g(int) __attribute__((overloadable)); - int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute - -Functions marked ``overloadable`` must have prototypes. Therefore, the -following code is ill-formed: - -.. code-block:: c - - int h() __attribute__((overloadable)); // error: h does not have a prototype - -However, ``overloadable`` functions are allowed to use a ellipsis even if there -are no named parameters (as is permitted in C++). This feature is particularly -useful when combined with the ``unavailable`` attribute: - -.. code-block:: c++ - - void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error - -Functions declared with the ``overloadable`` attribute have their names mangled -according to the same rules as C++ function names. For example, the three -``tgsin`` functions in our motivating example get the mangled names -``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two -caveats to this use of name mangling: - -* Future versions of Clang may change the name mangling of functions overloaded - in C, so you should not depend on an specific mangling. To be completely - safe, we strongly urge the use of ``static inline`` with ``overloadable`` - functions. - -* The ``overloadable`` attribute has almost no meaning when used in C++, - because names will already be mangled and functions are already overloadable. - However, when an ``overloadable`` function occurs within an ``extern "C"`` - linkage specification, it's name *will* be mangled in the same way as it - would in C. - -Query for this feature with ``__has_extension(attribute_overloadable)``. - - -pcs (gnu::pcs) --------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -On ARM targets, this can attribute can be used to select calling conventions, -similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and -"aapcs-vfp". - - -release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability) ------------------------------------------------------------------------------------------------------------ -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -Marks a function as releasing a capability. - - -try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability) ---------------------------------------------------------------------------------------------------------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -Marks a function that attempts to acquire a capability. This function may fail to -actually acquire the capability; they accept a Boolean value determining -whether acquiring the capability means success (true), or failing to acquire -the capability means success (false). - - -Variable Attributes -=================== - - -section (gnu::section, __declspec(allocate)) --------------------------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","X","" - -The ``section`` attribute allows you to specify a specific section a -global variable or function should be in after translation. - - -tls_model (gnu::tls_model) --------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","X","","" - -The ``tls_model`` attribute allows you to specify which thread-local storage -model to use. It accepts the following strings: - -* global-dynamic -* local-dynamic -* initial-exec -* local-exec - -TLS models are mutually exclusive. - - -thread ------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "","","X","" - -The ``__declspec(thread)`` attribute declares a variable with thread local -storage. It is available under the ``-fms-extensions`` flag for MSVC -compatibility. Documentation for the Visual C++ attribute is available on MSDN_. - -.. _MSDN: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx - -In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the -GNU ``__thread`` keyword. The variable must not have a destructor and must have -a constant initializer, if any. The attribute only applies to variables -declared with static storage duration, such as globals, class static data -members, and static locals. - - -Type Attributes -=============== - - -__single_inhertiance, __multiple_inheritance, __virtual_inheritance -------------------------------------------------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "","","","X" - -This collection of keywords is enabled under ``-fms-extensions`` and controls -the pointer-to-member representation used on ``*-*-win32`` targets. - -The ``*-*-win32`` targets utilize a pointer-to-member representation which -varies in size and alignment depending on the definition of the underlying -class. - -However, this is problematic when a forward declaration is only available and -no definition has been made yet. In such cases, Clang is forced to utilize the -most general representation that is available to it. - -These keywords make it possible to use a pointer-to-member representation other -than the most general one regardless of whether or not the definition will ever -be present in the current translation unit. - -This family of keywords belong between the ``class-key`` and ``class-name``: - -.. code-block:: c++ - - struct __single_inheritance S; - int S::*i; - struct S {}; - -This keyword can be applied to class templates but only has an effect when used -on full specializations: - -.. code-block:: c++ - - template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template - template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization - template <> struct __single_inheritance A<int, float>; - -Note that choosing an inheritance model less general than strictly necessary is -an error: - -.. code-block:: c++ - - struct __multiple_inheritance S; // error: inheritance model does not match definition - int S::*i; - struct S {}; - - -Statement Attributes -==================== - - -fallthrough (clang::fallthrough) --------------------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "","X","","" - -The ``clang::fallthrough`` attribute is used along with the -``-Wimplicit-fallthrough`` argument to annotate intentional fall-through -between switch labels. It can only be applied to a null statement placed at a -point of execution between any statement and the next switch label. It is -common to mark these places with a specific comment, but this attribute is -meant to replace comments with a more strict annotation, which can be checked -by the compiler. This attribute doesn't change semantics of the code and can -be used wherever an intended fall-through occurs. It is designed to mimic -control-flow statements like ``break;``, so it can be placed in most places -where ``break;`` can, but only if there are no statements on the execution path -between it and the next switch label. - -Here is an example: - -.. code-block:: c++ - - // compile with -Wimplicit-fallthrough - switch (n) { - case 22: - case 33: // no warning: no statements between case labels - f(); - case 44: // warning: unannotated fall-through - g(); - [[clang::fallthrough]]; - case 55: // no warning - if (x) { - h(); - break; - } - else { - i(); - [[clang::fallthrough]]; - } - case 66: // no warning - p(); - [[clang::fallthrough]]; // warning: fallthrough annotation does not - // directly precede case label - q(); - case 77: // warning: unannotated fall-through - r(); - } - - -Consumed Annotation Checking -============================ -Clang supports additional attributes for checking basic resource management -properties, specifically for unique objects that have a single owning reference. -The following attributes are currently supported, although **the implementation -for these annotations is currently in development and are subject to change.** - -callable_when -------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Use ``__attribute__((callable_when(...)))`` to indicate what states a method -may be called in. Valid states are unconsumed, consumed, or unknown. Each -argument to this attribute must be a quoted string. E.g.: - -``__attribute__((callable_when("unconsumed", "unknown")))`` - - -consumable ----------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Each ``class`` that uses any of the typestate annotations must first be marked -using the ``consumable`` attribute. Failure to do so will result in a warning. - -This attribute accepts a single parameter that must be one of the following: -``unknown``, ``consumed``, or ``unconsumed``. - - -param_typestate ---------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -This attribute specifies expectations about function parameters. Calls to an -function with annotated parameters will issue a warning if the corresponding -argument isn't in the expected state. The attribute is also used to set the -initial state of the parameter when analyzing the function's body. - - -return_typestate ----------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -The ``return_typestate`` attribute can be applied to functions or parameters. -When applied to a function the attribute specifies the state of the returned -value. The function's body is checked to ensure that it always returns a value -in the specified state. On the caller side, values returned by the annotated -function are initialized to the given state. - -When applied to a function parameter it modifies the state of an argument after -a call to the function returns. The function's body is checked to ensure that -the parameter is in the expected state before returning. - - -set_typestate -------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Annotate methods that transition an object into a new state with -``__attribute__((set_typestate(new_state)))``. The new new state must be -unconsumed, consumed, or unknown. - - -test_typestate --------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method -returns true if the object is in the specified state.. - - -Type Safety Checking -==================== -Clang supports additional attributes to enable checking type safety properties -that can't be enforced by the C type system. Use cases include: - -* MPI library implementations, where these attributes enable checking that - the buffer type matches the passed ``MPI_Datatype``; -* for HDF5 library there is a similar use case to MPI; -* checking types of variadic functions' arguments for functions like - ``fcntl()`` and ``ioctl()``. - -You can detect support for these attributes with ``__has_attribute()``. For -example: - -.. code-block:: c++ - - #if defined(__has_attribute) - # if __has_attribute(argument_with_type_tag) && \ - __has_attribute(pointer_with_type_tag) && \ - __has_attribute(type_tag_for_datatype) - # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) - /* ... other macros ... */ - # endif - #endif - - #if !defined(ATTR_MPI_PWT) - # define ATTR_MPI_PWT(buffer_idx, type_idx) - #endif - - int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) - ATTR_MPI_PWT(1,3); - -argument_with_type_tag ----------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx, -type_tag_idx)))`` on a function declaration to specify that the function -accepts a type tag that determines the type of some other argument. -``arg_kind`` is an identifier that should be used when annotating all -applicable type tags. - -This attribute is primarily useful for checking arguments of variadic functions -(``pointer_with_type_tag`` can be used in most non-variadic cases). - -For example: - -.. code-block:: c++ - - int fcntl(int fd, int cmd, ...) - __attribute__(( argument_with_type_tag(fcntl,3,2) )); - - -pointer_with_type_tag ---------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`` -on a function declaration to specify that the function accepts a type tag that -determines the pointee type of some other pointer argument. - -For example: - -.. code-block:: c++ - - int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) - __attribute__(( pointer_with_type_tag(mpi,1,3) )); - - -type_tag_for_datatype ---------------------- -.. csv-table:: Supported Syntaxes - :header: "GNU", "C++11", "__declspec", "Keyword" - - "X","","","" - -Clang supports annotating type tags of two forms. - -* **Type tag that is an expression containing a reference to some declared - identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a - declaration with that identifier: - - .. code-block:: c++ - - extern struct mpi_datatype mpi_datatype_int - __attribute__(( type_tag_for_datatype(mpi,int) )); - #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) - -* **Type tag that is an integral literal.** Introduce a ``static const`` - variable with a corresponding initializer value and attach - ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration, - for example: - - .. code-block:: c++ - - #define MPI_INT ((MPI_Datatype) 42) - static const MPI_Datatype mpi_datatype_int - __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 - -The attribute also accepts an optional third argument that determines how the -expression is compared to the type tag. There are two supported flags: - -* ``layout_compatible`` will cause types to be compared according to - layout-compatibility rules (C++11 [class.mem] p 17, 18). This is - implemented to support annotating types like ``MPI_DOUBLE_INT``. - - For example: - - .. code-block:: c++ - - /* In mpi.h */ - struct internal_mpi_double_int { double d; int i; }; - extern struct mpi_datatype mpi_datatype_double_int - __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) )); - - #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) - - /* In user code */ - struct my_pair { double a; int b; }; - struct my_pair *buffer; - MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning - - struct my_int_pair { int a; int b; } - struct my_int_pair *buffer2; - MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element - // type 'struct my_int_pair' - // doesn't match specified MPI_Datatype - -* ``must_be_null`` specifies that the expression should be a null pointer - constant, for example: - - .. code-block:: c++ - - /* In mpi.h */ - extern struct mpi_datatype mpi_datatype_null - __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); - - #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) - - /* In user code */ - MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL - // was specified but buffer - // is not a null pointer - - +===================
\ No newline at end of file diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 20a1396..47bb2e0 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -87,5 +87,8 @@ if (LLVM_ENABLE_SPHINX) if (${SPHINX_OUTPUT_HTML}) add_sphinx_target(html clang) endif() + if (${SPHINX_OUTPUT_MAN}) + add_sphinx_target(man clang) + endif() endif() endif() diff --git a/docs/ClangFormatStyleOptions.rst b/docs/ClangFormatStyleOptions.rst index f4c4c8c..ab7bd87 100644 --- a/docs/ClangFormatStyleOptions.rst +++ b/docs/ClangFormatStyleOptions.rst @@ -218,12 +218,19 @@ the configuration (without a prefix: ``Auto``). If ``true``, ``while (true) continue;`` can be put on a single line. -**AlwaysBreakAfterDefinitionReturnType** (``bool``) - If ``true``, always break after function definition return types. +**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) + The function definition return type breaking style to use. + + Possible values: + + * ``DRTBS_None`` (in configuration: ``None``) + Break after return type automatically. + ``PenaltyReturnTypeOnItsOwnLine`` is taken into account. + * ``DRTBS_All`` (in configuration: ``All``) + Always break after the return type. + * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``) + Always break after the return types of top level functions. - More truthfully called 'break before the identifier following the type - in a function definition'. PenaltyReturnTypeOnItsOwnLine becomes - irrelevant. **AlwaysBreakBeforeMultilineStrings** (``bool``) If ``true``, always break before multiline string literals. @@ -327,7 +334,7 @@ the configuration (without a prefix: ``Auto``). alignment of & and \*. ``PointerAlignment`` is then used only as fallback. **DisableFormat** (``bool``) - Disables formatting at all. + Disables formatting completely. **ExperimentalAutoDetectBinPacking** (``bool``) If ``true``, clang-format detects whether function calls and diff --git a/docs/CommandGuide/clang.rst b/docs/CommandGuide/clang.rst new file mode 100644 index 0000000..39dbe02 --- /dev/null +++ b/docs/CommandGuide/clang.rst @@ -0,0 +1,484 @@ +clang - the Clang C, C++, and Objective-C compiler +================================================== + +SYNOPSIS +-------- + +:program:`clang` [*options*] *filename ...* + +DESCRIPTION +----------- + +:program:`clang` is a C, C++, and Objective-C compiler which encompasses +preprocessing, parsing, optimization, code generation, assembly, and linking. +Depending on which high-level mode setting is passed, Clang will stop before +doing a full link. While Clang is highly integrated, it is important to +understand the stages of compilation, to understand how to invoke it. These +stages are: + +Driver + The clang executable is actually a small driver which controls the overall + execution of other tools such as the compiler, assembler and linker. + Typically you do not need to interact with the driver, but you + transparently use it to run the other tools. + +Preprocessing + This stage handles tokenization of the input source file, macro expansion, + #include expansion and handling of other preprocessor directives. The + output of this stage is typically called a ".i" (for C), ".ii" (for C++), + ".mi" (for Objective-C), or ".mii" (for Objective-C++) file. + +Parsing and Semantic Analysis + This stage parses the input file, translating preprocessor tokens into a + parse tree. Once in the form of a parse tree, it applies semantic + analysis to compute types for expressions as well and determine whether + the code is well formed. This stage is responsible for generating most of + the compiler warnings as well as parse errors. The output of this stage is + an "Abstract Syntax Tree" (AST). + +Code Generation and Optimization + This stage translates an AST into low-level intermediate code (known as + "LLVM IR") and ultimately to machine code. This phase is responsible for + optimizing the generated code and handling target-specific code generation. + The output of this stage is typically called a ".s" file or "assembly" file. + + Clang also supports the use of an integrated assembler, in which the code + generator produces object files directly. This avoids the overhead of + generating the ".s" file and of calling the target assembler. + +Assembler + This stage runs the target assembler to translate the output of the + compiler into a target object file. The output of this stage is typically + called a ".o" file or "object" file. + +Linker + This stage runs the target linker to merge multiple object files into an + executable or dynamic library. The output of this stage is typically called + an "a.out", ".dylib" or ".so" file. + +:program:`Clang Static Analyzer` + +The Clang Static Analyzer is a tool that scans source code to try to find bugs +through code analysis. This tool uses many parts of Clang and is built into +the same driver. Please see <http://clang-analyzer.llvm.org> for more details +on how to use the static analyzer. + +OPTIONS +------- + +Stage Selection Options +~~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: -E + + Run the preprocessor stage. + +.. option:: -fsyntax-only + + Run the preprocessor, parser and type checking stages. + +.. option:: -S + + Run the previous stages as well as LLVM generation and optimization stages + and target-specific code generation, producing an assembly file. + +.. option:: -c + + Run all of the above, plus the assembler, generating a target ".o" object file. + +.. option:: no stage selection option + + If no stage selection option is specified, all stages above are run, and the + linker is run to combine the results into an executable or shared library. + +Language Selection and Mode Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: -x <language> + + Treat subsequent input files as having type language. + +.. option:: -std=<language> + + Specify the language standard to compile for. + +.. option:: -stdlib=<library> + + Specify the C++ standard library to use; supported options are libstdc++ and + libc++. + +.. option:: -ansi + + Same as -std=c89. + +.. option:: -ObjC, -ObjC++ + + Treat source input files as Objective-C and Object-C++ inputs respectively. + +.. option:: -trigraphs + + Enable trigraphs. + +.. option:: -ffreestanding + + Indicate that the file should be compiled for a freestanding, not a hosted, + environment. + +.. option:: -fno-builtin + + Disable special handling and optimizations of builtin functions like + :c:func:`strlen` and :c:func:`malloc`. + +.. option:: -fmath-errno + + Indicate that math functions should be treated as updating :c:data:`errno`. + +.. option:: -fpascal-strings + + Enable support for Pascal-style strings with "\\pfoo". + +.. option:: -fms-extensions + + Enable support for Microsoft extensions. + +.. option:: -fmsc-version= + + Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise. + +.. option:: -fborland-extensions + + Enable support for Borland extensions. + +.. option:: -fwritable-strings + + Make all string literals default to writable. This disables uniquing of + strings and other optimizations. + +.. option:: -flax-vector-conversions + + Allow loose type checking rules for implicit vector conversions. + +.. option:: -fblocks + + Enable the "Blocks" language feature. + +.. option:: -fobjc-gc-only + + Indicate that Objective-C code should be compiled in GC-only mode, which only + works when Objective-C Garbage Collection is enabled. + +.. option:: -fobjc-gc + + Indicate that Objective-C code should be compiled in hybrid-GC mode, which + works with both GC and non-GC mode. + +.. option:: -fobjc-abi-version=version + + Select the Objective-C ABI version to use. Available versions are 1 (legacy + "fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2). + +.. option:: -fobjc-nonfragile-abi-version=<version> + + Select the Objective-C non-fragile ABI version to use by default. This will + only be used as the Objective-C ABI when the non-fragile ABI is enabled + (either via :option:`-fobjc-nonfragile-abi`, or because it is the platform + default). + +.. option:: -fobjc-nonfragile-abi + + Enable use of the Objective-C non-fragile ABI. On platforms for which this is + the default ABI, it can be disabled with :option:`-fno-objc-nonfragile-abi`. + +Target Selection Options +~~~~~~~~~~~~~~~~~~~~~~~~ + +Clang fully supports cross compilation as an inherent part of its design. +Depending on how your version of Clang is configured, it may have support for a +number of cross compilers, or may only support a native target. + +.. option:: -arch <architecture> + + Specify the architecture to build for. + +.. option:: -mmacosx-version-min=<version> + + When building for Mac OS X, specify the minimum version supported by your + application. + +.. option:: -miphoneos-version-min + + When building for iPhone OS, specify the minimum version supported by your + application. + +.. option:: -march=<cpu> + + Specify that Clang should generate code for a specific processor family + member and later. For example, if you specify -march=i486, the compiler is + allowed to generate instructions that are valid on i486 and later processors, + but which may not exist on earlier ones. + + +Code Generation Options +~~~~~~~~~~~~~~~~~~~~~~~ + +.. option:: -O0, -O1, -O2, -O3, -Ofast, -Os, -Oz, -O, -O4 + + Specify which optimization level to use: + + :option:`-O0` Means "no optimization": this level compiles the fastest and + generates the most debuggable code. + + :option:`-O1` Somewhere between :option:`-O0` and :option:`-O2`. + + :option:`-O2` Moderate level of optimization which enables most + optimizations. + + :option:`-O3` Like :option:`-O2`, except that it enables optimizations that + take longer to perform or that may generate larger code (in an attempt to + make the program run faster). + + :option:`-Ofast` Enables all the optimizations from :option:`-O3` along + with other aggressive optimizations that may violate strict compliance with + language standards. + + :option:`-Os` Like :option:`-O2` with extra optimizations to reduce code + size. + + :option:`-Oz` Like :option:`-Os` (and thus :option:`-O2`), but reduces code + size further. + + :option:`-O` Equivalent to :option:`-O2`. + + :option:`-O4` and higher + + Currently equivalent to :option:`-O3` + +.. option:: -g + + Generate debug information. Note that Clang debug information works best at -O0. + +.. option:: -fstandalone-debug -fno-standalone-debug + + Clang supports a number of optimizations to reduce the size of debug + information in the binary. They work based on the assumption that the + debug type information can be spread out over multiple compilation units. + For instance, Clang will not emit type definitions for types that are not + needed by a module and could be replaced with a forward declaration. + Further, Clang will only emit type info for a dynamic C++ class in the + module that contains the vtable for the class. + + The :option:`-fstandalone-debug` option turns off these optimizations. + This is useful when working with 3rd-party libraries that don't come with + debug information. This is the default on Darwin. Note that Clang will + never emit type information for types that are not referenced at all by the + program. + +.. option:: -fexceptions + + Enable generation of unwind information. This allows exceptions to be thrown + through Clang compiled stack frames. This is on by default in x86-64. + +.. option:: -ftrapv + + Generate code to catch integer overflow errors. Signed integer overflow is + undefined in C. With this flag, extra code is generated to detect this and + abort when it happens. + +.. option:: -fvisibility + + This flag sets the default visibility level. + +.. option:: -fcommon + + This flag specifies that variables without initializers get common linkage. + It can be disabled with :option:`-fno-common`. + +.. option:: -ftls-model=<model> + + Set the default thread-local storage (TLS) model to use for thread-local + variables. Valid values are: "global-dynamic", "local-dynamic", + "initial-exec" and "local-exec". The default is "global-dynamic". The default + model can be overridden with the tls_model attribute. The compiler will try + to choose a more efficient model if possible. + +.. option:: -flto, -emit-llvm + + Generate output files in LLVM formats, suitable for link time optimization. + When used with :option:`-S` this generates LLVM intermediate language + assembly files, otherwise this generates LLVM bitcode format object files + (which may be passed to the linker depending on the stage selection options). + +Driver Options +~~~~~~~~~~~~~~ + +.. option:: -### + + Print (but do not run) the commands to run for this compilation. + +.. option:: --help + + Display available options. + +.. option:: -Qunused-arguments + + Do not emit any warnings for unused driver arguments. + +.. option:: -Wa,<args> + + Pass the comma separated arguments in args to the assembler. + +.. option:: -Wl,<args> + + Pass the comma separated arguments in args to the linker. + +.. option:: -Wp,<args> + + Pass the comma separated arguments in args to the preprocessor. + +.. option:: -Xanalyzer <arg> + + Pass arg to the static analyzer. + +.. option:: -Xassembler <arg> + + Pass arg to the assembler. + +.. option:: -Xlinker <arg> + + Pass arg to the linker. + +.. option:: -Xpreprocessor <arg> + + Pass arg to the preprocessor. + +.. option:: -o <file> + + Write output to file. + +.. option:: -print-file-name=<file> + + Print the full library path of file. + +.. option:: -print-libgcc-file-name + + Print the library path for "libgcc.a". + +.. option:: -print-prog-name=<name> + + Print the full program path of name. + +.. option:: -print-search-dirs + + Print the paths used for finding libraries and programs. + +.. option:: -save-temps + + Save intermediate compilation results. + +.. option:: -integrated-as, -no-integrated-as + + Used to enable and disable, respectively, the use of the integrated + assembler. Whether the integrated assembler is on by default is target + dependent. + +.. option:: -time + + Time individual commands. + +.. option:: -ftime-report + + Print timing summary of each stage of compilation. + +.. option:: -v + + Show commands to run and use verbose output. + + +Diagnostics Options +~~~~~~~~~~~~~~~~~~~ + +.. option:: -fshow-column, -fshow-source-location, -fcaret-diagnostics, -fdiagnostics-fixit-info, -fdiagnostics-parseable-fixits, -fdiagnostics-print-source-range-info, -fprint-source-range-info, -fdiagnostics-show-option, -fmessage-length + + These options control how Clang prints out information about diagnostics + (errors and warnings). Please see the Clang User's Manual for more information. + +Preprocessor Options +~~~~~~~~~~~~~~~~~~~~ + +.. option:: -D<macroname>=<value> + + Adds an implicit #define into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -U<macroname> + + Adds an implicit #undef into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -include <filename> + + Adds an implicit #include into the predefines buffer which is read before the + source file is preprocessed. + +.. option:: -I<directory> + + Add the specified directory to the search path for include files. + +.. option:: -F<directory> + + Add the specified directory to the search path for framework include files. + +.. option:: -nostdinc + + Do not search the standard system directories or compiler builtin directories + for include files. + +.. option:: -nostdlibinc + + Do not search the standard system directories for include files, but do + search compiler builtin include directories. + +.. option:: -nobuiltininc + + Do not search clang's builtin directory for include files. + + +ENVIRONMENT +----------- + +.. envvar:: TMPDIR, TEMP, TMP + + These environment variables are checked, in order, for the location to write + temporary files used during the compilation process. + +.. envvar:: CPATH + + If this environment variable is present, it is treated as a delimited list of + paths to be added to the default system include path list. The delimiter is + the platform dependent delimiter, as used in the PATH environment variable. + + Empty components in the environment variable are ignored. + +.. envvar:: C_INCLUDE_PATH, OBJC_INCLUDE_PATH, CPLUS_INCLUDE_PATH, OBJCPLUS_INCLUDE_PATH + + These environment variables specify additional paths, as for :envvar:`CPATH`, which are + only used when processing the appropriate language. + +.. envvar:: MACOSX_DEPLOYMENT_TARGET + + If :option:`-mmacosx-version-min` is unspecified, the default deployment + target is read from this environment variable. This option only affects + Darwin targets. + +BUGS +---- + +To report bugs, please visit <http://llvm.org/bugs/>. Most bug reports should +include preprocessed source files (use the :option:`-E` option) and the full +output of the compiler, along with information to reproduce. + +SEE ALSO +-------- + +:manpage:`as(1)`, :manpage:`ld(1)` + diff --git a/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst new file mode 100644 index 0000000..826ed97 --- /dev/null +++ b/docs/CommandGuide/index.rst @@ -0,0 +1,17 @@ +Clang "man" pages +----------------- + +The following documents are command descriptions for all of the Clang tools. +These pages describe how to use the Clang commands and what their options are. +Note that these pages do not describe all of the options available for all +tools. To get a complete listing, pass the ``--help`` (general options) or +``--help-hidden`` (general and debugging options) arguments to the tool you are +interested in. + +Basic Commands +~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + clang diff --git a/docs/DriverInternals.rst b/docs/DriverInternals.rst index 4cd2e5d..6bc5f7d 100644 --- a/docs/DriverInternals.rst +++ b/docs/DriverInternals.rst @@ -155,7 +155,7 @@ The driver functionality is conceptually divided into five stages: Subsequent stages should rarely, if ever, need to do any string processing. -#. **Pipeline: Compilation Job Construction** +#. **Pipeline: Compilation Action Construction** Once the arguments are parsed, the tree of subprocess jobs needed for the desired compilation sequence are constructed. This involves @@ -266,7 +266,7 @@ The driver functionality is conceptually divided into five stages: #. **Translate: Tool Specific Argument Translation** Once a Tool has been selected to perform a particular Action, the - Tool must construct concrete Jobs which will be executed during + Tool must construct concrete Commands which will be executed during compilation. The main work is in translating from the gcc style command line options to whatever options the subprocess expects. @@ -280,7 +280,7 @@ The driver functionality is conceptually divided into five stages: last of arguments corresponding to some option, or all arguments for an option. - The result of this stage is a list of Jobs (executable paths and + The result of this stage is a list of Commands (executable paths and argument strings) to execute. #. **Execute** diff --git a/docs/LeakSanitizer.rst b/docs/LeakSanitizer.rst index b1071ef..d4b4fa0 100644 --- a/docs/LeakSanitizer.rst +++ b/docs/LeakSanitizer.rst @@ -17,7 +17,8 @@ only, at a minimal performance cost. Current status ============== -LeakSanitizer is experimental and supported only on x86\_64 Linux. +LeakSanitizer is turned on by default, but it is only supported on x86\_64 +Linux. The combined mode has been tested on fairly large software projects. The stand-alone mode has received much less testing. diff --git a/docs/LibASTMatchersReference.html b/docs/LibASTMatchersReference.html index 74bbf9e..a555bb3 100644 --- a/docs/LibASTMatchersReference.html +++ b/docs/LibASTMatchersReference.html @@ -1434,6 +1434,16 @@ Usable as: Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1Charac Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>>, Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>> </pre></td></tr> +<tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXCatchStmt.html">CXXCatchStmt</a>></td><td class="name" onclick="toggle('isCatchAll1')"><a name="isCatchAll1Anchor">isCatchAll</a></td><td></td></tr> +<tr><td colspan="4" class="doc" id="isCatchAll1"><pre>Matches a C++ catch statement that has a handler that catches any exception type. + +Example matches catch(...) (matcher = catchStmt(isCatchAll())) + try { + // ... + } catch(...) { + } +</pre></td></tr> + <tr><td>Matcher<<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXConstructExpr.html">CXXConstructExpr</a>></td><td class="name" onclick="toggle('argumentCountIs1')"><a name="argumentCountIs1Anchor">argumentCountIs</a></td><td>unsigned N</td></tr> <tr><td colspan="4" class="doc" id="argumentCountIs1"><pre>Checks that a call expression or a constructor call expression has diff --git a/docs/Makefile b/docs/Makefile index 96978d8..a409cf6 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -8,7 +8,6 @@ ##===----------------------------------------------------------------------===## CLANG_LEVEL := .. -DIRS := tools ifdef BUILD_FOR_WEBSITE PROJ_OBJ_DIR = . diff --git a/docs/ObjectiveCLiterals.rst b/docs/ObjectiveCLiterals.rst index 8907c1e..9fe7f66 100644 --- a/docs/ObjectiveCLiterals.rst +++ b/docs/ObjectiveCLiterals.rst @@ -119,8 +119,8 @@ Objective-C provides a new syntax for boxing C expressions: @( <expression> ) -Expressions of scalar (numeric, enumerated, BOOL) and C string pointer -types are supported: +Expressions of scalar (numeric, enumerated, BOOL), C string pointer +and some C structures (via NSValue) are supported: .. code-block:: objc @@ -136,6 +136,12 @@ types are supported: NSString *path = @(getenv("PATH")); // [NSString stringWithUTF8String:(getenv("PATH"))] NSArray *pathComponents = [path componentsSeparatedByString:@":"]; + // structs. + NSValue *center = @(view.center); // Point p = view.center; + // [NSValue valueWithBytes:&p objCType:@encode(Point)]; + NSValue *frame = @(view.frame); // Rect r = view.frame; + // [NSValue valueWithBytes:&r objCType:@encode(Rect)]; + Boxed Enums ----------- @@ -218,6 +224,42 @@ character data is valid. Passing ``NULL`` as the character pointer will raise an exception at runtime. When possible, the compiler will reject ``NULL`` character pointers used in boxed expressions. +Boxed C Structures +------------------ + +Boxed expressions support construction of NSValue objects. +It said that C structures can be used, the only requirement is: +structure should be marked with ``objc_boxable`` attribute. +To support older version of frameworks and/or third-party libraries +you may need to add the attribute via ``typedef``. + +.. code-block:: objc + + struct __attribute__((objc_boxable)) Point { + // ... + }; + + typedef struct __attribute__((objc_boxable)) _Size { + // ... + } Size; + + typedef struct _Rect { + // ... + } Rect; + + struct Point p; + NSValue *point = @(p); // ok + Size s; + NSValue *size = @(s); // ok + + Rect r; + NSValue *bad_rect = @(r); // error + + typedef struct __attribute__((objc_boxable)) _Rect Rect; + + NSValue *good_rect = @(r); // ok + + Container Literals ================== @@ -539,6 +581,22 @@ checks. Here are examples of their use: } #endif + #if __has_attribute(objc_boxable) + typedef struct __attribute__((objc_boxable)) _Rect Rect; + #endif + + #if __has_feature(objc_boxed_nsvalue_expressions) + CABasicAnimation animation = [CABasicAnimation animationWithKeyPath:@"position"]; + animation.fromValue = @(layer.position); + animation.toValue = @(newPosition); + [layer addAnimation:animation forKey:@"move"]; + #else + CABasicAnimation animation = [CABasicAnimation animationWithKeyPath:@"position"]; + animation.fromValue = [NSValue valueWithCGPoint:layer.position]; + animation.toValue = [NSValue valueWithCGPoint:newPosition]; + [layer addAnimation:animation forKey:@"move"]; + #endif + Code can use also ``__has_feature(objc_bool)`` to check for the availability of numeric literals support. This checks for the new ``__objc_yes / __objc_no`` keywords, which enable the use of diff --git a/docs/SafeStack.rst b/docs/SafeStack.rst index 5115d95..21e9b6c 100644 --- a/docs/SafeStack.rst +++ b/docs/SafeStack.rst @@ -15,14 +15,17 @@ the safe stack and the unsafe stack. The safe stack stores return addresses, register spills, and local variables that are always accessed in a safe way, while the unsafe stack stores everything else. This separation ensures that buffer overflows on the unsafe stack cannot be used to overwrite anything -on the safe stack, which includes return addresses. +on the safe stack. + +SafeStack is a part of the `Code-Pointer Integrity (CPI) Project +<http://dslab.epfl.ch/proj/cpi/>`_. Performance ----------- The performance overhead of the SafeStack instrumentation is less than 0.1% on average across a variety of benchmarks (see the `Code-Pointer Integrity -<http://dslab.epfl.ch/pubs/cpi.pdf>`_ paper for details). This is mainly +<http://dslab.epfl.ch/pubs/cpi.pdf>`__ paper for details). This is mainly because most small functions do not have any variables that require the unsafe stack and, hence, do not need unsafe stack frames to be created. The cost of creating unsafe stack frames for large functions is amortized by the cost of @@ -34,37 +37,6 @@ used through multiple stack frames. Moving such objects away from the safe stack increases the locality of frequently accessed values on the stack, such as register spills, return addresses, and small local variables. -Limitations ------------ - -SafeStack has not been subjected to a comprehensive security review, and there -exist known weaknesses, including but not limited to the following. - -In its current state, the separation of local variables provides protection -against stack buffer overflows, but the safe stack itself is not protected -from being corrupted through a pointer dereference. The Code-Pointer -Integrity paper describes two ways in which we may protect the safe stack: -hardware segmentation on the 32-bit x86 architecture or information hiding -on other architectures. - -Even with information hiding, the safe stack would merely be hidden -from attackers by being somewhere in the address space. Depending on the -application, the address could be predictable even on 64-bit address spaces -because not all the bits are addressable, multiple threads each have their -stack, the application could leak the safe stack address to memory via -``__builtin_frame_address``, bugs in the low-level runtime support etc. -Safe stack leaks could be mitigated by writing and deploying a static binary -analysis or a dynamic binary instrumentation based tool to find leaks. - -This approach doesn't prevent an attacker from "imbalancing" the safe -stack by say having just one call, and doing two rets (thereby returning -to an address that wasn't meant as a return address). This can be at least -partially mitigated by deploying SafeStack alongside a forward control-flow -integrity mechanism to ensure that calls are made using the correct calling -convention. Clang does not currently implement a comprehensive forward -control-flow integrity protection scheme; there exists one that protects -:doc:`virtual calls <ControlFlowIntegrity>` but not non-virtual indirect calls. - Compatibility ------------- @@ -83,21 +55,73 @@ work with SafeStack. One example is mark-and-sweep garbage collection implementations for C/C++ (e.g., Oilpan in chromium/blink), which must be changed to look for the live pointers on both safe and unsafe stacks. -SafeStack supports linking together modules that are compiled with and without -SafeStack, both statically and dynamically. One corner case that is not -supported is using ``dlopen()`` to load a dynamic library that uses SafeStack into -a program that is not compiled with SafeStack but uses threads. +SafeStack supports linking statically modules that are compiled with and +without SafeStack. An executable compiled with SafeStack can load dynamic +libraries that are not compiled with SafeStack. At the moment, compiling +dynamic libraries with SafeStack is not supported. Signal handlers that use ``sigaltstack()`` must not use the unsafe stack (see ``__attribute__((no_sanitize("safe-stack")))`` below). Programs that use APIs from ``ucontext.h`` are not supported yet. +Security +-------- + +SafeStack protects return addresses, spilled registers and local variables that +are always accessed in a safe way by separating them in a dedicated safe stack +region. The safe stack is automatically protected against stack-based buffer +overflows, since it is disjoint from the unsafe stack in memory, and it itself +is always accessed in a safe way. In the current implementation, the safe stack +is protected against arbitrary memory write vulnerabilities though +randomization and information hiding: the safe stack is allocated at a random +address and the instrumentation ensures that no pointers to the safe stack are +ever stored outside of the safe stack itself (see limitations below). + +Known security limitations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A complete protection against control-flow hijack attacks requires combining +SafeStack with another mechanism that enforces the integrity of code pointers +that are stored on the heap or the unsafe stack, such as `CPI +<http://dslab.epfl.ch/proj/cpi/>`_, or a forward-edge control flow integrity +mechanism that enforces correct calling conventions at indirect call sites, +such as `IFCC <http://research.google.com/pubs/archive/42808.pdf>`_ with arity +checks. Clang has control-flow integrity protection scheme for :doc:`C++ virtual +calls <ControlFlowIntegrity>`, but not non-virtual indirect calls. With +SafeStack alone, an attacker can overwrite a function pointer on the heap or +the unsafe stack and cause a program to call arbitrary location, which in turn +might enable stack pivoting and return-oriented programming. + +In its current implementation, SafeStack provides precise protection against +stack-based buffer overflows, but protection against arbitrary memory write +vulnerabilities is probabilistic and relies on randomization and information +hiding. The randomization is currently based on system-enforced ASLR and shares +its known security limitations. The safe stack pointer hiding is not perfect +yet either: system library functions such as ``swapcontext``, exception +handling mechanisms, intrinsics such as ``__builtin_frame_address``, or +low-level bugs in runtime support could leak the safe stack pointer. In the +future, such leaks could be detected by static or dynamic analysis tools and +prevented by adjusting such functions to either encrypt the stack pointer when +storing it in the heap (as already done e.g., by ``setjmp``/``longjmp`` +implementation in glibc), or store it in a safe region instead. + +The `CPI paper <http://dslab.epfl.ch/pubs/cpi.pdf>`_ describes two alternative, +stronger safe stack protection mechanisms, that rely on software fault +isolation, or hardware segmentation (as available on x86-32 and some x86-64 +CPUs). + +At the moment, SafeStack assumes that the compiler's implementation is correct. +This has not been verified except through manual code inspection, and could +always regress in the future. It's therefore desirable to have a separate +static or dynamic binary verification tool that would check the correctness of +the SafeStack instrumentation in final binaries. + Usage ===== -To enable SafeStack, just pass ``-fsanitize=safe-stack`` flag to both compile and link -command lines. +To enable SafeStack, just pass ``-fsanitize=safe-stack`` flag to both compile +and link command lines. Supported Platforms ------------------- @@ -129,10 +153,11 @@ function, even if enabled globally (see ``-fsanitize=safe-stack`` flag). This attribute may be required for functions that make assumptions about the exact layout of their stack frames. -Care should be taken when using this attribute. The return address is not -protected against stack buffer overflows, and it is easier to leak the -address of the safe stack to memory by taking the address of a local variable. - +All local variables in functions with this attribute will be stored on the safe +stack. The safe stack remains unprotected against memory errors when accessing +these variables, so extra care must be taken to manually ensure that all such +accesses are safe. Furthermore, the addresses of such local variables should +never be stored on the heap, as it would leak the location of the SafeStack. ``__builtin___get_unsafe_stack_ptr()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -149,15 +174,14 @@ current thread. Design ====== -Please refer to -`http://dslab.epfl.ch/proj/cpi/ <http://dslab.epfl.ch/proj/cpi/>`_ for more -information about the design of the SafeStack and its related technologies. - +Please refer to the `Code-Pointer Integrity <http://dslab.epfl.ch/proj/cpi/>`__ +project page for more information about the design of the SafeStack and its +related technologies. Publications ------------ -`Code-Pointer Integrity <http://dslab.epfl.ch/pubs/cpi.pdf>`_. +`Code-Pointer Integrity <http://dslab.epfl.ch/pubs/cpi.pdf>`__. Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song. USENIX Symposium on Operating Systems Design and Implementation (`OSDI <https://www.usenix.org/conference/osdi14>`_), Broomfield, CO, October 2014 diff --git a/docs/conf.py b/docs/conf.py index 9030c2c..b7ed23a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,7 +41,7 @@ master_doc = 'index' # General information about the project. project = u'Clang' -copyright = u'2007-2014, The Clang Team' +copyright = u'2007-2015, The Clang Team' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -212,10 +212,40 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'clang', u'Clang Documentation', - [u'The Clang Team'], 1) -] +man_pages = [] + +# Automatically derive the list of man pages from the contents of the command +# guide subdirectory. This was copied from llvm/docs/conf.py. +basedir = os.path.dirname(__file__) +man_page_authors = u'Maintained by the Clang / LLVM Team (<http://clang.llvm.org>)' +command_guide_subpath = 'CommandGuide' +command_guide_path = os.path.join(basedir, command_guide_subpath) +for name in os.listdir(command_guide_path): + # Ignore non-ReST files and the index page. + if not name.endswith('.rst') or name in ('index.rst',): + continue + + # Otherwise, automatically extract the description. + file_subpath = os.path.join(command_guide_subpath, name) + with open(os.path.join(command_guide_path, name)) as f: + title = f.readline().rstrip('\n') + header = f.readline().rstrip('\n') + + if len(header) != len(title): + print >>sys.stderr, ( + "error: invalid header in %r (does not match title)" % ( + file_subpath,)) + if ' - ' not in title: + print >>sys.stderr, ( + ("error: invalid title in %r " + "(expected '<name> - <description>')") % ( + file_subpath,)) + + # Split the name out of the title. + name,description = title.split(' - ', 1) + man_pages.append((file_subpath.replace('.rst',''), name, + description, man_page_authors, 1)) + # If true, show URL addresses after external links. #man_show_urls = False diff --git a/docs/index.rst b/docs/index.rst index dec2bc8..d50667d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -32,6 +32,7 @@ Using Clang as a Compiler SafeStack Modules MSVCCompatibility + CommandGuide/index FAQ Using Clang as a Library diff --git a/docs/tools/Makefile b/docs/tools/Makefile deleted file mode 100644 index 5521d6b..0000000 --- a/docs/tools/Makefile +++ /dev/null @@ -1,116 +0,0 @@ -##===- docs/tools/Makefile ---------------------------------*- Makefile -*-===## -# -# The LLVM Compiler Infrastructure -# -# This file is distributed under the University of Illinois Open Source -# License. See LICENSE.TXT for details. -# -##===----------------------------------------------------------------------===## - -ifdef BUILD_FOR_WEBSITE - -# FIXME: This was copied from the CommandGuide makefile. Figure out -# how to get this stuff on the website. - -# This special case is for keeping the CommandGuide on the LLVM web site -# up to date automatically as the documents are checked in. It must build -# the POD files to HTML only and keep them in the src directories. It must also -# build in an unconfigured tree, hence the ifdef. To use this, run -# make -s BUILD_FOR_WEBSITE=1 inside the cvs commit script. -SRC_DOC_DIR= -DST_HTML_DIR=html/ -DST_MAN_DIR=man/man1/ -DST_PS_DIR=ps/ -CLANG_VERSION := trunk - -# If we are in BUILD_FOR_WEBSITE mode, default to the all target. -all:: html man ps - -clean: - rm -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -# To create other directories, as needed, and timestamp their creation -%/.dir: - -mkdir $* > /dev/null - date > $@ - -else - -# Otherwise, if not in BUILD_FOR_WEBSITE mode, use the project info. -CLANG_LEVEL := ../.. -include $(CLANG_LEVEL)/Makefile - -CLANG_VERSION := $(word 3,$(shell grep "CLANG_VERSION " \ - $(PROJ_OBJ_DIR)/$(CLANG_LEVEL)/include/clang/Basic/Version.inc)) - -SRC_DOC_DIR=$(PROJ_SRC_DIR)/ -DST_HTML_DIR=$(PROJ_OBJ_DIR)/ -DST_MAN_DIR=$(PROJ_OBJ_DIR)/ -DST_PS_DIR=$(PROJ_OBJ_DIR)/ - -endif - - -POD := $(wildcard $(SRC_DOC_DIR)*.pod) -HTML := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_HTML_DIR)%.html, $(POD)) -MAN := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_MAN_DIR)%.1, $(POD)) -PS := $(patsubst $(SRC_DOC_DIR)%.pod, $(DST_PS_DIR)%.ps, $(POD)) - -ifdef ONLY_MAN_DOCS -INSTALL_TARGETS := install-man -else -INSTALL_TARGETS := install-html install-man install-ps -endif - -.SUFFIXES: -.SUFFIXES: .html .pod .1 .ps - -$(DST_HTML_DIR)%.html: %.pod $(DST_HTML_DIR)/.dir - pod2html --css=manpage.css --htmlroot=. \ - --podpath=. --infile=$< --outfile=$@ --title=$* - -$(DST_MAN_DIR)%.1: %.pod $(DST_MAN_DIR)/.dir - pod2man --release "clang $(CLANG_VERSION)" --center="Clang Tools Documentation" $< $@ - -$(DST_PS_DIR)%.ps: $(DST_MAN_DIR)%.1 $(DST_PS_DIR)/.dir - groff -Tps -man $< > $@ - - -html: $(HTML) -man: $(MAN) -ps: $(PS) - -EXTRA_DIST := $(POD) - -clean-local:: - $(Verb) $(RM) -f pod2htm*.*~~ $(HTML) $(MAN) $(PS) - -HTML_DIR := $(DESTDIR)$(PROJ_docsdir)/html/clang -MAN_DIR := $(DESTDIR)$(PROJ_mandir)/man1 -PS_DIR := $(DESTDIR)$(PROJ_docsdir)/ps - -install-html:: $(HTML) - $(Echo) Installing HTML Clang Tools Documentation - $(Verb) $(MKDIR) $(HTML_DIR) - $(Verb) $(DataInstall) $(HTML) $(HTML_DIR) - $(Verb) $(DataInstall) $(PROJ_SRC_DIR)/manpage.css $(HTML_DIR) - -install-man:: $(MAN) - $(Echo) Installing MAN Clang Tools Documentation - $(Verb) $(MKDIR) $(MAN_DIR) - $(Verb) $(DataInstall) $(MAN) $(MAN_DIR) - -install-ps:: $(PS) - $(Echo) Installing PS Clang Tools Documentation - $(Verb) $(MKDIR) $(PS_DIR) - $(Verb) $(DataInstall) $(PS) $(PS_DIR) - -install-local:: $(INSTALL_TARGETS) - -uninstall-local:: - $(Echo) Uninstalling Clang Tools Documentation - $(Verb) $(RM) -rf $(HTML_DIR) $(MAN_DIR) $(PS_DIR) - -printvars:: - $(Echo) "POD : " '$(POD)' - $(Echo) "HTML : " '$(HTML)' diff --git a/docs/tools/clang.pod b/docs/tools/clang.pod deleted file mode 100644 index 153f97b..0000000 --- a/docs/tools/clang.pod +++ /dev/null @@ -1,614 +0,0 @@ -=pod - -=head1 NAME - -clang - the Clang C, C++, and Objective-C compiler - -=head1 SYNOPSIS - -B<clang> [B<-c>|B<-S>|B<-E>] B<-std=>I<standard> B<-g> - [B<-O0>|B<-O1>|B<-O2>|B<-O3>|B<-Ofast>|B<-Os>|B<-Oz>|B<-O>|B<-O4>] - B<-W>I<warnings...> B<-pedantic> - B<-I>I<dir...> B<-L>I<dir...> - B<-D>I<macro[=defn]> - B<-f>I<feature-option...> - B<-m>I<machine-option...> - B<-o> I<output-file> - B<-stdlib=>I<library> - I<input-filenames> - -=head1 DESCRIPTION - -B<clang> is a C, C++, and Objective-C compiler which encompasses preprocessing, -parsing, optimization, code generation, assembly, and linking. Depending on -which high-level mode setting is passed, Clang will stop before doing a full -link. While Clang is highly integrated, it is important to understand the -stages of compilation, to understand how to invoke it. These stages are: - -=over - -=item B<Driver> - -The B<clang> executable is actually a small driver which controls the overall -execution of other tools such as the compiler, assembler and linker. Typically -you do not need to interact with the driver, but you transparently use it to run -the other tools. - -=item B<Preprocessing> - -This stage handles tokenization of the input source file, macro expansion, -#include expansion and handling of other preprocessor directives. The output of -this stage is typically called a ".i" (for C), ".ii" (for C++), ".mi" (for -Objective-C), or ".mii" (for Objective-C++) file. - -=item B<Parsing and Semantic Analysis> - -This stage parses the input file, translating preprocessor tokens into a parse -tree. Once in the form of a parse tree, it applies semantic analysis to compute -types for expressions as well and determine whether the code is well formed. This -stage is responsible for generating most of the compiler warnings as well as -parse errors. The output of this stage is an "Abstract Syntax Tree" (AST). - -=item B<Code Generation and Optimization> - -This stage translates an AST into low-level intermediate code (known as "LLVM -IR") and ultimately to machine code. This phase is responsible for optimizing -the generated code and handling target-specific code generation. The output of -this stage is typically called a ".s" file or "assembly" file. - -Clang also supports the use of an integrated assembler, in which the code -generator produces object files directly. This avoids the overhead of generating -the ".s" file and of calling the target assembler. - -=item B<Assembler> - -This stage runs the target assembler to translate the output of the compiler -into a target object file. The output of this stage is typically called a ".o" -file or "object" file. - -=item B<Linker> - -This stage runs the target linker to merge multiple object files into an -executable or dynamic library. The output of this stage is typically called an -"a.out", ".dylib" or ".so" file. - -=back - -The Clang compiler supports a large number of options to control each of these -stages. In addition to compilation of code, Clang also supports other tools: - -B<Clang Static Analyzer> - -The Clang Static Analyzer is a tool that scans source code to try to find bugs -through code analysis. This tool uses many parts of Clang and is built into the -same driver. Please see L<http://clang-analyzer.llvm.org> for more details -on how to use the static analyzer. - - -=head1 OPTIONS - -=head2 Stage Selection Options - -=over - -=item B<-E> - -Run the preprocessor stage. - -=item B<-fsyntax-only> - -Run the preprocessor, parser and type checking stages. - -=item B<-S> - -Run the previous stages as well as LLVM generation and optimization stages and -target-specific code generation, producing an assembly file. - -=item B<-c> - -Run all of the above, plus the assembler, generating a target ".o" object file. - -=item B<no stage selection option> - -If no stage selection option is specified, all stages above are run, and the -linker is run to combine the results into an executable or shared library. - -=back - - - -=head2 Language Selection and Mode Options - -=over - -=item B<-x> I<language> - -Treat subsequent input files as having type I<language>. - -=item B<-std>=I<language> - -Specify the language standard to compile for. - -=item B<-stdlib>=I<library> - -Specify the C++ standard library to use; supported options are libstdc++ and -libc++. - -=item B<-ansi> - -Same as B<-std=c89>. - -=item B<-ObjC++> - -Treat source input files as Objective-C++ inputs. - -=item B<-ObjC> - -Treat source input files as Objective-C inputs. - -=item B<-trigraphs> - -Enable trigraphs. - -=item B<-ffreestanding> - -Indicate that the file should be compiled for a freestanding, not a hosted, -environment. - -=item B<-fno-builtin> - -Disable special handling and optimizations of builtin functions like strlen and -malloc. - -=item B<-fmath-errno> - -Indicate that math functions should be treated as updating errno. - -=item B<-fpascal-strings> - -Enable support for Pascal-style strings with "\pfoo". - -=item B<-fms-extensions> - -Enable support for Microsoft extensions. - -=item B<-fmsc-version=> - -Set _MSC_VER. Defaults to 1300 on Windows. Not set otherwise. - -=item B<-fborland-extensions> - -Enable support for Borland extensions. - -=item B<-fwritable-strings> - -Make all string literals default to writable. This disables uniquing of -strings and other optimizations. - -=item B<-flax-vector-conversions> - -Allow loose type checking rules for implicit vector conversions. - -=item B<-fblocks> - -Enable the "Blocks" language feature. - -=item B<-fobjc-gc-only> - -Indicate that Objective-C code should be compiled in GC-only mode, which only -works when Objective-C Garbage Collection is enabled. - -=item B<-fobjc-gc> - -Indicate that Objective-C code should be compiled in hybrid-GC mode, which works -with both GC and non-GC mode. - -=item B<-fobjc-abi-version>=I<version> - -Select the Objective-C ABI version to use. Available versions are 1 (legacy -"fragile" ABI), 2 (non-fragile ABI 1), and 3 (non-fragile ABI 2). - -=item B<-fobjc-nonfragile-abi-version>=I<version> - -Select the Objective-C non-fragile ABI version to use by default. This will only -be used as the Objective-C ABI when the non-fragile ABI is enabled (either via --fobjc-nonfragile-abi, or because it is the platform default). - -=item B<-fobjc-nonfragile-abi> - -Enable use of the Objective-C non-fragile ABI. On platforms for which this is -the default ABI, it can be disabled with B<-fno-objc-nonfragile-abi>. - -=back - - - -=head2 Target Selection Options - -Clang fully supports cross compilation as an inherent part of its design. -Depending on how your version of Clang is configured, it may have support for -a number of cross compilers, or may only support a native target. - -=over - -=item B<-arch> I<architecture> - -Specify the architecture to build for. - -=item B<-mmacosx-version-min>=I<version> - -When building for Mac OS X, specify the minimum version supported by your -application. - -=item B<-miphoneos-version-min> - -When building for iPhone OS, specify the minimum version supported by your -application. - - -=item B<-march>=I<cpu> - -Specify that Clang should generate code for a specific processor family member -and later. For example, if you specify -march=i486, the compiler is allowed to -generate instructions that are valid on i486 and later processors, but which -may not exist on earlier ones. - -=back - - -=head2 Code Generation Options - -=over - -=item B<-O0> B<-O1> B<-O2> B<-O3> B<-Ofast> B<-Os> B<-Oz> B<-O> B<-O4> - -Specify which optimization level to use: - -=over - -=item B<-O0> - -Means "no optimization": this level compiles the fastest and -generates the most debuggable code. - -=item B<-O1> - -Somewhere between B<-O0> and B<-O2>. - -=item B<-O2> - -Moderate level of optimization which enables most optimizations. - -=item B<-O3> - -Like B<-O2>, except that it enables optimizations that take longer to perform -or that may generate larger code (in an attempt to make the program run faster). - -=item B<-Ofast> - -Enables all the optimizations from B<-O3> along with other aggressive -optimizations that may violate strict compliance with language standards. - -=item B<-Os> - -Like B<-O2> with extra optimizations to reduce code size. - -=item B<-Oz> - -Like B<-Os> (and thus B<-O2>), but reduces code size further. - -=item B<-O> - -Equivalent to B<-O2>. - -=item B<-O4> and higher - -Currently equivalent to B<-O3> - -=back - -=item B<-g> - -Generate debug information. Note that Clang debug information works best at -B<-O0>. - -=item B<-fstandalone-debug> B<-fno-standalone-debug> - -Clang supports a number of optimizations to reduce the size of debug -information in the binary. They work based on the assumption that the -debug type information can be spread out over multiple compilation -units. For instance, Clang will not emit type definitions for types -that are not needed by a module and could be replaced with a forward -declaration. Further, Clang will only emit type info for a dynamic -C++ class in the module that contains the vtable for the class. - -The B<-fstandalone-debug> option turns off these optimizations. This -is useful when working with 3rd-party libraries that don't come with -debug information. This is the default on Darwin. Note that Clang -will never emit type information for types that are not referenced at -all by the program. - -=item B<-fexceptions> - -Enable generation of unwind information. This allows exceptions to be thrown -through Clang compiled stack frames. This is on by default in x86-64. - -=item B<-ftrapv> - -Generate code to catch integer overflow errors. Signed integer overflow is -undefined in C. With this flag, extra code is generated to detect this and abort -when it happens. - - -=item B<-fvisibility> - -This flag sets the default visibility level. - -=item B<-fcommon> - -This flag specifies that variables without initializers get common linkage. It -can be disabled with B<-fno-common>. - -=item B<-ftls-model> - -Set the default thread-local storage (TLS) model to use for thread-local -variables. Valid values are: "global-dynamic", "local-dynamic", "initial-exec" -and "local-exec". The default is "global-dynamic". The default model can be -overridden with the tls_model attribute. The compiler will try to choose a more -efficient model if possible. - -=item B<-flto> B<-emit-llvm> - -Generate output files in LLVM formats, suitable for link time optimization. When -used with B<-S> this generates LLVM intermediate language assembly files, -otherwise this generates LLVM bitcode format object files (which may be passed -to the linker depending on the stage selection options). - -=cut - -##=item B<-fnext-runtime> B<-fobjc-nonfragile-abi> B<-fgnu-runtime> -##These options specify which Objective-C runtime the code generator should -##target. FIXME: we don't want people poking these generally. - -=pod - -=back - - -=head2 Driver Options - -=over - -=item B<-###> - -Print (but do not run) the commands to run for this compilation. - -=item B<--help> - -Display available options. - -=item B<-Qunused-arguments> - -Do not emit any warnings for unused driver arguments. - -=item B<-Wa,>I<args> - -Pass the comma separated arguments in I<args> to the assembler. - -=item B<-Wl,>I<args> - -Pass the comma separated arguments in I<args> to the linker. - -=item B<-Wp,>I<args> - -Pass the comma separated arguments in I<args> to the preprocessor. - -=item B<-Xanalyzer> I<arg> - -Pass I<arg> to the static analyzer. - -=item B<-Xassembler> I<arg> - -Pass I<arg> to the assembler. - -=item B<-Xlinker> I<arg> - -Pass I<arg> to the linker. - -=item B<-Xpreprocessor> I<arg> - -Pass I<arg> to the preprocessor. - -=item B<-o> I<file> - -Write output to I<file>. - -=item B<-print-file-name>=I<file> - -Print the full library path of I<file>. - -=item B<-print-libgcc-file-name> - -Print the library path for "libgcc.a". - -=item B<-print-prog-name>=I<name> - -Print the full program path of I<name>. - -=item B<-print-search-dirs> - -Print the paths used for finding libraries and programs. - -=item B<-save-temps> - -Save intermediate compilation results. - -=item B<-integrated-as> B<-no-integrated-as> - -Used to enable and disable, respectively, the use of the integrated -assembler. Whether the integrated assembler is on by default is target -dependent. - -=item B<-time> - -Time individual commands. - -=item B<-ftime-report> - -Print timing summary of each stage of compilation. - -=item B<-v> - -Show commands to run and use verbose output. - -=back - - -=head2 Diagnostics Options - -=over - -=item B<-fshow-column> -B<-fshow-source-location> -B<-fcaret-diagnostics> -B<-fdiagnostics-fixit-info> -B<-fdiagnostics-parseable-fixits> -B<-fdiagnostics-print-source-range-info> -B<-fprint-source-range-info> -B<-fdiagnostics-show-option> -B<-fmessage-length> - -These options control how Clang prints out information about diagnostics (errors -and warnings). Please see the Clang User's Manual for more information. - -=back - - -=head2 Preprocessor Options - -=over - -=item B<-D>I<macroname=value> - -Adds an implicit #define into the predefines buffer which is read before the -source file is preprocessed. - -=item B<-U>I<macroname> - -Adds an implicit #undef into the predefines buffer which is read before the -source file is preprocessed. - -=item B<-include> I<filename> - -Adds an implicit #include into the predefines buffer which is read before the -source file is preprocessed. - -=item B<-I>I<directory> - -Add the specified directory to the search path for include files. - -=item B<-F>I<directory> - -Add the specified directory to the search path for framework include files. - -=item B<-nostdinc> - -Do not search the standard system directories or compiler builtin directories -for include files. - -=item B<-nostdlibinc> - -Do not search the standard system directories for include files, but do search -compiler builtin include directories. - -=item B<-nobuiltininc> - -Do not search clang's builtin directory for include files. - -=cut - -## TODO, but do we really want people using this stuff? -#=item B<-idirafter>I<directory> -#=item B<-iquote>I<directory> -#=item B<-isystem>I<directory> -#=item B<-iprefix>I<directory> -#=item B<-iwithprefix>I<directory> -#=item B<-iwithprefixbefore>I<directory> -#=item B<-isysroot> - -=pod - - -=back - - - -=cut - -### TODO someday. -#=head2 Warning Control Options -#=over -#=back -#=head2 Code Generation and Optimization Options -#=over -#=back -#=head2 Assembler Options -#=over -#=back -#=head2 Linker Options -#=over -#=back -#=head2 Static Analyzer Options -#=over -#=back - -=pod - - -=head1 ENVIRONMENT - -=over - -=item B<TMPDIR>, B<TEMP>, B<TMP> - -These environment variables are checked, in order, for the location to -write temporary files used during the compilation process. - -=item B<CPATH> - -If this environment variable is present, it is treated as a delimited -list of paths to be added to the default system include path list. The -delimiter is the platform dependent delimiter, as used in the I<PATH> -environment variable. - -Empty components in the environment variable are ignored. - -=item B<C_INCLUDE_PATH>, B<OBJC_INCLUDE_PATH>, B<CPLUS_INCLUDE_PATH>, -B<OBJCPLUS_INCLUDE_PATH> - -These environment variables specify additional paths, as for CPATH, -which are only used when processing the appropriate language. - -=item B<MACOSX_DEPLOYMENT_TARGET> - -If -mmacosx-version-min is unspecified, the default deployment target -is read from this environment variable. This option only affects Darwin -targets. - -=back - -=head1 BUGS - -To report bugs, please visit L<http://llvm.org/bugs/>. Most bug reports should -include preprocessed source files (use the B<-E> option) and the full output of -the compiler, along with information to reproduce. - -=head1 SEE ALSO - - as(1), ld(1) - -=head1 AUTHOR - -Maintained by the Clang / LLVM Team (L<http://clang.llvm.org>). - -=cut diff --git a/docs/tools/manpage.css b/docs/tools/manpage.css deleted file mode 100644 index c922564..0000000 --- a/docs/tools/manpage.css +++ /dev/null @@ -1,256 +0,0 @@ -/* Based on http://www.perldoc.com/css/perldoc.css */ - -@import url("../llvm.css"); - -body { font-family: Arial,Helvetica; } - -blockquote { margin: 10pt; } - -h1, a { color: #336699; } - - -/*** Top menu style ****/ -.mmenuon { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #ff6600; font-size: 10pt; -} -.mmenuoff { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #ffffff; font-size: 10pt; -} -.cpyright { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #ffffff; font-size: xx-small; -} -.cpyrightText { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #ffffff; font-size: xx-small; -} -.sections { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 11pt; -} -.dsections { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 12pt; -} -.slink { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; - color: #000000; font-size: 9pt; -} - -.slink2 { font-family: Arial,Helvetica; text-decoration: none; color: #336699; } - -.maintitle { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 18pt; -} -.dblArrow { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: small; -} -.menuSec { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: small; -} - -.newstext { - font-family: Arial,Helvetica; font-size: small; -} - -.linkmenu { - font-family: Arial,Helvetica; color: #000000; font-weight: bold; - text-decoration: none; -} - -P { - font-family: Arial,Helvetica; -} - -PRE { - font-size: 10pt; -} -.quote { - font-family: Times; text-decoration: none; - color: #000000; font-size: 9pt; font-style: italic; -} -.smstd { font-family: Arial,Helvetica; color: #000000; font-size: x-small; } -.std { font-family: Arial,Helvetica; color: #000000; } -.meerkatTitle { - font-family: sans-serif; font-size: x-small; color: black; } - -.meerkatDescription { font-family: sans-serif; font-size: 10pt; color: black } -.meerkatCategory { - font-family: sans-serif; font-size: 9pt; font-weight: bold; font-style: italic; - color: brown; } -.meerkatChannel { - font-family: sans-serif; font-size: 9pt; font-style: italic; color: brown; } -.meerkatDate { font-family: sans-serif; font-size: xx-small; color: #336699; } - -.tocTitle { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #333333; font-size: 10pt; -} - -.toc-item { - font-family: Arial,Helvetica; font-weight: bold; - color: #336699; font-size: 10pt; text-decoration: underline; -} - -.perlVersion { - font-family: Arial,Helvetica; font-weight: bold; - color: #336699; font-size: 10pt; text-decoration: none; -} - -.podTitle { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #000000; -} - -.docTitle { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #000000; font-size: 10pt; -} -.dotDot { - font-family: Arial,Helvetica; font-weight: bold; - color: #000000; font-size: 9pt; -} - -.docSec { - font-family: Arial,Helvetica; font-weight: normal; - color: #333333; font-size: 9pt; -} -.docVersion { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 10pt; -} - -.docSecs-on { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; - color: #ff0000; font-size: 10pt; -} -.docSecs-off { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; - color: #333333; font-size: 10pt; -} - -h2 { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: medium; -} -h1 { - font-family: Verdana,Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: large; -} - -DL { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: none; - color: #333333; font-size: 10pt; -} - -UL > LI > A { - font-family: Arial,Helvetica; font-weight: bold; - color: #336699; font-size: 10pt; -} - -.moduleInfo { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #333333; font-size: 11pt; -} - -.moduleInfoSec { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 10pt; -} - -.moduleInfoVal { - font-family: Arial,Helvetica; font-weight: normal; text-decoration: underline; - color: #000000; font-size: 10pt; -} - -.cpanNavTitle { - font-family: Arial,Helvetica; font-weight: bold; - color: #ffffff; font-size: 10pt; -} -.cpanNavLetter { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #333333; font-size: 9pt; -} -.cpanCat { - font-family: Arial,Helvetica; font-weight: bold; text-decoration: none; - color: #336699; font-size: 9pt; -} - -.bttndrkblue-bkgd-top { - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgtop.gif); -} -.bttndrkblue-bkgd-left { - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgleft.gif); -} -.bttndrkblue-bkgd { - padding-top: 0px; - padding-bottom: 0px; - margin-bottom: 0px; - margin-top: 0px; - background-repeat: no-repeat; - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgmiddle.gif); - vertical-align: top; -} -.bttndrkblue-bkgd-right { - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgright.gif); -} -.bttndrkblue-bkgd-bottom { - background-color: #225688; - background-image: url(/global/mvc_objects/images/bttndrkblue_bgbottom.gif); -} -.bttndrkblue-text a { - color: #ffffff; - text-decoration: none; -} -a.bttndrkblue-text:hover { - color: #ffDD3C; - text-decoration: none; -} -.bg-ltblue { - background-color: #f0f5fa; -} - -.border-left-b { - background: #f0f5fa url(/i/corner-leftline.gif) repeat-y; -} - -.border-right-b { - background: #f0f5fa url(/i/corner-rightline.gif) repeat-y; -} - -.border-top-b { - background: #f0f5fa url(/i/corner-topline.gif) repeat-x; -} - -.border-bottom-b { - background: #f0f5fa url(/i/corner-botline.gif) repeat-x; -} - -.border-right-w { - background: #ffffff url(/i/corner-rightline.gif) repeat-y; -} - -.border-top-w { - background: #ffffff url(/i/corner-topline.gif) repeat-x; -} - -.border-bottom-w { - background: #ffffff url(/i/corner-botline.gif) repeat-x; -} - -.bg-white { - background-color: #ffffff; -} - -.border-left-w { - background: #ffffff url(/i/corner-leftline.gif) repeat-y; -} |
