Geoff Chappell - Software Analyst
The DESCRIPTION statement is supported only when building an export file for a VxD. It is otherwise ignored after a warning (LNK4017).
DESCRIPTION is a single-definition statement. It is a fatal error (LNK1118) if the statement is empty. The DESCRIPTION tag must be followed by a space or tab. There may then be any amount of white space, including none, before the definition. The ordinary syntax is:
DESCRIPTION text
such that text truly is all the text on the remainder of the line (including trailing white space). A variation is:
DESCRIPTION 'text'
Here, the first character of the argument is a single-quote, and text begins with the next character and continues up to but not including the last single-quote on the remainder of the line. It is a fatal error (LNK1118) if there is not another single-quote on the line. Characters beyond the last single-quote are irrelevant and are ignored without complaint.
The DESCRIPTION statement translates to a /comment option for the export-file command line. The form is:
/COMMENT:"text"
where text is from the DESCRIPTION statement, as described above, but at most the first 117 bytes of it.
The need to limit the amount of text that carries to the command-line option arises because LIB prepares the command-line option in a buffer that is set up on the stack as a local variable, whose size is therefore set in the source code and not adjustable at run time. The buffer’s size is 128 bytes. The /comment switch, its colon and a pair of double-quotes total 11 bytes. This would leave 117 bytes for the text.
However, a null byte must yet terminate the string that LIB prepares in this buffer. If the text in the DESCRIPTION statement does run to 117 bytes or more, then although LIB copies only the first 117 bytes to the stack as text for the /comment switch, the null terminator is one byte too many for the buffer on the stack.
It happens that in the version inspected for these notes, namely 7.00.9466, the buffer in which LIB prepares the /comment switch is placed highest among the relevant procedure’s local variables. Ordinarily, the one-byte overrun would therefore corrupt this procedure’s return address. However, the procedure has been compiled with the Buffer Security Check enabled, to detect overruns that would overwrite the return address. This gives a ready demonstration both of the coding error and of the efficacy of the Buffer Security Check.
Begin with a module definition file, here named TEST.DEF, containing just the following as one (long) line:
DESCRIPTION 12345678901234567890...1234567
where the ellipsis stands for as many repetitions of 1234567890 as needed for the text argument to count to 117. Running
lib /def:test.def /machine:x86 /vxd
triggers the buffer overrun. Repeat with text reduced by one byte, and there is no buffer overrun.
Note that text with white space need not be enclosed in quotes of either sort when given in the DESCRIPTION statement. All the white space gets enclosed in double-quotes when carried to the /comment option. This is true even of trailing white space, such as occurs if text without single-quotes is followed by white space and then by a comment. (Remember that by this stage of parsing, LIB treats a comment as having ended the line.)
Enclosure between single-quotes in the DESCRIPTION statement is supported explicitly and has the merit of marking clearly which characters are intended as the text for the /comment option. Double-quotes in the text are problematic. They carry into the text for the /comment option in the export file, but the enclosure in double-quotes for the option inverts the pairing of the double-quotes in the definition.