doc/develop/printf.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Printf() format codes
   4 =====================
   5
   6 Each conversion specification consists of:
   7
   8 * leading '%' character
   9 * zero or more flags
  10 * an optional minimum field width
  11 * an optional precision field preceded by '.'
  12 * an optional length modifier
  13 * a conversion specifier
  14
  15 Flags
  16 -----
  17
  18 'space'
  19         fill up with spaces to reach the specified length
  20
  21 \-
  22         left justify
  23
  24 \+
  25         add sign field of decimal conversion
  26
  27 #
  28         convert to alternative form
  29
  30         * prepend 0 to octal output
  31         * ignored for decimal output
  32         * prepend 0X to hexadecimal output
  33
  34 0
  35         fill up with zeroes to reach the specified length
  36
  37
  38 Integer types
  39 -------------
  40
  41 Length modifiers
  42 ''''''''''''''''
  43
  44 The optional length modifier specifies the size of the argument.
  45
  46 no modifier
  47         bool, enum, short, int are passed as int
  48
  49 %h
  50         convert to (unsigned) short before printing.
  51         Only the low 16 bits are printed.
  52
  53 %hh
  54         **not implemented**
  55
  56 %j
  57         **not implemented**
  58
  59 %l
  60         long
  61
  62 %ll, %L
  63         long long
  64
  65 %t
  66         ptr_diff_t
  67
  68 %z, %Z
  69         size_t, ssize_t
  70
  71 Conversion specifiers
  72 '''''''''''''''''''''
  73
  74 Conversion specifiers control the output.
  75
  76 %d
  77         signed decimal
  78
  79 %u
  80         unsigned decimal
  81
  82 %o
  83         unsigned octal
  84
  85 %x
  86         unsigned lower case hexadecimal
  87
  88 %X
  89         unsigned upper case hexadecimal
  90
  91 The floating point conversion specifiers are not implemented:
  92
  93 * %a
  94 * %A
  95 * %e
  96 * %E
  97 * %f
  98 * %F
  99 * %g
 100 * %G
 101
 102 The following tables shows the correct combinations of modifiers and specifiers
 103 for the individual integer types.
 104
 105 =================== ==================
 106 Type                Format specifier
 107 =================== ==================
 108 bool                %d, %x
 109 char                %d, %x
 110 unsigned char       %u, %x
 111 short               %d, %x
 112 unsigned short      %u, %x
 113 int                 %d, %x
 114 unsigned int        %d, %x
 115 long                %ld, %lx
 116 unsigned long       %lu, %lx
 117 long long           %lld, %llx
 118 unsigned long long  %llu, %llx
 119 off_t               %llu, %llx
 120 ptr_diff_t          %td, %tx
 121 fdt_addr_t          %pa, see pointers
 122 fdt_size_t          %pa, see pointers
 123 phys_addr_t         %pa, see pointers
 124 phys_size_t         %pa, see pointers
 125 resource_size_t     %pa, see pointers
 126 size_t              %zu, %zx, %zX
 127 ssize_t             %zd, %zx, %zX
 128 =================== ==================
 129
 130 Characters
 131 ----------
 132
 133 %%
 134         a '%' character is written
 135
 136 %c
 137         prints a single character
 138
 139 %lc
 140         **not implemented**
 141
 142 Strings
 143 -------
 144
 145 %s
 146         prints a UTF-8 string (char \*)
 147
 148 %ls
 149         prints a UTF-16 string (u16 \*)
 150
 151 Pointers
 152 --------
 153
 154 %p
 155         prints the address the pointer points to hexadecimally
 156
 157 %pa, %pap
 158         prints the value of a phys_addr_t value that the pointer points to
 159         preceded with 0x and zero padding according to the size of phys_addr_t.
 160         The following types should be printed this way:
 161
 162         * fdt_addr_t
 163         * fdt_size_t
 164         * phys_addr_t
 165         * phys_size_t
 166         * resource_size_t
 167
 168 %pD
 169         prints a UEFI device path
 170
 171 %pi4, %pI4
 172         prints IPv4 address, e.g. '192.168.0.1'
 173
 174 %pm
 175         prints MAC address without separators, e.g. '001122334455'
 176
 177 %pM
 178         print MAC address colon separated, e.g. '00:01:02:03:04:05'
 179
 180 %pUb
 181         prints GUID big endian, lower case
 182         e.g. '00112233-4455-6677-8899-aabbccddeeff'
 183
 184 %pUB
 185         prints GUID big endian, upper case
 186         e.g. '00112233-4455-6677-8899-AABBCCDDEEFF'
 187
 188 %pUl
 189         prints GUID little endian, lower case
 190         e.g. '33221100-5544-7766-8899-aabbccddeeff'
 191
 192 %pUL
 193         prints GUID little endian, upper case
 194         e.g. '33221100-5544-7766-8899-AABBCCDDEEFF'
 195
 196 %pUs
 197         prints text description of a GUID or if such is not known little endian,
 198         lower case, e.g. 'system' for a GUID identifying an EFI system
 199         partition.