1 LINTDUMP(1ONBLD)              illumos Build Tools             LINTDUMP(1ONBLD)
   2 
   3 
   4 
   5 lintdump - dump the contents of one or more lint objects
   6 
   7 SYNOPSIS
   8        lintdump [-i] [-p 1|2|3] [-r] lintobj [ lintobj ... ]
   9 
  10 DESCRIPTION
  11        The lintdump utility dumps the contents of one or more lint objects.
  12        This is chiefly useful when trying to understand the cause of
  13        unexpected or obtuse lint warnings (see EXAMPLES), but can also be used
  14        to find differences between lint objects across builds or releases, or
  15        to debug problems in lint itself.
  16 
  17        A lint object is a binary file (typically suffixed with ".ln")
  18        constructed from a C source file via the "-c" option to lint(1).
  19        Multiple lint objects may be combined into a lint library object
  20        (typically prefixed with "llib-l" and suffixed with ".ln") using the
  21        "-o" option to lint.  (As a convenience, lint "-o" allows a lint
  22        library object to be built directly from C source files). The lintdump
  23        utility is capable of dumping both traditional lint objects and lint
  24        library objects.
  25 
  26        The format of a lint object is unstable and subject to change at any
  27        time, but its current structure is summarized here in order to aid in
  28        understanding the current output of lintdump.  A lint object consists
  29        of one or more lint modules (one per C source file).  Each lint module
  30        consists of a header and four sections, called PASS1, PASS2, PASS3, and
  31        STRINGS.  Generally speaking, PASS1 contains definitions, PASS2
  32        contains declarations, and PASS3 contains information on whether or how
  33        functions or variables are used.  The STRINGS section holds the strings
  34        for printf(3C)/scanf(3C) checking.
  35 
  36        Each PASS section consists of a sequence of binary records of assorted
  37        types.  The sequence of records is further partitioned by FILE records,
  38        which indicate the source or header file that is responsible for the
  39        records that follow.  The remaining record types provide lint with
  40        information about the functions, variables, and structures defined or
  41        used by the object.
  42 
  43 OPTIONS
  44        -i        Do not output structure tag IDs (see EXAMPLES).
  45 
  46        -p 1|2|3  Just output the PASS1, PASS2, or PASS3 section.
  47 
  48        -r        Output records using relative paths (see EXAMPLES).
  49 
  50 OUTPUT
  51        The contents of each specified lintobj is dumped in command-line order.
  52        For each lintobj, lintdump outputs a single line beginning with
  53        "LINTOBJ:" that provides its name.  For each lint module within that
  54        object, lintdump outputs a single line beginning with "LINTMOD:" that
  55        provides its module ID, the size of its PASS1, PASS2, PASS3, STRING
  56        sections, and its total size, in that order.
  57 
  58        Next, unless the -p option is used, the contents of the PASS1, PASS2,
  59        and PASS3 sections are dumped, in order.  Before each section is
  60        dumped, lintdump outputs a single line beginning with "SECTION:" that
  61        provides the name and size of the section.  For each section, lintdump
  62        outputs each record in order.  The display format of each record
  63        depends on its type:
  64 
  65        FILE RECORDS
  66            Each FILE record is displayed on a single line beginning with
  67            "FILE:".  Note that FILE records are often found in pairs, the
  68            first providing the absolute path to the file.  FILE records
  69            containing absolute paths are omitted if -r is used.  Other record
  70            types following a FILE record are indented to show their
  71            relationship to the FILE record.
  72 
  73        FUNCTION AND VARIABLE RECORDS
  74            Each function or variable record is displayed on a single line
  75            using an extended version of the format used in The C Programming
  76            Language, Second Edition.  In particular, properties contained in
  77            the record that cannot be conveyed in C are displayed in angle
  78            brackets following definition or declaration; a full list of these
  79            and their meanings are given below in RECORD PROPERTIES.  In
  80            addition, note that some structures or unions may only be known by
  81            a numeric ID, and thus output as "struct <tag ID>".    This ID can be
  82            used to pair the structure with its definition via structure
  83            records.  If -i is used, then "struct <anon>" is printed instead.
  84 
  85        STRUCTURE AND UNION RECORDS
  86            Each structure or union record is displayed using an extended
  87            version of the standard multi-line format used in The C Programming
  88            Language, Second Edition.  In particular, to facilitate problem
  89            analysis, unless -i is used, each structure or union definition
  90            includes a numeric ID enclosed in angle-brackets, such as "struct
  91            FILE <tag 1298> {".
  92 
  93        To illustrate each of the common record formats, suppose the following
  94        lint library is built:
  95 
  96        $ cat > liba.c
  97        /* LINTLIBRARY */
  98        /* PROTOLIB1 */
  99        int af(int);
 100        struct as {
 101                char as_name[32];
 102                int  as_flag;
 103        } as;
 104        $ lint -oa liba.c
 105 
 106        Then lintdump will produce the following output:
 107 
 108        LINTOBJ: llib-la.ln
 109        LINTMOD: 6484: 268+24+130+9 = 431 bytes
 110        SECTION: PASS1: 268 bytes
 111           FILE: /home/meem/hacks/liba.c
 112           FILE: liba.c
 113                 extern int af(int);
 114                 struct as as;
 115                 struct as <tag 98> {
 116                     char as_name[];
 117                     int as_flag;
 118                 };
 119        SECTION: PASS2: 24 bytes
 120        SECTION: PASS3: 130 bytes
 121           FILE: /home/meem/hacks/liba.c
 122           FILE: liba.c
 123                 int af(void) <returns value>;
 124 
 125 RECORD PROPERTIES
 126        As discussed in OUTPUT, some records are displayed using an extended
 127        format to convey information that cannot be expressed in C.  The
 128        following extended information may be displayed:
 129 
 130        <PRINTFLIKEn>
 131            Indicates to lint that argument n to the variable-argument function
 132            is a format string in printf(3C) format, which enhances lint's
 133            argument checking.
 134 
 135        <SCANFLIKEn>
 136            Indicates to lint that argument n to the variable-argument function
 137            is a format string in scanf(3C) format, which enhances lint's
 138            argument checking.
 139 
 140        <definition>
 141            Indicates to lint that this record represents the definition of the
 142            given variable or function (rather than a declaration).
 143 
 144        <use: side-effects context>
 145            Indicates to lint that the associated function is called in a
 146            context that suggests it has side effects.
 147 
 148        <use: return value context>
 149            Indicates to lint that the associated function is called in a
 150            context where its return value is used.
 151 
 152        <use: unspecified context>
 153            Indicates to lint that the associated function is used in an
 154            unspecified manner.
 155 
 156        <returns      value>
 157            Indicates to lint that the function returns a value.
 158 
 159 EXAMPLES
 160        One common problem is that lint does not always provide sufficient
 161        information to understand the reason for a type mismatch.  For
 162        instance, sometimes lint will confusingly report a type mismatch
 163        between apparently-identical types:
 164 
 165        $ lint msghdr.c -lsocket
 166        function argument ( number ) used inconsistently
 167            recvmsg (arg 2) llib-lsocket:socket.h(437) struct msghdr * ::
 168                                         msghdr.c(12)  struct msghdr *
 169 
 170        By using lintdump, we can pinpoint the problem by examining both
 171        definitions for struct msghdr:
 172 
 173        $ lintdump /lib/llib-lsocket.ln
 174           [ ... ]
 175           FILE: llib-lsocket:socket.h
 176                 struct msghdr <tag 4532> {
 177                     void *msg_name;
 178                     unsigned int msg_namelen;
 179                     struct iovec *msg_iov;
 180                     int msg_iovlen;
 181                     char *msg_accrights;
 182                     int msg_accrightslen;
 183                 };
 184 
 185        $ lint -omsghdr msghdr.c -lsocket
 186        $ lintdump llib-lmsghdr.ln
 187           [ ... ]
 188           FILE: socket.h
 189                 struct msghdr <tag 1315> {
 190                     void *msg_name;
 191                     unsigned int msg_namelen;
 192                     struct iovec *msg_iov;
 193                     int msg_iovlen;
 194                     void *msg_control;
 195                     unsigned int msg_controllen;
 196                     int msg_flags;
 197                 };
 198 
 199        Looking at <sys/socket.h>, the problem becomes apparent:   the structure
 200        changes depending on compile-time options, which clearly differ between
 201        the application and the library:
 202 
 203        struct msghdr {
 204                void            *msg_name;
 205                socklen_t       msg_namelen;
 206                struct iovec    *msg_iov;
 207                int             msg_iovlen;
 208 
 209        #if defined(_XPG4_2) || defined(_KERNEL)
 210                void            *msg_control;
 211                socklen_t       msg_controllen;
 212                int             msg_flags;
 213        #else
 214                caddr_t         msg_accrights;
 215                int             msg_accrightslen;
 216        #endif  /* defined(_XPG4_2) || defined(_KERNEL) */
 217        };
 218 
 219        Another use of lintdump is to compare two versions of a lint object to
 220        see whether anything of significance has changed.  For instance,
 221        lintdump can be used to understand why a lint library is different
 222        between a project gate and a patch gate, and thus to determine whether
 223        the library will need to be redelivered in the patch including the
 224        project:
 225 
 226        $ PATCHROOT=/ws/on10-patch/proto/root_i386
 227        $ diff llib-lkstat.ln $PATCHROOT/lib/llib-lkstat.ln
 228        Binary files llib-lkstat.ln and
 229                     /ws/on10-patch/proto/root_i386/lib/llib-lkstat.ln differ
 230        $ lintdump -ir llib-lkstat.ln > /tmp/proj-kstat.out
 231        $ lintdump -ir $PATCHROOT/lib/llib-lkstat.ln > /tmp/patch-kstat.out
 232 
 233        $ diff /tmp/patch-kstat.out /tmp/proj-kstat.out
 234        1,2c1,2
 235        < LINTMOD: 3675:      4995+26812+1045+9 = 32861 bytes
 236        < SECTION: PASS1: 4995 bytes
 237        ---
 238        > LINTMOD: 39982: 5144+27302+1057+9 = 33512 bytes
 239        > SECTION: PASS1: 5144 bytes
 240        19c19
 241        <           unsigned char _file;
 242        ---
 243        >           unsigned char _magic;
 244        22a23,24
 245        >           unsigned int __extendedfd;
 246        >           unsigned int __xf_nocheck;
 247        [ ... ]
 248 
 249        Note that -r option removes spurious differences that would otherwise
 250        arise from different absolute paths to the same source file, and the -i
 251        option removes spurious differences due to ID generation inside lint.
 252 
 253 SEE ALSO
 254        lint(1), printf(3C), scanf(3C)
 255 
 256 NOTES
 257        This utility is provided as an interim solution until a stable utility
 258        can be bundled with Sun Studio.  As such, any use of this utility in
 259        scripts or embedded inside programs should be done with knowledge that
 260        subsequent changes will be required in order to transition to the
 261        stable solution.
 262 
 263        The lint object file format does not have a way to represent bitfields.
 264        As such, bitfield size information cannot be displayed by lintdump.
 265 
 266 
 267 
 268                                 March 28, 2008                LINTDUMP(1ONBLD)