From 84b805cae32080a3642c0ee936e8e461122b6d7b Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Mon, 16 Sep 2019 11:49:45 -0700 Subject: [PATCH 01/15] Automatically port Reflection.PortableExecutable.PE* APIs --- .../PEDirectoriesBuilder.xml | 141 +++++++++- .../PEHeader.xml | 235 ++++++++++++---- .../PEHeaderBuilder.xml | 3 +- .../PEHeaders.xml | 74 +++-- .../PEMemoryBlock.xml | 18 +- .../PEReader.xml | 258 ++++++++++++++---- .../PEStreamOptions.xml | 32 ++- 7 files changed, 601 insertions(+), 160 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml b/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml index af9abbbcc2b..599c18079ea 100644 --- a/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml +++ b/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml @@ -1,3 +1,4 @@ + @@ -86,7 +87,15 @@ To be added. To be added. - To be added. + + + @@ -110,7 +119,15 @@ To be added. To be added. - To be added. + + + @@ -134,7 +151,15 @@ To be added. To be added. - To be added. + + + @@ -158,7 +183,15 @@ To be added. To be added. - To be added. + + + @@ -182,7 +215,15 @@ To be added. To be added. - To be added. + + + @@ -206,7 +247,15 @@ To be added. To be added. - To be added. + + + @@ -230,7 +279,15 @@ To be added. To be added. - To be added. + + + @@ -254,7 +311,15 @@ To be added. To be added. - To be added. + + + @@ -278,7 +343,15 @@ To be added. To be added. - To be added. + + + @@ -302,7 +375,15 @@ To be added. To be added. - To be added. + + + @@ -326,7 +407,15 @@ To be added. To be added. - To be added. + + + @@ -350,7 +439,15 @@ To be added. To be added. - To be added. + + + @@ -374,7 +471,15 @@ To be added. To be added. - To be added. + + + @@ -398,7 +503,15 @@ To be added. To be added. - To be added. + + + diff --git a/xml/System.Reflection.PortableExecutable/PEHeader.xml b/xml/System.Reflection.PortableExecutable/PEHeader.xml index 8914a7275fb..cead79f1b7b 100644 --- a/xml/System.Reflection.PortableExecutable/PEHeader.xml +++ b/xml/System.Reflection.PortableExecutable/PEHeader.xml @@ -44,9 +44,17 @@ System.Int32 - To be added. + The address of the entry point relative to the image base when the PE file is loaded into memory. To be added. - To be added. + + + @@ -70,7 +78,7 @@ System.Int32 - To be added. + The address that is relative to the image base of the beginning-of-code section when it is loaded into memory. To be added. To be added. @@ -96,7 +104,7 @@ System.Int32 - To be added. + The address that is relative to the image base of the beginning-of-data section when it is loaded into memory. To be added. To be added. @@ -124,7 +132,15 @@ To be added. To be added. - To be added. + + + @@ -150,7 +166,15 @@ To be added. To be added. - To be added. + + + @@ -174,9 +198,19 @@ System.Reflection.PortableExecutable.DirectoryEntry - To be added. + The Certificate Table entry points to a table of attribute certificates. To be added. - To be added. + + + @@ -200,7 +234,7 @@ System.UInt32 - To be added. + The image file checksum. To be added. To be added. @@ -228,7 +262,15 @@ To be added. To be added. - To be added. + + + @@ -254,7 +296,15 @@ To be added. To be added. - To be added. + + + @@ -280,7 +330,15 @@ To be added. To be added. - To be added. + + + @@ -306,7 +364,15 @@ To be added. To be added. - To be added. + + + @@ -358,7 +424,15 @@ To be added. To be added. - To be added. + + + @@ -384,7 +458,15 @@ To be added. To be added. - To be added. + + + @@ -408,9 +490,16 @@ System.Int32 - To be added. - To be added. - To be added. + The alignment factor (in bytes) that is used to align the raw data of sections in the image file. + A power of 2 between 512 and 64K, inclusive. The default is 512. + + is less than the architecture's page size, then must match . + + ]]> @@ -436,7 +525,15 @@ To be added. To be added. - To be added. + + + @@ -460,8 +557,8 @@ System.UInt64 - To be added. - To be added. + The preferred address of the first byte of image when loaded into memory. + A multiple of 64K. To be added. @@ -488,7 +585,15 @@ To be added. To be added. - To be added. + + + @@ -514,7 +619,15 @@ To be added. To be added. - To be added. + + + @@ -540,7 +653,15 @@ To be added. To be added. - To be added. + + + @@ -564,7 +685,7 @@ System.Reflection.PortableExecutable.PEMagic - To be added. + Identifies the format of the image file. To be added. To be added. @@ -590,7 +711,7 @@ System.UInt16 - To be added. + The major version number of the image. To be added. To be added. @@ -616,7 +737,7 @@ System.Byte - To be added. + The linker major version number. To be added. To be added. @@ -642,7 +763,7 @@ System.UInt16 - To be added. + The major version number of the required operating system. To be added. To be added. @@ -668,7 +789,7 @@ System.UInt16 - To be added. + The major version number of the subsystem. To be added. To be added. @@ -694,7 +815,7 @@ System.UInt16 - To be added. + The minor version number of the image. To be added. To be added. @@ -720,7 +841,7 @@ System.Byte - To be added. + The linker minor version number. To be added. To be added. @@ -746,7 +867,7 @@ System.UInt16 - To be added. + The minor version number of the required operating system. To be added. To be added. @@ -772,7 +893,7 @@ System.UInt16 - To be added. + The minor version number of the subsystem. To be added. To be added. @@ -798,7 +919,7 @@ System.Int32 - To be added. + The number of data-directory entries in the remainder of the . Each describes a location and size. To be added. To be added. @@ -826,7 +947,15 @@ To be added. To be added. - To be added. + + + @@ -850,8 +979,8 @@ System.Int32 - To be added. - To be added. + The alignment (in bytes) of sections when they are loaded into memory. + A number greater than or equal to . The default is the page size for the architecture. To be added. @@ -876,7 +1005,7 @@ System.Int32 - To be added. + The size of the code (text) section, or the sum of all code sections if there are multiple sections. To be added. To be added. @@ -902,7 +1031,7 @@ System.Int32 - To be added. + The combined size of an MS DOS stub, PE header, and section headers rounded up to a multiple of FileAlignment. To be added. To be added. @@ -928,7 +1057,7 @@ System.UInt64 - To be added. + The size of the local heap space to commit. To be added. To be added. @@ -954,7 +1083,7 @@ System.UInt64 - To be added. + The size of the local heap space to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. To be added. To be added. @@ -980,8 +1109,8 @@ System.Int32 - To be added. - To be added. + The size (in bytes) of the image, including all headers, as the image is loaded in memory. + A multiple of . To be added. @@ -1006,7 +1135,7 @@ System.Int32 - To be added. + The size of the initialized data section, or the sum of all such sections if there are multiple data sections. To be added. To be added. @@ -1032,7 +1161,7 @@ System.UInt64 - To be added. + The size of the stack to commit. To be added. To be added. @@ -1058,7 +1187,7 @@ System.UInt64 - To be added. + The size of the stack to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. To be added. To be added. @@ -1084,7 +1213,7 @@ System.Int32 - To be added. + The size of the uninitialized data section (BSS), or the sum of all such sections if there are multiple BSS sections. To be added. To be added. @@ -1110,7 +1239,7 @@ System.Reflection.PortableExecutable.Subsystem - To be added. + The subsystem that is required to run this image. To be added. To be added. @@ -1138,7 +1267,15 @@ To be added. To be added. - To be added. + + + diff --git a/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml b/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml index cb0ef1953f6..4d0636191f3 100644 --- a/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml +++ b/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml @@ -75,8 +75,9 @@ To be added. To be added. To be added. - To be added. + Creates PE header builder. To be added. + is not power of 2 between 512 and 64K, or not power of 2 or it's less than . diff --git a/xml/System.Reflection.PortableExecutable/PEHeaders.xml b/xml/System.Reflection.PortableExecutable/PEHeaders.xml index 2aea8949902..adea1a9a0ab 100644 --- a/xml/System.Reflection.PortableExecutable/PEHeaders.xml +++ b/xml/System.Reflection.PortableExecutable/PEHeaders.xml @@ -19,7 +19,7 @@ - To be added. + An object used to read PE (Portable Executable) and COFF (Common Object File Format) headers from a stream. To be added. @@ -44,9 +44,13 @@ - To be added. - To be added. + A stream containing PE image starting at the stream's current position and ending at the end of the stream. + Reads the PE headers from the current location in the stream. To be added. + The data read from the stream has an invalid format. + Error reading from the stream. + The stream does not support seek operations. + is . @@ -71,10 +75,15 @@ - To be added. - To be added. - To be added. + A stream containing PE image of the given size starting at its current position. + THe size of the PE image. + Reads the PE headers from the current location in the stream. To be added. + The data read from the stream has an invalid format. + Error reading from the stream. + The stream does not support seek operations. + is . + The size is negative or extends past the end of the stream. @@ -98,11 +107,16 @@ - To be added. - To be added. - To be added. - To be added. + The stream containing PE image of the given size starting at its current position. + The size of the PE image. + if the PE image has been loaded into memory by the OS loader. + Reads the PE headers from the current location in the stream. To be added. + The data read from the stream has invalid format. + Error reading from the stream. + The stream does not support seek operations. + is . + The size is negative or extends past the end of the stream. @@ -126,7 +140,7 @@ System.Reflection.PortableExecutable.CoffHeader - To be added. + Gets the COFF header of the image. To be added. To be added. @@ -152,7 +166,7 @@ System.Int32 - To be added. + Gets the byte offset from the start of the PE image to the start of the COFF header. To be added. To be added. @@ -178,7 +192,7 @@ System.Reflection.PortableExecutable.CorHeader - To be added. + Gets the CLI header or if the image does not have one. To be added. To be added. @@ -204,7 +218,7 @@ System.Int32 - To be added. + Gets the byte offset from the start of the image to the COR header or -1 if the image does not have one. To be added. To be added. @@ -233,9 +247,9 @@ - To be added. - To be added. - To be added. + The specified relative virtual address to search. + Searches sections of the PE image for the one that contains specified Relative Virtual Address. + Index of the section that contains , or -1 if there is none. To be added. @@ -260,7 +274,7 @@ System.Boolean - To be added. + Determines if the image is Coff only. To be added. To be added. @@ -286,7 +300,7 @@ System.Boolean - To be added. + Determines if the image represents a Windows console application. To be added. To be added. @@ -312,7 +326,7 @@ System.Boolean - To be added. + Determines if the image represents a dynamically linked library. To be added. To be added. @@ -338,7 +352,7 @@ System.Boolean - To be added. + Determines if the image represents an executable. To be added. To be added. @@ -364,7 +378,7 @@ System.Int32 - To be added. + Gets the size of the CLI metadata, 0 if the image does not contain metadata. To be added. To be added. @@ -390,7 +404,7 @@ System.Int32 - To be added. + Gets the offset (in bytes) from the start of the PE image to the start of the CLI metadata or -1 if the image does not contain metadata. To be added. To be added. @@ -416,7 +430,7 @@ System.Reflection.PortableExecutable.PEHeader - To be added. + Gets the PE header of the image or if the image is COFF only. To be added. To be added. @@ -442,7 +456,7 @@ System.Int32 - To be added. + Gets the byte offset from the start of the image. To be added. To be added. @@ -468,7 +482,7 @@ System.Collections.Immutable.ImmutableArray<System.Reflection.PortableExecutable.SectionHeader> - To be added. + Gets the PE section headers. To be added. To be added. @@ -498,10 +512,10 @@ - To be added. - To be added. - To be added. - To be added. + PE directory entry. + Offset from the start of the image to the given directory data. + Gets the offset (in bytes) from the start of the image to the given directory data. + if the directory data is found, otherwise. To be added. diff --git a/xml/System.Reflection.PortableExecutable/PEMemoryBlock.xml b/xml/System.Reflection.PortableExecutable/PEMemoryBlock.xml index fc2d2766034..2ef4d9ea37b 100644 --- a/xml/System.Reflection.PortableExecutable/PEMemoryBlock.xml +++ b/xml/System.Reflection.PortableExecutable/PEMemoryBlock.xml @@ -50,8 +50,8 @@ - To be added. - To be added. + Reads the content of the entire block into an array. + An immutable array of bytes. To be added. @@ -80,9 +80,10 @@ To be added. To be added. - To be added. - To be added. + Reads the content of a part of the block into an array. + An immutable array of bytes. To be added. + Specified range is not contained within the block. @@ -105,7 +106,7 @@ - To be added. + Creates for a blob spanning the entire block. To be added. To be added. @@ -135,9 +136,10 @@ To be added. To be added. - To be added. + Creates for a blob spanning a part of the block. To be added. To be added. + Specified range is not contained within the block. @@ -161,7 +163,7 @@ System.Int32 - To be added. + The length of the block. To be added. To be added. @@ -186,7 +188,7 @@ System.Byte* - To be added. + Pointer to the first byte of the block. To be added. To be added. diff --git a/xml/System.Reflection.PortableExecutable/PEReader.xml b/xml/System.Reflection.PortableExecutable/PEReader.xml index aa02b829396..78e7f183d35 100644 --- a/xml/System.Reflection.PortableExecutable/PEReader.xml +++ b/xml/System.Reflection.PortableExecutable/PEReader.xml @@ -23,8 +23,16 @@ - To be added. - To be added. + Portable Executable format reader. + + ). + + ]]> + @@ -48,9 +56,18 @@ - To be added. - To be added. - To be added. + An immutable array of bytes representing the PE image. + Creates a Portable Executable reader over a PE image stored in a byte array. + + + + ]]> + + is . @@ -74,9 +91,18 @@ - To be added. - To be added. - To be added. + PE image stream. + Creates a Portable Executable reader over a PE image stored in a stream. + + upon successful validation of constructor arguments. It will be disposed by the and the caller must not manipulate it. + + ]]> + + is . @@ -100,10 +126,24 @@ - To be added. - To be added. - To be added. - To be added. + Pointer to the start of the PE image. + The size of the PE image. + Creates a Portable Executable reader over a PE image stored in memory. + + . + +The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the . + +The content of the image is not read during the construction of the + + ]]> + + is . + is negative. @@ -128,10 +168,26 @@ - To be added. - To be added. - To be added. - To be added. + PE image stream. + Options specifying how sections of the PE image are read from the stream. + Creates a Portable Executable reader over a PE image stored in a stream beginning at its current position and ending at the end of the stream. + + is specified, ownership of the stream is transferred to the upon successful argument validation. It will be disposed by the and the caller must not manipulate it. + +Unless or is specified no data is read from the stream during the construction of the . Furthermore, the stream must not be manipulated by caller while the is alive and undisposed. + +If or , the will have read all of the data requested during construction. As such, if is also specified, the caller retains full ownership of the stream and is assured that it will not be manipulated by the after construction. + + ]]> + + is . + has an invalid value. + Error reading from the stream (only when prefetching data). + is specified and the PE headers of the image are invalid. @@ -154,11 +210,25 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + A pointer to the start of the PE image. + The size of the PE image. + if the PE image has been loaded into memory by the OS loader. + Creates a Portable Executable reader over a PE image stored in memory. + + . + +The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the . + +The content of the image is not read during the construction of the + + ]]> + + is . + is negative. @@ -184,11 +254,26 @@ - To be added. - To be added. - To be added. - To be added. - To be added. + PE image stream. + Options specifying how sections of the PE image are read from the stream. + PE image size. + Creates a Portable Executable reader over a PE image of the given size beginning at the stream's current position. + + is specified, ownership of the stream is transferred to the upon successful argument validation. It will be disposed by the and the caller must not manipulate it. + +Unless or is specified no data is read from the stream during the construction of the . Furthermore, the stream must not be manipulated by caller while the is alive and undisposed. + +If or , the will have read all of the data requested during construction. As such, if is also specified, the caller retains full ownership of the stream and is assured that it will not be manipulated by the after construction. + + ]]> + + Size is negative or extends past the end of the stream. + Error reading from the stream (only when prefetching data). + is specified and the PE headers of the image are invalid. @@ -216,8 +301,18 @@ - To be added. - To be added. + Disposes all memory allocated by the reader. + + [!IMPORTANT] +> can be called multiple times, but not in parallel. +> It is not safe to call in parallel with any other operation on the or reading from s retrieved from the reader. + + ]]> + @@ -242,9 +337,10 @@ - To be added. + Gets a pointer to and size of the PE image if available (). To be added. To be added. + The entire PE image is not available. @@ -269,9 +365,12 @@ - To be added. + Loads PE section that contains CLI metadata. To be added. To be added. + The PE image doesn't contain metadata ( returns false). + The PE headers contain invalid data. + IO error while reading from the underlying stream. @@ -298,10 +397,14 @@ - To be added. - To be added. - To be added. + Relative Virtual Address of the data to read. + Loads PE section that contains the specified into memory and returns a memory block that starts at and ends at the end of the containing section. + An empty block if doesn't represent a location in any of the PE sections of this PE image. To be added. + The PE headers contain invalid data. + IO error while reading from the underlying stream. + PE image not available. + is negative. @@ -326,10 +429,12 @@ - To be added. - To be added. - To be added. + Name of the section. + Loads PE section of the specified name into memory and returns a memory block that spans the section. + An empty block if no section of the given exists in this PE image. To be added. + is . + PE image not available. @@ -353,9 +458,11 @@ System.Boolean - To be added. + Returns if the PE image contains CLI metadata. To be added. To be added. + The PE headers contain invalid data. + Error reading from the underlying stream. @@ -379,9 +486,17 @@ System.Boolean - To be added. + Return if the reader can access the entire PE image. To be added. - To be added. + + is constructed from a stream and only part of it is prefetched into memory. + + ]]> + @@ -403,7 +518,7 @@ System.Boolean - To be added. + if the PE image has been loaded into memory by the OS loader. To be added. To be added. @@ -429,9 +544,11 @@ System.Reflection.PortableExecutable.PEHeaders - To be added. + Gets the PE headers. To be added. To be added. + The headers contain invalid data. + Error reading from the stream. @@ -458,9 +575,13 @@ To be added. - To be added. + Reads the data pointed to by the specified Debug Directory entry and interprets them as CodeView. To be added. To be added. + is not a CodeView entry. + Bad format of the data. + IO error while reading from the underlying stream. + PE image not available. @@ -484,9 +605,12 @@ - To be added. + Reads all Debug Directory table entries. To be added. To be added. + Bad format of the entry. + IO error while reading from the underlying stream. + PE image not available. @@ -512,9 +636,12 @@ To be added. - To be added. - To be added. + Reads the data pointed to by the specified Debug Directory entry and interprets them as Embedded Portable PDB blob. + Provider of a metadata reader reading Portable PDB image. To be added. + is not a entry. + Bad format of the data. + PE image not available. @@ -538,9 +665,13 @@ To be added. - To be added. + Reads the data pointed to by the specified Debug Directory entry and interprets them as PDB Checksum entry. To be added. To be added. + is not a PDB Checksum entry. + Bad format of the data. + IO error while reading from the underlying stream. + PE image not available. @@ -568,13 +699,34 @@ - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The path to the PE image. The path is used to locate the PDB file located in the directory containing the PE file. + If specified, called to open a for a given file path. The provider is expected to either return a readable and seekable , or if the target file doesn't exist or should be ignored for some reason. The provider shall throw if it fails to open the file due to an unexpected IO error. + If successful, a new instance of to be used to read the Portable PDB,. + If successful and the PDB is found in a file, the path to the file. Returns if the PDB is embedded in the PE image itself. + Opens a Portable PDB associated with this PE image. + if the PE image has a PDB associated with it and the PDB has been successfully opened. + + + + or is . + The stream returned from doesn't support read and seek operations. + No matching PDB file is found due to an error: The PE image or the PDB is invalid. + No matching PDB file is found due to an error: An IO error occurred while reading the PE image or the PDB. diff --git a/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml b/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml index 97f25dced95..c72c633876f 100644 --- a/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml +++ b/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml @@ -49,7 +49,7 @@ 0 - To be added. + By default the stream is disposed when is disposed and sections of the PE image are read lazily. @@ -72,7 +72,7 @@ 8 - To be added. + Indicates that the underlying PE image has been loaded into memory by the OS loader. @@ -97,7 +97,7 @@ 1 - To be added. + Keep the stream open when the is disposed. @@ -122,7 +122,16 @@ 4 - To be added. + Reads the entire image into memory right away. + + closes the stream automatically by the time the constructor returns unless is specified. + + ]]> + @@ -147,7 +156,20 @@ 2 - To be added. + Reads metadata section into memory right away. + + is thrown by the ). + +The underlying file may be closed and even deleted after is constructed. + + closes the stream automatically by the time the constructor returns unless is specified. + + ]]> + From 239c0d02af85638ffc47796db7d533af23d67001 Mon Sep 17 00:00:00 2001 From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> Date: Mon, 16 Sep 2019 12:00:58 -0700 Subject: [PATCH 02/15] remove top line --- .../PEDirectoriesBuilder.xml | 1 - 1 file changed, 1 deletion(-) diff --git a/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml b/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml index 599c18079ea..f5fd876e60e 100644 --- a/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml +++ b/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml @@ -1,4 +1,3 @@ - From bec32b579ebbc2aa90c43d646a2cf883b8205ca5 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 25 Sep 2019 16:23:38 -0700 Subject: [PATCH 03/15] Update PEMemoryBlock.xml --- .../PEMemoryBlock.xml | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEMemoryBlock.xml b/xml/System.Reflection.PortableExecutable/PEMemoryBlock.xml index 2ef4d9ea37b..14be5983d2c 100644 --- a/xml/System.Reflection.PortableExecutable/PEMemoryBlock.xml +++ b/xml/System.Reflection.PortableExecutable/PEMemoryBlock.xml @@ -50,8 +50,8 @@ - Reads the content of the entire block into an array. - An immutable array of bytes. + Reads the contents of the entire block into an array. + An immutable byte array. To be added. @@ -78,12 +78,12 @@ - To be added. - To be added. - Reads the content of a part of the block into an array. + The starting position in the block. + The number of bytes to read. + Reads the contents of a part of the block into an array. An immutable array of bytes. To be added. - Specified range is not contained within the block. + The specified range is not contained within the block. @@ -106,8 +106,8 @@ - Creates for a blob spanning the entire block. - To be added. + Creates a for a blob spanning the entire block. + A reader for a blob spanning the entire block. To be added. @@ -134,12 +134,12 @@ - To be added. - To be added. - Creates for a blob spanning a part of the block. - To be added. + The starting position in the block. + The number of bytes in the portion of the block. + Creates a for a blob spanning a part of the block. + A reader for a blob spanning a portion of the block. To be added. - Specified range is not contained within the block. + The specified range is not contained within the block. @@ -163,8 +163,8 @@ System.Int32 - The length of the block. - To be added. + Gets the length of the block. + The length of the block. To be added. @@ -188,8 +188,8 @@ System.Byte* - Pointer to the first byte of the block. - To be added. + Gets a pointer to the first byte of the block. + A pointer to the first byte of the block. To be added. From 7fa6d075d97a1291e058121b94f2841cab0a9488 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 26 Sep 2019 13:27:48 -0700 Subject: [PATCH 04/15] In-place edits. --- .../PEReader.xml | 76 +++++++++---------- 1 file changed, 37 insertions(+), 39 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEReader.xml b/xml/System.Reflection.PortableExecutable/PEReader.xml index 78e7f183d35..dea302d527b 100644 --- a/xml/System.Reflection.PortableExecutable/PEReader.xml +++ b/xml/System.Reflection.PortableExecutable/PEReader.xml @@ -397,13 +397,13 @@ If - Relative Virtual Address of the data to read. - Loads PE section that contains the specified into memory and returns a memory block that starts at and ends at the end of the containing section. - An empty block if doesn't represent a location in any of the PE sections of this PE image. + The Relative Virtual Address of the data to read. + Loads the PE section that contains the specified relative virtual address into memory and returns a memory block that starts at that address and ends at the end of the containing section. + A memory block that starats at and ends at the end of the containing section, or an empty block if doesn't represent a location in any of the PE sections of this PE image. To be added. The PE headers contain invalid data. - IO error while reading from the underlying stream. - PE image not available. + An IO error occurred while reading from the underlying stream. + The PE image is not available. is negative. @@ -429,12 +429,12 @@ If - Name of the section. - Loads PE section of the specified name into memory and returns a memory block that spans the section. - An empty block if no section of the given exists in this PE image. + The name of the section. + Loads the PE section with the specified name into memory and returns a memory block that spans the section. + A memory block that spans the section, or an empty block if no section of the given exists in this PE image. To be added. is . - PE image not available. + The PE image is not available. @@ -458,8 +458,8 @@ If System.Boolean - Returns if the PE image contains CLI metadata. - To be added. + Returns a value that indicates if the PE image contains CLI metadata. + if the PE image contains CLI metadata; otherwise, . To be added. The PE headers contain invalid data. Error reading from the underlying stream. @@ -486,14 +486,14 @@ If System.Boolean - Return if the reader can access the entire PE image. - To be added. + Returns a value that indicates if the reader can access the entire PE image. + if the reader can access the entire PE image; otherwise, . is constructed from a stream and only part of it is prefetched into memory. +The property returns `false` if the is constructed from a stream and only part of it is prefetched into memory. ]]> @@ -518,8 +518,8 @@ Returns `false` if the is c System.Boolean - if the PE image has been loaded into memory by the OS loader. - To be added. + Returns a value that indicates if the PE image has been loaded into memory by the OS loader. + if the PE image has been loaded into memory by the OS loader; otherwise, . To be added. @@ -545,7 +545,7 @@ Returns `false` if the is c Gets the PE headers. - To be added. + The PE headers for this PE image. To be added. The headers contain invalid data. Error reading from the stream. @@ -575,13 +575,13 @@ Returns `false` if the is c To be added. - Reads the data pointed to by the specified Debug Directory entry and interprets them as CodeView. + Reads the data pointed to by the specified Debug Directory entry and interprets it as CodeView. To be added. To be added. is not a CodeView entry. Bad format of the data. IO error while reading from the underlying stream. - PE image not available. + The PE image is not available. @@ -606,11 +606,11 @@ Returns `false` if the is c Reads all Debug Directory table entries. - To be added. + An array of Debug Directory table entries. To be added. Bad format of the entry. IO error while reading from the underlying stream. - PE image not available. + The PE image is not available. @@ -635,9 +635,9 @@ Returns `false` if the is c - To be added. - Reads the data pointed to by the specified Debug Directory entry and interprets them as Embedded Portable PDB blob. - Provider of a metadata reader reading Portable PDB image. + The Debug Directory entry whose data is to be read. + Reads the data pointed to by the specified Debug Directory entry and interprets it as an Embedded Portable PDB blob. + The provider of a metadata reader for reading a Portable PDB image. To be added. is not a entry. Bad format of the data. @@ -664,14 +664,14 @@ Returns `false` if the is c - To be added. - Reads the data pointed to by the specified Debug Directory entry and interprets them as PDB Checksum entry. - To be added. + The Debug Directory entry whose data is to be read. + Reads the data pointed to by the specified Debug Directory entry and interprets it as a PDB Checksum entry. + The PDB Checksum entry. To be added. is not a PDB Checksum entry. Bad format of the data. IO error while reading from the underlying stream. - PE image not available. + The PE image is not available. @@ -700,24 +700,22 @@ Returns `false` if the is c The path to the PE image. The path is used to locate the PDB file located in the directory containing the PE file. - If specified, called to open a for a given file path. The provider is expected to either return a readable and seekable , or if the target file doesn't exist or should be ignored for some reason. The provider shall throw if it fails to open the file due to an unexpected IO error. + If specified, called to open a for a given file path. The provider is expected to either return a readable and seekable , or if the target file doesn't exist or should be ignored for some reason. The provider should throw if it fails to open the file due to an unexpected IO error. If successful, a new instance of to be used to read the Portable PDB,. - If successful and the PDB is found in a file, the path to the file. Returns if the PDB is embedded in the PE image itself. + If successful and the PDB is found in a file, the path to the file, or if the PDB is embedded in the PE image itself. Opens a Portable PDB associated with this PE image. - if the PE image has a PDB associated with it and the PDB has been successfully opened. + if the PE image has a PDB associated with it and the PDB has been successfully opened; otherwise, . or is . The stream returned from doesn't support read and seek operations. - No matching PDB file is found due to an error: The PE image or the PDB is invalid. - No matching PDB file is found due to an error: An IO error occurred while reading the PE image or the PDB. + No matching PDB file was found due to an error: The PE image or the PDB is invalid. + No matching PDB file was found due to an error: An IO error occurred while reading the PE image or the PDB. From 573ab80a83fb8a1a9db8dc5862a81540fd32a25e Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 26 Sep 2019 13:37:49 -0700 Subject: [PATCH 05/15] Edited PEStreamOptions directly --- .../PEStreamOptions.xml | 32 +++---------------- 1 file changed, 5 insertions(+), 27 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml b/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml index c72c633876f..25ed42913ef 100644 --- a/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml +++ b/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml @@ -23,7 +23,7 @@ - To be added. + Provides options that specify how sections of a PE image are read from a stream. To be added. @@ -49,7 +49,7 @@ 0 - By default the stream is disposed when is disposed and sections of the PE image are read lazily. + By default, the stream is disposed when the is disposed, and sections of the PE image are read lazily. @@ -97,7 +97,7 @@ 1 - Keep the stream open when the is disposed. + Keeps the stream open when the is disposed. @@ -122,16 +122,7 @@ 4 - Reads the entire image into memory right away. - - closes the stream automatically by the time the constructor returns unless is specified. - - ]]> - + Reads the entire image into memory right away. closes the stream automatically by the time the constructor returns unless is specified. @@ -156,20 +147,7 @@ 2 - Reads metadata section into memory right away. - - is thrown by the ). - -The underlying file may be closed and even deleted after is constructed. - - closes the stream automatically by the time the constructor returns unless is specified. - - ]]> - + Reads the metadata section into memory right away.Reading from other sections of the file is not allowed ( is thrown by the ). closes the stream automatically by the time the constructor returns unless is specified. The underlying file may be closed and even deleted after is constructed. From 74211072314d40687437ea324752ee85ff4fe9c9 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 26 Sep 2019 14:02:31 -0700 Subject: [PATCH 06/15] Revised property descriptions. --- xml/System.Reflection.PortableExecutable/PEReader.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEReader.xml b/xml/System.Reflection.PortableExecutable/PEReader.xml index dea302d527b..313967a7d4c 100644 --- a/xml/System.Reflection.PortableExecutable/PEReader.xml +++ b/xml/System.Reflection.PortableExecutable/PEReader.xml @@ -458,7 +458,7 @@ If System.Boolean - Returns a value that indicates if the PE image contains CLI metadata. + Gets a value that indicates if the PE image contains CLI metadata. if the PE image contains CLI metadata; otherwise, . To be added. The PE headers contain invalid data. @@ -486,7 +486,7 @@ If System.Boolean - Returns a value that indicates if the reader can access the entire PE image. + Gets a value that indicates if the reader can access the entire PE image. if the reader can access the entire PE image; otherwise, . System.Boolean - Returns a value that indicates if the PE image has been loaded into memory by the OS loader. + Gets a value that indicates if the PE image has been loaded into memory by the OS loader. if the PE image has been loaded into memory by the OS loader; otherwise, . To be added. From 8d302cb3c41dd866f28e756a32ae23b5a4e27a72 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 26 Sep 2019 14:39:51 -0700 Subject: [PATCH 07/15] Add summary and value. --- .../PEDirectoriesBuilder.xml | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml b/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml index 599c18079ea..c6613278a87 100644 --- a/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml +++ b/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml @@ -18,7 +18,7 @@ - To be added. + Builds PE directories. To be added. @@ -38,7 +38,7 @@ - To be added. + Initializes an instance of the class. To be added. @@ -61,8 +61,8 @@ System.Int32 - To be added. - To be added. + The entry point address. + An integer representing the entry point address. To be added. @@ -85,8 +85,8 @@ System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The base relocation table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The bound import image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The copyright/architecture image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The COM descriptortable image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The debug table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The delay import table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The exception table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The export table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The global pointer table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The import address table (IAT) image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The import table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The load configuration table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The resource table image directory entry. + A directory entry instance. System.Reflection.PortableExecutable.DirectoryEntry - To be added. - To be added. + The thread local storage (TLS) table image directory entry. + A directory entry instance. Date: Thu, 26 Sep 2019 14:52:45 -0700 Subject: [PATCH 08/15] suggestions by rpetrusha Co-Authored-By: Ron Petrusha --- .../PEHeader.xml | 104 +++++++++--------- .../PEHeaderBuilder.xml | 8 +- .../PEHeaders.xml | 76 ++++++------- 3 files changed, 96 insertions(+), 92 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEHeader.xml b/xml/System.Reflection.PortableExecutable/PEHeader.xml index cead79f1b7b..e7a42912bec 100644 --- a/xml/System.Reflection.PortableExecutable/PEHeader.xml +++ b/xml/System.Reflection.PortableExecutable/PEHeader.xml @@ -44,8 +44,8 @@ System.Int32 - The address of the entry point relative to the image base when the PE file is loaded into memory. - To be added. + Gets the address of the entry point relative to the image base when the PE file is loaded into memory. + The address of the entry point relative to the image base. System.Int32 - The address that is relative to the image base of the beginning-of-code section when it is loaded into memory. - To be added. + Gets the address of the beginning-of-code section relative to the image base when the image is loaded into memory. + The address of the beginning-of-code section relative to the image base. To be added. @@ -104,8 +104,8 @@ For program images, this is the starting address. For device drivers, this is th System.Int32 - The address that is relative to the image base of the beginning-of-data section when it is loaded into memory. - To be added. + Gets the address of the beginning-of-data section relative to the image base when the image is loaded into memory. + The address of the beginning-of-data section relative to the image base. To be added. @@ -198,7 +198,7 @@ Represents `IMAGE_DIRECTORY_ENTRY_BOUND_IMPORT`. System.Reflection.PortableExecutable.DirectoryEntry - The Certificate Table entry points to a table of attribute certificates. + Gets the Certificate Table entry, which points to a table of attribute certificates. To be added. System.UInt32 - The image file checksum. - To be added. + Gets the image file checksum. + The image file checksum. To be added. @@ -490,7 +490,7 @@ Represents `IMAGE_DIRECTORY_ENTRY_EXPORT`. System.Int32 - The alignment factor (in bytes) that is used to align the raw data of sections in the image file. + Gets the alignment factor (in bytes) that is used to align the raw data of sections in the image file. A power of 2 between 512 and 64K, inclusive. The default is 512. System.UInt64 - The preferred address of the first byte of image when loaded into memory. - A multiple of 64K. + Gets the preferred address of the first byte of the image when it is loaded into memory. + The preferred address, which is a multiple of 64K. To be added. @@ -685,8 +685,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.Reflection.PortableExecutable.PEMagic - Identifies the format of the image file. - To be added. + Gets a value that identifies the format of the image file. + The format of the image file. To be added. @@ -711,8 +711,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.UInt16 - The major version number of the image. - To be added. + Gets the major version number of the image. + The major version number of the image. To be added. @@ -737,8 +737,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.Byte - The linker major version number. - To be added. + Gets the linker major version number. + The linker major version number. To be added. @@ -763,8 +763,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.UInt16 - The major version number of the required operating system. - To be added. + Gets the major version number of the required operating system. + The major version number of the required operating system. To be added. @@ -789,8 +789,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.UInt16 - The major version number of the subsystem. - To be added. + Gets the major version number of the subsystem. + The major version number of the subsystem. To be added. @@ -815,8 +815,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.UInt16 - The minor version number of the image. - To be added. + Gets the minor version number of the image. + The minor version number of the image. To be added. @@ -841,8 +841,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.Byte - The linker minor version number. - To be added. + Gets the linker minor version number. + The linker minor version number. To be added. @@ -867,8 +867,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.UInt16 - The minor version number of the required operating system. - To be added. + Gets the minor version number of the required operating system. + The minor version number of the required operating system. To be added. @@ -893,8 +893,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.UInt16 - The minor version number of the subsystem. - To be added. + Gets the minor version number of the subsystem. + The minor version number of the subsystem. To be added. @@ -919,8 +919,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_LOAD_CONFIG`. System.Int32 - The number of data-directory entries in the remainder of the . Each describes a location and size. - To be added. + Gets the number of data-directory entries in the remainder of the . Each describes a location and size. + The number of data-directory entries in the remainder of the . To be added. @@ -979,7 +979,7 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.Int32 - The alignment (in bytes) of sections when they are loaded into memory. + Gets the alignment (in bytes) of sections when they are loaded into memory. A number greater than or equal to . The default is the page size for the architecture. To be added. @@ -1005,8 +1005,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.Int32 - The size of the code (text) section, or the sum of all code sections if there are multiple sections. - To be added. + Gets the size of the code (text) section, or the sum of all code sections if there are multiple sections. + the size of the code (text) section, or the sum of all code sections if there are multiple sections. To be added. @@ -1031,8 +1031,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.Int32 - The combined size of an MS DOS stub, PE header, and section headers rounded up to a multiple of FileAlignment. - To be added. + Gets the combined size of an MS DOS stub, PE header, and section headers rounded up to a multiple of FileAlignment. + The combined size of an MS DOS stub, PE header, and section headers rounded up to a multiple of FileAlignment. To be added. @@ -1057,8 +1057,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.UInt64 - The size of the local heap space to commit. - To be added. + Gets the size of the local heap space to commit. + the size of the local heap space to commit. To be added. @@ -1083,8 +1083,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.UInt64 - The size of the local heap space to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. - To be added. + Gets the size of the local heap space to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. + The size of the local heap space to reserve. To be added. @@ -1109,8 +1109,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.Int32 - The size (in bytes) of the image, including all headers, as the image is loaded in memory. - A multiple of . + Gets the size (in bytes) of the image, including all headers, as the image is loaded in memory. + The size (in bytes) of the image, which is a multiple of . To be added. @@ -1135,7 +1135,7 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.Int32 - The size of the initialized data section, or the sum of all such sections if there are multiple data sections. + Gets the size of the initialized data section, or the sum of all such sections if there are multiple data sections. To be added. To be added. @@ -1161,8 +1161,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.UInt64 - The size of the stack to commit. - To be added. + Gets the size of the stack to commit. + The size of the stack to commit. To be added. @@ -1187,8 +1187,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.UInt64 - The size of the stack to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. - To be added. + Gets the size of the stack to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. + The size of the stack to reserve. To be added. @@ -1213,8 +1213,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.Int32 - The size of the uninitialized data section (BSS), or the sum of all such sections if there are multiple BSS sections. - To be added. + Gets the size of the uninitialized data section (BSS), or the sum of all such sections if there are multiple BSS sections. + The size of the uninitialized data section (BSS) or the sum of all such sections. To be added. @@ -1239,8 +1239,8 @@ Represents `IMAGE_DIRECTORY_ENTRY_RESOURCE`. System.Reflection.PortableExecutable.Subsystem - The subsystem that is required to run this image. - To be added. + Gets the name of the subsystem that is required to run this image. + the name of the subsystem that is required to run this image. To be added. diff --git a/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml b/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml index 4d0636191f3..555f5670e53 100644 --- a/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml +++ b/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml @@ -75,9 +75,13 @@ To be added. To be added. To be added. - Creates PE header builder. + Initializes a new instance of the class. To be added. - is not power of 2 between 512 and 64K, or not power of 2 or it's less than . + is not power of 2 between 512 and 64K. +-or- + not power of 2. +-or- + is less than . diff --git a/xml/System.Reflection.PortableExecutable/PEHeaders.xml b/xml/System.Reflection.PortableExecutable/PEHeaders.xml index adea1a9a0ab..416e1b8e17b 100644 --- a/xml/System.Reflection.PortableExecutable/PEHeaders.xml +++ b/xml/System.Reflection.PortableExecutable/PEHeaders.xml @@ -19,7 +19,7 @@ - An object used to read PE (Portable Executable) and COFF (Common Object File Format) headers from a stream. + Defines a type that reads PE (Portable Executable) and COFF (Common Object File Format) headers from a stream. To be added. @@ -44,8 +44,8 @@ - A stream containing PE image starting at the stream's current position and ending at the end of the stream. - Reads the PE headers from the current location in the stream. + A stream containing the PE image starting at the stream's current position and ending at the end of the stream. + Instantiates a new instance of the class that reads the PE headers from the current location in the specified stream. To be added. The data read from the stream has an invalid format. Error reading from the stream. @@ -76,14 +76,14 @@ A stream containing PE image of the given size starting at its current position. - THe size of the PE image. - Reads the PE headers from the current location in the stream. + The size of the PE image. + Instantiates a new instance of the class that reads the PE headers from a stream that represents a PE image of a specified size. To be added. The data read from the stream has an invalid format. Error reading from the stream. The stream does not support seek operations. is . - The size is negative or extends past the end of the stream. + is negative or extends past the end of the stream. @@ -109,14 +109,14 @@ The stream containing PE image of the given size starting at its current position. The size of the PE image. - if the PE image has been loaded into memory by the OS loader. - Reads the PE headers from the current location in the stream. + if the PE image has been loaded into memory by the OS loader; otherwise, . + Instantiates a new instance of the class that reads the PE headers from a stream that represents a PE image of a specified size and indicates whether the PE image has been loaded into memory. To be added. The data read from the stream has invalid format. Error reading from the stream. The stream does not support seek operations. is . - The size is negative or extends past the end of the stream. + is negative or extends past the end of the stream. @@ -141,7 +141,7 @@ Gets the COFF header of the image. - To be added. + The COFF header of the image. To be added. @@ -167,7 +167,7 @@ Gets the byte offset from the start of the PE image to the start of the COFF header. - To be added. + The byte offset from the start of the PE image to the start of the COFF header. To be added. @@ -192,8 +192,8 @@ System.Reflection.PortableExecutable.CorHeader - Gets the CLI header or if the image does not have one. - To be added. + Gets the COR header. + The COR header, or if the image does not have one. To be added. @@ -218,8 +218,8 @@ System.Int32 - Gets the byte offset from the start of the image to the COR header or -1 if the image does not have one. - To be added. + Gets the byte offset from the start of the image to the COR header. + The byte offset from the start of the image to the COR header, or -1 if the image does not have a COR header. To be added. @@ -247,9 +247,9 @@ - The specified relative virtual address to search. - Searches sections of the PE image for the one that contains specified Relative Virtual Address. - Index of the section that contains , or -1 if there is none. + The relative virtual address to search for. + Searches sections of the PE image for the section that contains the specified Relative Virtual Address. + The index of the section that contains , or -1 if there the search is unsuccessful. To be added. @@ -274,8 +274,8 @@ System.Boolean - Determines if the image is Coff only. - To be added. + Gets a value that indicates whether the image is Coff only. + if the image is Coff only; otherwise, . To be added. @@ -300,8 +300,8 @@ System.Boolean - Determines if the image represents a Windows console application. - To be added. + Gets a value that indicates whether the image represents a Windows console application. + if the image is a Windows console applications; otherwise, . To be added. @@ -326,8 +326,8 @@ System.Boolean - Determines if the image represents a dynamically linked library. - To be added. + Gets a value that indicates whether the image represents a dynamic link library. + if the image is a DLL; otherwise, . To be added. @@ -352,8 +352,8 @@ System.Boolean - Determines if the image represents an executable. - To be added. + Gets a value that indicates whether the image represents an executable. + if the image is an executable; otherwise, . To be added. @@ -378,8 +378,8 @@ System.Int32 - Gets the size of the CLI metadata, 0 if the image does not contain metadata. - To be added. + Gets the size of the CLI metadata. + the size of the CLI metadata, or 0 if the image does not contain metadata. To be added. @@ -404,8 +404,8 @@ System.Int32 - Gets the offset (in bytes) from the start of the PE image to the start of the CLI metadata or -1 if the image does not contain metadata. - To be added. + Gets the offset (in bytes) from the start of the PE image to the start of the CLI metadata. + The offset (in bytes) from the start of the PE image to the start of the CLI metadata, or -1 if the image does not contain metadata. To be added. @@ -430,8 +430,8 @@ System.Reflection.PortableExecutable.PEHeader - Gets the PE header of the image or if the image is COFF only. - To be added. + Gets the image's PE header. + The image's PE header, or if the image is COFF only. To be added. @@ -456,8 +456,8 @@ System.Int32 - Gets the byte offset from the start of the image. - To be added. + Gets the byte offset of the header from the start of the image. + The byte offset of the header from the start of the image. To be added. @@ -483,7 +483,7 @@ Gets the PE section headers. - To be added. + An array containing the PE section headers. To be added. @@ -512,10 +512,10 @@ - PE directory entry. - Offset from the start of the image to the given directory data. + The PE directory entry. + When the method returns, contains the offset from the start of the image to the given directory data. Gets the offset (in bytes) from the start of the image to the given directory data. - if the directory data is found, otherwise. + if the directory data is found; otherwise. To be added. From 8151ae40a4624c80764d2d8730913c3f41f4231f Mon Sep 17 00:00:00 2001 From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> Date: Thu, 26 Sep 2019 14:57:11 -0700 Subject: [PATCH 09/15] suggestions by rpetrusha Co-Authored-By: Ron Petrusha --- .../PEReader.xml | 58 ++++++++++--------- 1 file changed, 31 insertions(+), 27 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEReader.xml b/xml/System.Reflection.PortableExecutable/PEReader.xml index 313967a7d4c..c13d7d4b0f8 100644 --- a/xml/System.Reflection.PortableExecutable/PEReader.xml +++ b/xml/System.Reflection.PortableExecutable/PEReader.xml @@ -23,7 +23,7 @@ - Portable Executable format reader. + Provides a reader for Portable Executable format (PE) files. - Pointer to the start of the PE image. + A pointer to the start of the PE image. The size of the PE image. Creates a Portable Executable reader over a PE image stored in memory. @@ -134,9 +134,8 @@ Ownership of the stream is transferred to the . +The memory is owned by the caller and not released on disposal of the . The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the . -The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the . The content of the image is not read during the construction of the @@ -168,7 +167,7 @@ The content of the image is not read during the construction of the - PE image stream. + A PE image stream. Options specifying how sections of the PE image are read from the stream. Creates a Portable Executable reader over a PE image stored in a stream beginning at its current position and ending at the end of the stream. @@ -176,18 +175,18 @@ The content of the image is not read during the construction of the is specified, ownership of the stream is transferred to the upon successful argument validation. It will be disposed by the and the caller must not manipulate it. +Unless is specified, ownership of the stream is transferred to the upon successful argument validation. It will be disposed by the and the caller must not manipulate it. -Unless or is specified no data is read from the stream during the construction of the . Furthermore, the stream must not be manipulated by caller while the is alive and undisposed. +Unless or is specified, no data is read from the stream during the construction of the . Furthermore, the stream must not be manipulated by caller while the is alive and undisposed. -If or , the will have read all of the data requested during construction. As such, if is also specified, the caller retains full ownership of the stream and is assured that it will not be manipulated by the after construction. +If `options` includes or , the will have read all of the data requested during construction. As such, if is also specified, the caller retains full ownership of the stream and is assured that it will not be manipulated by the after construction. ]]> is . has an invalid value. Error reading from the stream (only when prefetching data). - is specified and the PE headers of the image are invalid. + is specified, and the PE headers of the image are invalid. @@ -212,16 +211,15 @@ If A pointer to the start of the PE image. The size of the PE image. - if the PE image has been loaded into memory by the OS loader. - Creates a Portable Executable reader over a PE image stored in memory. + if the PE image has been loaded into memory by the OS loader; otherwise, . + Creates a Portable Executable reader over a PE image stored in memory. A flag indicates whether the image has already been loaded into memory. . +The memory is owned by the caller and is not released when the is disposed. The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the . -The caller is responsible for keeping the memory alive and unmodified throughout the lifetime of the . The content of the image is not read during the construction of the @@ -254,26 +252,26 @@ The content of the image is not read during the construction of the - PE image stream. + A PE image stream. Options specifying how sections of the PE image are read from the stream. - PE image size. + The PE image size. Creates a Portable Executable reader over a PE image of the given size beginning at the stream's current position. is specified, ownership of the stream is transferred to the upon successful argument validation. It will be disposed by the and the caller must not manipulate it. +Unless is specified, ownership of the stream is transferred to the upon successful argument validation. It will be disposed by the , and the caller must not manipulate it. -Unless or is specified no data is read from the stream during the construction of the . Furthermore, the stream must not be manipulated by caller while the is alive and undisposed. +Unless or is specified, no data is read from the stream during the construction of the . Furthermore, the stream must not be manipulated by the caller while the is alive and undisposed. -If or , the will have read all of the data requested during construction. As such, if is also specified, the caller retains full ownership of the stream and is assured that it will not be manipulated by the after construction. +If `options` includes the or values, the will have read all of the data requested during construction. As such, if is also specified, the caller retains full ownership of the stream and is assured that it will not be manipulated by the after construction. ]]> - Size is negative or extends past the end of the stream. + is negative or extends past the end of the stream. Error reading from the stream (only when prefetching data). - is specified and the PE headers of the image are invalid. + is specified, and the PE headers of the image are invalid. @@ -309,7 +307,7 @@ If > [!IMPORTANT] > can be called multiple times, but not in parallel. -> It is not safe to call in parallel with any other operation on the or reading from s retrieved from the reader. +> It is not safe to call in parallel with any other operation on the or when reading from s retrieved from the reader. ]]> @@ -337,9 +335,15 @@ If - Gets a pointer to and size of the PE image if available (). - To be added. - To be added. + Gets a object containing the entire PE image. + A memory block that contains the entire PE image. + + property to determine whether the makes the entire image available. + + ]]> + The entire PE image is not available. @@ -365,10 +369,10 @@ If - Loads PE section that contains CLI metadata. - To be added. + Loads a PE section that contains CLI metadata. + A memory block that contains the CLI metadata. To be added. - The PE image doesn't contain metadata ( returns false). + The PE image doesn't contain metadata ( returns ). The PE headers contain invalid data. IO error while reading from the underlying stream. From 9b1ce009cf9bf7b7db069199a99289829df453f5 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 26 Sep 2019 15:00:32 -0700 Subject: [PATCH 10/15] PEReader add missing elements --- xml/System.Reflection.PortableExecutable/PEReader.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEReader.xml b/xml/System.Reflection.PortableExecutable/PEReader.xml index 313967a7d4c..ed19d5dc7ed 100644 --- a/xml/System.Reflection.PortableExecutable/PEReader.xml +++ b/xml/System.Reflection.PortableExecutable/PEReader.xml @@ -338,7 +338,7 @@ If Gets a pointer to and size of the PE image if available (). - To be added. + A PE memory block instance. To be added. The entire PE image is not available. @@ -366,7 +366,7 @@ If Loads PE section that contains CLI metadata. - To be added. + A PE memory block instance. To be added. The PE image doesn't contain metadata ( returns false). The PE headers contain invalid data. @@ -574,9 +574,9 @@ The property returns `false` if the - To be added. + A Debug Directory entry instance. Reads the data pointed to by the specified Debug Directory entry and interprets it as CodeView. - To be added. + A code view debug directory data instance. To be added. is not a CodeView entry. Bad format of the data. From e8fb5b1ef4c7cb8aaafe6190a56a267fcd7ceb5f Mon Sep 17 00:00:00 2001 From: Carlos Sanchez Lopez <1175054+carlossanlop@users.noreply.github.com> Date: Thu, 26 Sep 2019 15:17:16 -0700 Subject: [PATCH 11/15] entry point address --- .../PEDirectoriesBuilder.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml b/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml index f6b2c752fe2..47b3f40d398 100644 --- a/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml +++ b/xml/System.Reflection.PortableExecutable/PEDirectoriesBuilder.xml @@ -60,8 +60,8 @@ System.Int32 - The entry point address. - An integer representing the entry point address. + The address of the entry point relative to the image base when the PE file is loaded into memory. + For program images, this is the starting address. For device drivers, this is the address of the initialization function. An entry point is optional for DLLs. When no entry point is present, this field must be zero. To be added. From a437b902425ad71a4685184756cd31b42ecef579 Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Thu, 26 Sep 2019 15:34:35 -0700 Subject: [PATCH 12/15] PEHeaderBuilder changes --- .../PEHeaderBuilder.xml | 82 +++++++++---------- 1 file changed, 41 insertions(+), 41 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml b/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml index aa1ebe880d4..e58a246b139 100644 --- a/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml +++ b/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml @@ -107,8 +107,8 @@ - To be added. - To be added. + Creates an executable header. + A instance representing the executable header. To be added. @@ -132,8 +132,8 @@ - To be added. - To be added. + Creates a library header. + A instance representing the library header. To be added. @@ -156,8 +156,8 @@ System.Reflection.PortableExecutable.DllCharacteristics - To be added. - To be added. + Returns the dynamic linker library characteristics. + An object that describes the dynamic linker library characteristics. To be added. @@ -180,7 +180,7 @@ System.Int32 - To be added. + The alignment factor (in bytes) that is used to align the raw data of sections in the image file. The value should be a power of 2 between 512 and 64K, inclusive. The default is 512. If the section alignment is less than the architecture's page size, then file alignment must match the section alignment. To be added. To be added. @@ -204,8 +204,8 @@ System.UInt64 - To be added. - To be added. + The preferred address of the first byte of image when loaded into memory; must be a multiple of 64K. + A number representing the preferred address of the first byte of image when loaded into memory. To be added. @@ -228,8 +228,8 @@ System.Reflection.PortableExecutable.Characteristics - To be added. - To be added. + Returns the image characteristics. + An object representing the image characteristics. To be added. @@ -252,8 +252,8 @@ System.Reflection.PortableExecutable.Machine - To be added. - To be added. + The target machine's CPU architecture. + One of the enumeration values representing the different CPU architectures. To be added. @@ -276,8 +276,8 @@ System.UInt16 - To be added. - To be added. + The major version number of the image. + A number the size of a representing the the major version number of the image. To be added. @@ -300,8 +300,8 @@ System.Byte - To be added. - To be added. + The linker major version number. + A number the size of a representing the linker major version number. To be added. @@ -324,8 +324,8 @@ System.UInt16 - To be added. - To be added. + The major version number of the required operating system. + A number the size of a representing the major version number of the required operating system. To be added. @@ -348,8 +348,8 @@ System.UInt16 - To be added. - To be added. + The major version number of the subsystem. + A number the size of a representing the major version number of the subsystem. To be added. @@ -372,8 +372,8 @@ System.UInt16 - To be added. - To be added. + The minor version number of the image. + A number the size of a representing the minor version number of the image. To be added. @@ -396,8 +396,8 @@ System.Byte - To be added. - To be added. + The linker minor version number. + A number the size of a representing the linker minor version number. To be added. @@ -420,8 +420,8 @@ System.UInt16 - To be added. - To be added. + The minor version number of the required operating system. + A number the size of a representing the minor version number of the required operating system. To be added. @@ -444,8 +444,8 @@ System.UInt16 - To be added. - To be added. + The minor version number of the subsystem. + A number the size of a representing the minor version number of the subsystem. To be added. @@ -468,8 +468,8 @@ System.Int32 - To be added. - To be added. + The alignment (in bytes) of sections when they are loaded into memory. + A number representing the alignment (in bytes) of sections when they are loaded into memory. It must be greater than or equal to the file alignment. The default is the page size for the architecture. To be added. @@ -492,8 +492,8 @@ System.UInt64 - To be added. - To be added. + The size of the local heap space to commit. + A number representing the size of the local heap space to commit. To be added. @@ -516,8 +516,8 @@ System.UInt64 - To be added. - To be added. + The size of the local heap space to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. + A number representing the size of the local heap space to reserve. To be added. @@ -540,8 +540,8 @@ System.UInt64 - To be added. - To be added. + The size of the stack to commit. + A number representing the size of the stack to commit. To be added. @@ -564,8 +564,8 @@ System.UInt64 - To be added. - To be added. + The size of the stack to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. + A number representing the size of the stack to reserve. To be added. @@ -588,8 +588,8 @@ System.Reflection.PortableExecutable.Subsystem - To be added. - To be added. + The subsystem that is required to run this image. + A instance. To be added. From 94a9ea48662f281abe893dc42185c9da72047de8 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Wed, 2 Oct 2019 13:19:09 -0700 Subject: [PATCH 13/15] Fixed para tag --- xml/System.Reflection.PortableExecutable/PEStreamOptions.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml b/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml index 25ed42913ef..d204f2f2cfb 100644 --- a/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml +++ b/xml/System.Reflection.PortableExecutable/PEStreamOptions.xml @@ -147,7 +147,7 @@ 2 - Reads the metadata section into memory right away.Reading from other sections of the file is not allowed ( is thrown by the ). closes the stream automatically by the time the constructor returns unless is specified. The underlying file may be closed and even deleted after is constructed. + Reads the metadata section into memory right away.Reading from other sections of the file is not allowed ( is thrown by the ). closes the stream automatically by the time the constructor returns unless is specified. The underlying file may be closed and even deleted after is constructed. From 5f96cc36e659fdb6401624bd3597e73d022b25b5 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Fri, 11 Oct 2019 10:08:43 -0700 Subject: [PATCH 14/15] Update PEReader.xml --- xml/System.Reflection.PortableExecutable/PEReader.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Reflection.PortableExecutable/PEReader.xml b/xml/System.Reflection.PortableExecutable/PEReader.xml index cb7293b9aac..70143dde642 100644 --- a/xml/System.Reflection.PortableExecutable/PEReader.xml +++ b/xml/System.Reflection.PortableExecutable/PEReader.xml @@ -340,7 +340,7 @@ If `options` includes the property to determine whether the makes the entire image available. +You can retrieve the value of the property to determine whether the makes the entire image available. ]]> From 456af06e59d7f97f20e606acdf66bf2c7fedd529 Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Fri, 11 Oct 2019 10:13:07 -0700 Subject: [PATCH 15/15] Fixed bad crefs --- xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml b/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml index e58a246b139..812500bf86c 100644 --- a/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml +++ b/xml/System.Reflection.PortableExecutable/PEHeaderBuilder.xml @@ -516,7 +516,7 @@ System.UInt64 - The size of the local heap space to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. + The size of the local heap space to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. A number representing the size of the local heap space to reserve. To be added. @@ -564,7 +564,7 @@ System.UInt64 - The size of the stack to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. + The size of the stack to reserve. Only is committed; the rest is made available one page at a time until the reserve size is reached. A number representing the size of the stack to reserve. To be added.