SORT_BY_INIT_PRIORITY

I was looking at the implementation of this script keyword today and
couldn't remember why we do what we do in get_init_priority, because
the comments explain how the init_priority is encoded but don't say
why it is necessary to extract the priority and sort on that.  So
after figuring out why (again), I wrote some more comments.

Then I simplified get_init_priority a little, adding some sanity
checking on the strtoul result.  This actually makes get_init_priority
support sorting by numerical suffix more generally, but I figure this
feature would be better as a new keyword (without the .ctors/.dtors
special case), so haven't documented the extension.

	* ld.texi (SORT_BY_ALIGNMENT): Reword slightly.
	(SORT_BY_INIT_PRIORITY): Elucidate.
	* ldlang.c: Include limits.h.
	(get_init_priority): Comment.  Change param to a section,
	return an int.  Sanity check priority digits.  Support sorting
	more sections with trailing digits.  Return -1 on error.
	(compare_section): Adjust.

1 files changed, 12 insertions, 9 deletions

diff --git a/ld/ld.texi b/ld/ld.texi
index 8d5c7bc..95fa6a0 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -4630,17 +4630,20 @@ pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}).  When the
 into ascending order by name before placing them in the output file.
 
 @cindex SORT_BY_ALIGNMENT
-@code{SORT_BY_ALIGNMENT} is very similar to @code{SORT_BY_NAME}. The
-difference is @code{SORT_BY_ALIGNMENT} will sort sections into
-descending order by alignment before placing them in the output file.
-Larger alignments are placed before smaller alignments in order to
-reduce the amount of padding necessary.
+@code{SORT_BY_ALIGNMENT} is similar to @code{SORT_BY_NAME}.
+@code{SORT_BY_ALIGNMENT} will sort sections into descending order of
+alignment before placing them in the output file.  Placing larger
+alignments before smaller alignments can reduce the amount of padding
+needed.
 
 @cindex SORT_BY_INIT_PRIORITY
-@code{SORT_BY_INIT_PRIORITY} is very similar to @code{SORT_BY_NAME}. The
-difference is @code{SORT_BY_INIT_PRIORITY} will sort sections into
-ascending order by numerical value of the GCC init_priority attribute
-encoded in the section name before placing them in the output file.
+@code{SORT_BY_INIT_PRIORITY} is also similar to @code{SORT_BY_NAME}.
+@code{SORT_BY_INIT_PRIORITY} will sort sections into ascending
+numerical order of the GCC init_priority attribute encoded in the
+section name before placing them in the output file.  In
+@code{.init_array.NNNNN} and @code{.fini_array.NNNNN}, @code{NNNNN} is
+the init_priority.  In @code{.ctors.NNNNN} and @code{.dtors.NNNNN},
+@code{NNNNN} is 65535 minus the init_priority.
 
 @cindex SORT
 @code{SORT} is an alias for @code{SORT_BY_NAME}.