PTCH IFF Format Copyright (c) 1989 Lattice, Inc. All Rights Reserved. Copyright (c) 1990 SAS Institute Inc. All Rights Reserved SAS Campus Drive Cary NC 27513 Address all questions to John Toebes Bix: JTOEBES Plink: JTOEBES This document describes the PTCH IFF format as implemented by the SAS/C LCOMPARE and LPATCH programs. We are making the actual format of this Patch file public so that others may benefit from its use. SUMMARY ------- The PTCH IFF format provides a standard method of describing patches for arbitrary binary (and of course ASCII) data. The patch format allows for descriptive text to be included as part of the patch as well as checksumming information to ensure the validity of the patch. The PTCH form consists of 5 standard chunks (described in detail below). VERS describes the version of the Patch program necessary to apply the patch. INPF indicates a default input file to be used as well as the attributes of that file to prevent patching the wrong file. OUTF describes a default output file along with the attributes of the created file to ensure that the patch applied correctly. PMSG descibes a string to be output to the terminal when running the patch program. This chunk is optional and may occur more than once. PSEQ Contains the actual patch instructions. Only the PMSG chunk is optional. All other chunks are required. VERS ---- The VERS chunk contains information describing the revision of the patch program necessary to apply the patch. The chunk consists of 4 bytes followed by a text string. The first two bytes are reserved for future expansion and must always contain 0. The third byte is the major version of the patcher program with the minor version being stored in the next (4th) byte. At present time, this spec refers to the 3.0 format. The string following these 4 bytes is simple ASCII text that may be used to more completely describe the version. There is no restriction on the format of this text. If it is an odd number of bytes long, it must be padded with a single trailing null byte to bring the chunk to an even size. INPF ---- The INPF chunk describes the input file to be patched. It consists of two long words followed by an ASCII string. The first long word is the checksum of the input file computed by adding all bytes in the file and throwing away any overflow beyond 32 bits. The second longword is the length of the input file in bytes. Future version of the patch program may chose to implement this verification through CRC or other more sophisticated methods. If this is done, the VERS chunk should be updated to reflect this. The ASCII string indicates the default name of the file to be patched. As with the VERS string, an odd length string is padded out with a single null byte to bring the chunk to an even size. OUTF ---- The OUTF chunk is identical in form to the INPF chunk. In this case, the version information is used to verify that the patch was applied correctly as a final check. PMSG ---- The PMSG chunk is a hook to allow a developer to print out special information about a patch being applied. More than one PMSG chunk may be present in the file; each will be printed out in turn. This can be useful when you wish to print out a message before the patch is applied and another after the lengthy patch process has completed. If the message is an odd length, it is padded out with a single null byte to bring the chunk to an even size. PSEQ ---- The PSEQ chunk contains the actual patch data to be applied. This data consists of a series of single byte commands to indicate the action to take. Commands that are in lower case are followed by a single byte length. Upper case commands are followed by 2 or 4 bytes of data based on the command. However, they can be treated as 2 byte lengths with the 'C' and 'D' commands treated special. All lengths are treated as unsigned. With the 3.0 version, the following commands are supported: 'C' <4 byte Checksum of original> - Simple additive checksum of the original program. This information is somewhat obsolete in that is contained in the INPF chunk; hence the LCOMPARE program does not output it. 'D' <4 byte checksum of final program> - Simple additive checksum of the generated program. Like the 'C' command, this is obsoleted by the presence of the information in the OUTF chunk and is not output by the LCOMPARE program. 'S' <2 byte length> - Skip bytes from original file. 's' <1 byte length> - Skip bytes from original file. Skips over bytes in the input file and in effect does a forward seek. If more than 64K bytes need to be skipped, multiple S commands need to be used. The output file is not modified. 'U' <2 byte length> - Use bytes directly 'u' <1 byte length> - Use bytes directly Copies bytes directly from the original input file at the current position to the end of the output file. If more than 64K bytes of data is to be copied, multiple U commands can be used. 'I' <2 byte length> - Insert bytes 'i' <1 byte length> - Insert bytes Inserts the given data into the output file. The data bytes are taken directly from the patch file for the specified length. The input file seek position is unaffected. Insertions of more than 64K must be done with multiple 'I' commands. 'R' <2 byte length> - Replace bytes 'r' <1 byte length> - Replace bytes Replaces the specified number of bytes in the output file by first skipping the specified length in the input file (as with the S command) followed by inserting the same number of bytes in the output file using the data directly following in the patch file. Replaced areas of more than 64K must be done with multiple R commands. 0 A filler byte used to pad out the patch data to an even length. Any zero bytes are to be ignored. All other commands are considered illegal and if encountered are to abort the patch. The choice of 2 bytes for most lengths is based on the observation that few patches exceed 64K. For these, it is felt that the extra overhead of a single byte is well worth the noticable savings for most other patches. If this is felt to be a burden, additional commands could be quickly added to remedy the situation. AVAILABILITY ------------ The LPATCH program as provided by SAS Institute is freely redistributable.