1#
2# This file and its contents are supplied under the terms of the
3# Common Development and Distribution License ("CDDL"), version 1.0.
4# You may only use this file in accordance with the terms of version
5# 1.0 of the CDDL.
6#
7# A full copy of the text of the CDDL should have accompanied this
8# source.  A copy of the CDDL is also available via the Internet at
9# http://www.illumos.org/license/CDDL.
10#
11
12#
13# Copyright 2015 Garrett D'Amore <garrett@damore.org>
14# Copyright 2016 Joyent, Inc.
15#
16
17The configuration files in this directory are structured using the
18syntax defined in the ../README file.  They make use of the compilation
19environments declared in ../compilation.cfg, and are processed by the
20symbols test.
21
22We have organized the files by header file, that is the tests for symbols
23declared in a header file (e.g. <unistd.h> appear in a file based on that
24header file's name (e.g. unistd_h.cfg.)  This is purely for convenience.
25
26Within these various declarations, we have the following field types:
27
28<envs>    This is a list of compilation environments where the symbol
29          should be legal.  To indicate that the symbol must not be legal
30          an environment group can be prefixed with "-".  For example,
31          "SUS+ -SUSv4+" indicates a symbol that is legal in all SUS
32	  environments up to SUSv3, and was removed in SUSv4 and subsequent
33          versions of SUS.  As you can see, we can list multiple environments
34          or environment groups, and we can add or remove to previous groups
35          with subsequent ones.
36
37<name>    This is a symbol name.  It follows the rules for C symbol names.
38
39<header>  This is a header file, for example, unistd.h.  Conventionally,
40          the header files used should match the file where the test is
41          declared.
42
43<type>    This is a C type.  Function types can be declared without their
44          names, e.g. "void (*)(int)".  Structures (e.g. "struct stat") and
45          pointer types (e.g. "pthead_t *") are legal as well.
46
47Here are the types of declarations in these files:
48
49type | <name> | <header> | <envs>
50
51    Tests for a C type with <name>.  The test verifies that a variable with
52    this type can be declared when the <header> is included.
53
54value | <name> | <type> | <header> | <envs>
55
56    Tests for a value named <name>, of type <type>.  The test attempts to
57    assign the given value to a scratch variable declared with the given
58    type.  The value can be a macro or other C symbol.
59
60define | <name> | <value> | <header> | <envs>
61
62    Tests for a definition named <name>.  The test verifies that the
63    pre-processor sees the definition.  If the <value> entry is not
64    empty then the check also verifies that there is strict equality
65    between the pre-processor value and it.  Only strict equality checks
66    are supported at this time.
67
68func | <name> | <type> | <type> [; <type> ]... | <header> | <envs>
69
70    Tests whether a function <name>, returning the first <type>, and
71    taking arguments of following <type> values, is declared.  Note that
72    the argument types are separated by semicolons.  For varargs style
73    functions, leave out the ... part.  For function declarations
74    that have no declared arguments, either void can specified, or
75    the type list can be omitted.
76
77Examples:
78
79    type | size_t | sys/types.h | ALL
80    value | NULL | void * | stdlib.h | ALL
81    define | thread_local | | threads.h | -ALL +C11
82    define | __alignas_is_defined | 1 | threads.h | -ALL +C11
83    func | strnlen | int | const char *; int | string.h | ALL
84