diff mbox series

[v4,4/7] ld.texi: Add ASCII to info file

Message ID 20240708174929.15137-5-binutils@emagii.com
State New
Headers
Series ASCII output section command |

Checks

Context Check Description
linaro-tcwg-bot/tcwg_binutils_build--master-arm success Build passed
linaro-tcwg-bot/tcwg_binutils_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_binutils_check--master-aarch64 success Test passed
linaro-tcwg-bot/tcwg_binutils_check--master-arm success Test passed

Commit Message

Ulf Samuelsson July 8, 2024, 5:49 p.m. UTC 
  From: Ulf Samuelsson <ulf@emagii.com>

Signed-off-by: Ulf Samuelsson <ulf@emagii.com>
---
 ld/ld.texi | 42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)
diff mbox series

Patch

diff --git a/ld/ld.texi b/ld/ld.texi
index 89e3913317a..70ff492ab2b 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -5642,7 +5642,8 @@  C identifiers because they contain a @samp{.} character.
 @cindex data
 @cindex section data
 @cindex output section data
-@kindex ASCIZ ``@var{string}''
+@kindex ASCIZ "@var{string}"
+@kindex ASCII @var{expression}, "@var{string}"
 @kindex BYTE(@var{expression})
 @kindex SHORT(@var{expression})
 @kindex LONG(@var{expression})
@@ -5681,7 +5682,7 @@  endianness of the first input object file.
 
 You can include a zero-terminated string in an output section by using
 @code{ASCIZ}.  The keyword is followed by a string which is stored at
-the current value of the location counter adding a zero byte at the
+the current value of the location counter adding a NUL byte at the
 end.  If the string includes spaces it must be enclosed in double
 quotes.  The string may contain '\n', '\r', '\t' and octal numbers.
 Hex numbers are not supported.
@@ -5691,6 +5692,43 @@  For example, this string of 16 characters will create a 17 byte area
   ASCIZ "This is 16 bytes"
 @end smallexample
 
+You can include a fixed size string in an output section by using
+@code{ASCII}.  The keyword is followed by a size and a string
+separated by a comma.  The string is stored at the current
+value of the location counter. If the string is shorted than the allocated
+size, NUL character are added at the end to fill up to the specified size.
+Note the fill value is ignored for this padding.
+If the string includes spaces it must be enclosed in double
+quotes.  The string may contain '\n', '\r', '\t' and octal numbers.
+Hex numbers are not supported.
+
+If the string is too long, a warning is issued and the string is
+truncated.  The string will still be zero-terminated in this case.
+
+If the expression evaluates to zero then the directive will be treated
+as if it were @code{ASCIZ} instead.
+
+Example: This is string of 16 characters and will create a 16 byte
+area, not zero-terminated.
+@smallexample
+  ASCII 16, "This is 16 bytes"
+@end smallexample
+
+
+Example: This is string of 10 characters in a 16 byte area, unused locations are filled with NUL characters.
+@smallexample
+  ASCII 16, "This is 16"
+@end smallexample
+
+
+Example: This is string of 15 characters in a 16 byte area, ending with a NUL character.
+@smallexample
+  ASCII 16, "01234567890123456789"
+@end smallexample
+The last character of the string will be "4".
+A warning will be issued to indicate that the string does not fit.
+
+
 Note---these commands only work inside a section description and not
 between them, so the following will produce an error from the linker:
 @smallexample