emmtrix Wiki - User contributions [en]

Remove Includes Transformation

2025-08-06T06:57:15Z

Tobias.columbus:

== RemoveIncludes Transformation ==
The '''RemoveIncludes Transformation''' removes all non-standard include directives from a C source file and replaces them with the corresponding declarations directly within the file. The result is a self-contained <code>.c</code> file that can be compiled independently of external headers.

This transformation effectively performs a header-flattening step that normally occurs during preprocessing in a compiler’s build pipeline. However, instead of producing a preprocessed file, it inserts only the '''relevant declarations''' (e.g., function prototypes, structs, macros) in a clean and readable format.

=== RemoveIncludes Transformation in emmtrix Studio ===
The '''RemoveIncludes''' transformation in emmtrix Studio resolves and eliminates all non-standard includes from a source file. It can be invoked via
<code>#pragma EMX_TRANSFORMATION_GLOBAL RemoveIncludes</code>
or through the graphical user interface.

The transformation extracts all declarations from the included header files and inserts them directly into the C source file, replacing the corresponding <code>#include</code> directives. System includes such as <code><stdio.h></code> or <code><stdlib.h></code> are left untouched.

After applying this transformation, the resulting <code>.c</code> file is fully self-contained and can be compiled without any external include files.

=== Purpose ===
This transformation is useful when:
* creating '''standalone compilable files''', e.g., for testing, simulation, or external distribution
* analyzing or debugging code where '''include chains introduce complexity'''
* preparing code for '''environments without access to full header hierarchies'''
* exporting generated code for '''toolchain-agnostic or embedded workflows'''

=== Example ===
{| class="wikitable"
|-
| <syntaxhighlight lang="c">
#include "my_driver.h"
#include "board_cfg.h"

int main(void) {
init_driver();
return 0;
}
</syntaxhighlight>
| <syntaxhighlight lang="c">
/* auto-generated by RemoveIncludes Transformation */
void init_driver(void);

int main(void) {
init_driver();
return 0;
}
</syntaxhighlight>
|}

=== Parameters ===
{| class="wikitable"
! Parameter !! Default !! Description
|-
| colspan="4" | Currently, no parameters
|}

=== Limitations ===
* The transformation '''does not take system includes''' (e.g., <code><stdio.h></code>, <code><math.h></code>) into account, although that might be changed in the future.
* '''Static functions or internal declarations''' that are not exposed in headers will not be visible
* '''Header guards, conditional compilation logic or complex macro definitions''' are not always fully preserved

[[Category:Code Transformation]]

Remove Includes Transformation

2025-08-06T06:56:34Z

Tobias.columbus: Created page with "== RemoveIncludes Transformation == The '''RemoveIncludes Transformation''' removes all non-standard include directives from a C source file and replaces them with the corresponding declarations directly within the file. The result is a self-contained <code>.c</code> file that can be compiled independently of external headers. This transformation effectively performs a header-flattening step that normally occurs during preprocessing in a compiler’s build pipeline. How..."

== RemoveIncludes Transformation ==
The '''RemoveIncludes Transformation''' removes all non-standard include directives from a C source file and replaces them with the corresponding declarations directly within the file. The result is a self-contained <code>.c</code> file that can be compiled independently of external headers.

This transformation effectively performs a header-flattening step that normally occurs during preprocessing in a compiler’s build pipeline. However, instead of producing a preprocessed file, it inserts only the '''relevant declarations''' (e.g., function prototypes, structs, macros) in a clean and readable format.

=== RemoveIncludes Transformation in emmtrix Studio ===
The '''RemoveIncludes''' transformation in emmtrix Studio resolves and eliminates all non-standard includes from a source file. It can be invoked via
<code>#pragma EMX_TRANSFORMATION RemoveIncludes</code>
or through the graphical user interface.

The transformation extracts all declarations from the included header files and inserts them directly into the C source file, replacing the corresponding <code>#include</code> directives. System includes such as <code><stdio.h></code> or <code><stdlib.h></code> are left untouched.

After applying this transformation, the resulting <code>.c</code> file is fully self-contained and can be compiled without any external include files.

=== Purpose ===
This transformation is useful when:
* creating '''standalone compilable files''', e.g., for testing, simulation, or external distribution
* analyzing or debugging code where '''include chains introduce complexity'''
* preparing code for '''environments without access to full header hierarchies'''
* exporting generated code for '''toolchain-agnostic or embedded workflows'''

=== Example ===
{| class="wikitable"
|-
| <syntaxhighlight lang="c">
#include "my_driver.h"
#include "board_cfg.h"

int main(void) {
init_driver();
return 0;
}
</syntaxhighlight>
| <syntaxhighlight lang="c">
/* auto-generated by RemoveIncludes Transformation */
void init_driver(void);

int main(void) {
init_driver();
return 0;
}
</syntaxhighlight>
|}

=== Parameters ===
{| class="wikitable"
! Parameter !! Default !! Description
|-
| colspan="4" | Currently, no parameters
|}

=== Limitations ===
* The transformation '''does not take system includes''' (e.g., <code><stdio.h></code>, <code><math.h></code>) into account, although that might be changed in the future.
* '''Static functions or internal declarations''' that are not exposed in headers will not be visible
* '''Header guards, conditional compilation logic or complex macro definitions''' are not always fully preserved

[[Category:Code Transformation]]

Infineon AURIX TC3xx

2025-07-04T07:17:50Z

Tobias.columbus: /* GCC for AURIX™ */

[[File:AURIX TC399 LFBGA-516 plain.jpg|thumb|Infineon AURIX™ TC3xx second-generation microcontroller (TC399 BGA package). The AURIX™ TC3xx family integrates multiple TriCore™ CPUs and on-chip safety/security modules for automotive applications.|alt=TC399 BGA package]]
The '''Infineon AURIX™ TC3xx''' (Automotive Realtime Integrated neXt-generation architecture) is a family of 32-bit automotive microcontrollers introduced as the second generation of Infineon’s AURIX™ platform. Launched in 2016 as a successor to the earlier [[Infineon AURIX TC2xx|AURIX™ TC2xx series]], the TC3xx devices emphasize high performance, functional safety, and embedded security for advanced automotive and industrial applications. AURIX™ TC3xx microcontrollers feature a hexa-core [[TriCore Instruction Set Architecture|''TriCore'' processor architecture]] with enhanced safety measures, making them well-suited for demanding tasks such as autonomous driving domain controllers, powertrain control, and sensor data fusion in advanced driver-assistance systems (ADAS). The combination of multiple CPU cores, extensive on-chip memory, and a rich peripheral set allows TC3xx chips to deliver real-time responsiveness and reliability in safety-critical environments while meeting stringent automotive standards (such as ISO 26262 for functional safety).<ref name="ref1951907555">Safety Microcontrollers: Texas Instruments Hercules vs Infineon AURIX https://www.linkedin.com/pulse/safety-microcontrollers-texas-instruments-hercules-vs-cook-meng-miet</ref><ref name="ref1428109010">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref1948477695">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref>
==Applications==
AURIX™ TC3xx microcontrollers are used in a variety of safety-critical and high-performance applications across the automotive and industrial sectors. Key application domains include:
*'''Automotive Systems:''' The TC3xx family was primarily designed for automotive use and finds broad application in vehicles’ electronic control units (ECUs). Notably, it is used in ''powertrain and drivetrain control'' (engine management, transmission control, hybrid/electric vehicle inverter control, battery management) where its real-time processing and resilience support precise actuator control. It is also deployed in ''chassis and safety systems'' such as anti-lock braking systems (ABS), electronic stability control, airbag controllers, and electric power steering, leveraging its redundancy and fast response for fail-safe operation. With the growth of ADAS and autonomous driving, AURIX™ TC3xx devices serve as domain controllers for ''ADAS sensor fusion'', handling data from radar, LiDAR, camera, and ultrasonic sensors and performing environment modeling and decision-making algorithms. Their combination of multiple cores and a built-in radar signal processing sub-system makes them an attractive choice for tasks like front radar processing, sensor fusion hubs, and ''autonomous driving domain controllers'' that must meet ASIL-D safety levels.<ref name="ref14281090102">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref572781451">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref>
*'''Industrial Automation and Robotics:''' Infineon has also positioned the AURIX™ family for use in industrial applications that demand high reliability. The TC3xx MCUs, with their hardware self-test mechanisms and safety documentation, can be found in ''industrial motor drives, robotics controllers, and PLCs (programmable logic controllers)'', where they help achieve functional safety certifications up to SIL-3 (according to IEC 61508). The powerful TriCore™ cores and rich peripheral set enable complex motor control algorithms (e.g., field-oriented control for servo motors) and real-time sensor processing in factory automation. Additionally, the support for automotive-grade networking (CAN/CAN-FD, Ethernet) and timing peripherals makes them suitable for synchronous control in robotics and machinery. Infineon’s provision of AUTOSAR-compatible software for AURIX™ has even facilitated its use in non-automotive settings such as medical devices and elevator controllers, where proven safety and security are required.<ref name="ref496771205">Infineon's AURIX™ & TRAVEO™ microcontroller families extend their support for IEC 61508 hardware and software metrics enabling industrial safety up to SIL-3 - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2023/INFATV202303-078.html</ref>
*'''Aerospace and Defense:''' The high fault-tolerance and deterministic performance of the AURIX™ TC3xx architecture also attract interest for aerospace and other mission-critical uses. In avionics systems or autonomous drones, for instance, the lockstep core configuration and robust error checking of AURIX™ can provide an added layer of reliability for flight control computers or navigation systems. While primarily an automotive chip, its ability to operate in harsh conditions (−40°C to 150°C range) and to detect internal failures in real-time makes it viable for certain aerospace electronic systems. Some defense and aerospace projects leverage COTS (commercial off-the-shelf) automotive components like AURIX™ for applications such as unmanned vehicle control and high-reliability communication links, given its safety pedigree. (In these domains, additional analysis and possibly radiation testing would be performed if the devices are used in high-altitude or space environments.)
== Architecture Overview ==
[[File:Infineon TC3xx Architecture.webp|545x545px|thumb|alt=TC3xx Architecture Overview|TC3xx Architecture Overview]]
=== Processor Cores and Architecture===
The AURIX™ TC3xx family implements Infineon’s TriCore™ architecture, which uniquely combines aspects of RISC microcontrollers, DSP (digital signal processor) capabilities, and conventional microprocessor features into a single core design. Each TC3xx device can include up to six independent TriCore™ 32-bit CPU cores (TriCore™ version 1.6.2), all capable of running at up to 300 MHz clock frequency. Four of these cores can operate in dual-core lockstep pairs (with one core acting as a redundant checker for its partner) to provide fault detection for safety-critical functions. The TriCore™ cores use a superscalar Harvard architecture with 32-bit instruction words (and support for mixed 16/32-bit instruction encoding for code density). Each core includes a dedicated Floating Point Unit (FPU) for single-precision arithmetic and supports DSP-oriented instructions (e.g. single-cycle 16×16 MAC operations, SIMD for 16-bit/8-bit data) to accelerate signal processing tasks. For fast real-time performance, the architecture offers low interrupt latency (with automatic context save on-chip) and features like zero-overhead loops and a programmable peripheral timer unit for scheduling tasks. In total, a high-end TC3xx (such as the TC39x) provides six 300 MHz cores plus four checker cores, yielding a theoretical processing throughput of up to ~2400 DMIPS (Dhrystone MIPS) when all cores are utilized. This represents roughly a threefold increase in computational power over the previous AURIX™ generation (which achieved ~740 DMIPS with three cores).<ref name="ref19484776952">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref><ref name="ref2022357806">UDE Debug, Trace and Test solutions for Infineon TriCore™ AURIX™ TC32, TC33, TC35, TC36, TC37, TC38, TC39, TC3x Microcontrollers https://www.pls-mc.com/products/infineon-tricore-aurix-tc32-tc33-tc35-tc36-tc37-tc38-tc39-microcontrollers/</ref><ref name="ref14281090103">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref>
===Memory Subsystem and Cache===
AURIX™ TC3xx microcontrollers integrate a large on-chip memory system to meet real-time and safety requirements. Program flash memory sizes range up to 16 MB on the largest models, with over 6 MB of on-chip SRAM available for data and scratchpad usage. Each TriCore™ CPU has its own tightly-coupled local memories as well as caches: for example, each core includes a 32 KB instruction cache and a 16 KB data cache. In addition, every core has separate local RAM blocks (Harvard architecture) for instructions and data (often termed PSPR and DSPR – Program Scratch-Pad RAM and Data Scratch-Pad RAM) that allow deterministic access for time-critical routines. Shared global memory is provided via a Local Memory Unit (LMU) which can be up to several hundred kilobytes (for instance, 768 KB in the TC39x) accessible by all cores. The memory system is connected by a high-bandwidth internal bus fabric (the SRI crossbar and peripheral buses) that arbitrates access between cores, DMA engines, and peripherals. This architecture ensures that each core can quickly fetch instructions and data either from its local cache/RAM or the central memory, enabling efficient parallel processing. Memory protection hardware is also built-in to isolate tasks of different criticality, an important feature for safety and security.<ref name="ref19484776952" /><ref name="ref5727814512">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref>
===Peripherals and Interfaces===
One of the strengths of the AURIX™ TC3xx architecture is its extensive set of on-chip peripherals and interface controllers, designed to handle the complex networking and I/O needs of modern vehicles and industrial systems. Key peripheral features and interfaces include:<ref name="ref19484776952" /><ref name="ref2022357806" /><ref name="ref14281090103" /><ref name="ref3635926">AURIX™ Training System Architecture https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_System_Architecture-Training-v01_00-EN.pdf?fileId=5546d46272e49d2a0172eb476d56739e</ref>

* '''Networking Interfaces:''' Multiple CAN FD controllers (supporting up to 12 CAN-FD channels in high-end variants) for in-vehicle networking, with legacy CAN and LIN interfaces (up to 24 LIN channels) for lower-speed device communication. Many TC3xx devices also integrate up to two FlexRay controllers for time-triggered automotive networks (maintaining compatibility with earlier automotive communication standards). For high-bandwidth data, a Gigabit Ethernet MAC is included, enabling uses like automotive Ethernet (e.g., audio-video bridging and IP-based connectivity).
* '''Analog and Timers:''' A suite of analog peripherals including multiple ADC units for sensor interfacing and motor control, and DACs in some models. Sophisticated timer units are on-chip, notably the Generic Timer Module (GTM) and Capture/Compare Units (CCU6), which can generate complex PWM waveforms and handle events for engine control, power inverters, or robotics with minimal CPU intervention. These timers enable precise control of actuators (e.g. fuel injection timing, electric motor commutation) in real time.
*'''Serial Interfaces:''' SPI, I²C, UART/LIN and other serial interfaces for connecting to external sensors, actuator controllers, and memory. The controllers often support multiple instances (several SPI channels, etc.) to accommodate numerous devices. AURIX™ TC3xx also provides an external bus interface (EBU) for parallel memory or FPGA connectivity, and an SD/MMC interface (eMMC) to connect external flash memory for data logging or over-the-air update storage.
*'''Dedicated Processing Units:''' Some AURIX™ TC3xx models include special accelerators, such as a hardware Fast Fourier Transform unit (HW-FFT) and up to two Signal Processing Units (SPUs) optimized for radar signal processing. These enable the microcontroller to handle radar front-end data or other intensive DSP tasks (like Fourier transforms for radar or audio signals) on-chip, which is crucial for advanced driver assistance sensors. There is also a ''Security Module'' (covered in a later section) and a Safety Management Unit that supervise system integrity.
*'''Other On-chip Modules:''' Watchdog timers, error-correction coders for memories (ECC on flash and RAM for reliability), a programmable interrupt system, multiple DMA channels (up to 128 DMA channels) for efficient data movement, and debug interfaces (JTAG and a 2/3-pin DAP) for development. The on-chip debug system supports tracing of program execution (via a built-in Emulation Memory, MCDS) to aid in complex multicore software development.

Overall, the AURIX™TC3xx provides a highly integrated SoC-like platform, allowing a single chip to manage tasks ranging from powertrain control and chassis control to infotainment gateways. This high level of integration reduces the need for separate companion chips and helps to lower system complexity and cost.
===Performance and Benchmarking===
Fabricated in a 40 nm embedded flash process<ref name="ref2022357806" />, AURIX™ TC3xx processors achieve significant performance gains over prior generations while maintaining automotive-grade power efficiency. With six 32-bit cores at 300 MHz (four of them paired in lockstep), a flagship TC3xx device (e.g., TC39x) can deliver up to approximately 2,400 DMIPS of aggregate computing throughput<ref name="ref2022357806" />. In terms of per-core performance, the TriCore™ architecture yields around 1.3–2.0 DMIPS/MHz depending on the instruction mix, meaning each 300 MHz core can approach ~400–600 DMIPS in optimized scenarios<ref name="ref14281090103" /><ref name="ref1222155140">Infineon AURIX - Wikipedia https://en.wikipedia.org/wiki/Infineon_AURIX</ref>. This is on par with or exceeding many contemporary 32-bit automotive MCUs. The integrated DSP extensions and optional accelerators (like the FFT unit) also enable high-speed signal processing, with Infineon citing up to ~1.8 GFLOPS of DSP throughput for certain operations<ref name="ref1222155140" />.

Real-world performance improvements of the TC3xx over its predecessor are notable: for example, compared to the first-generation AURIX™ (which offered up to 740 DMIPS), the TC3xx’s expanded core count and clock speed provide roughly three times the computational power on the same type of workload<ref name="ref14281090103" />. This extra headroom allows more functions (such as running multiple control algorithms or sensor fusion tasks in parallel) to be consolidated onto one microcontroller without compromising real-time deadlines<ref name="ref14281090103" />. Despite the increase in speed and core count, the TC3xx family was designed with power and thermal constraints in mind, achieving these gains within similar power consumption envelopes as the previous generation by leveraging the smaller 40 nm process and power-saving features like clock gating<ref name="ref5727814512" />. The deterministic real-time performance (with features like lockstep and tightly-coupled memory) makes the AURIX™ TC3xx suitable for the most demanding automotive applications, where consistent low latency and high throughput are required simultaneously.

== On-Chip System Connectivity and Bridges ==
[[File:TC3xx On-Chip System Connectivity.png|thumb|The TC3xx has two '''SRI Domains''' (SRI0 and SRI1). CPU0 to CPU3 are connected to SRI0, CPU4/5 are connected to SRI1.|alt=TC3xx On-Chip System Connectivity|423x423px]]
The AURIX™ TC3xx Platform has three independent on-chip connectivity resources:

* '''System Resource Interconnect Fabric (SRI Fabric)''' connects the TriCore™ CPUs, the DMA module, and other high bandwidth requestors to high bandwidth memories and other resources for instruction fetches and data accesses. A key component of the fabric is the SRI crossbar, which connects all the agents in one SRI domain. The SRI crossbar carries the transactions between the SRI Masters and SRI Slaves of the domain. The SRI crossbar supports parallel transactions between different SRI Master and SRI Slave agents. In addition to the parallelism of concurrent requests, it also supports pipelined requests from an SRI Master to a SRI Slave.
* '''System Peripheral Bus (SPB)''' connects the TriCore™ CPUs, the DMA module, and other SPB masters to the medium and low bandwidth peripherals. SPB masters do not directly connect to the SRI Fabric, and will access SRI attached resources via a SFI_F2S Bridge.
* '''Back Bone Bus (BBB)''' connects the TriCore™ CPUs, the DMA module, and SPB masters with ADAS resources. SRI Masters do not directly connect to the BBB, but access BBB attached resources via a SFI_S2F Bridge. SPB masters also do not directly connect to the BBB, but access BBB attached resources via bridging over the SRI Fabric.

=== CPU Resource Access Times ===
These tables describe the CPU access times to various resources in CPU clock cycles for the AURIX™ TC3xx Platform. In the case of load or fetch accesses, the access times are the minimum number of CPU stall cycles to complete the access. If there is a conflict for the resource accessed, there may be additional stall cycles till the conflicting access completes.

For write access, the access times are the maximum for a sequence of such access (non-conflicting). In many cases for a singleton access, or a short sequence, write buffering reduces the stall effect seen by a CPU, sometimes to 0. However, as with loads and fetches, if there is a conflict for the resource accessed, there may be additional stall cycles till the conflicting access completes.

==== Access latency for global resources ====
{| class="wikitable"
|+
! CPU Access Type !! CPU stall cycles
!Notes
|-
| Data read from System Peripheral Bus (SPB) || <math>\frac{f_\text{CPU}}{f_\text{SPB}} \cdot (4 + \text{Module Wait State})</math>
| rowspan="2" |The final number of stall cycles will depend on the real number of WS generated by the target resource.
|-
| Data write to System Peripheral Bus (SPB) || <math>\frac{f_\text{CPU}}{f_\text{SPB}} \cdot (4 + \text{Module Wait State})</math>
|-
| Data read from Back Bone Bus (BBB) (TC39x, TC37xED) || <math>9 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (5 + \text{Module Wait State})</math>
| rowspan="2" |When SFI_S2F is connected to XBar2 (TC39x and TC37xED) there is an additional latency due to access going through an S2S.
|-
| Data write to Back Bone Bus (BBB) (TC39x, TC37xED) || <math>5 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (4 + \text{Module Wait State})</math>
|-
| Data read from Back Bone Bus (BBB) (TC35x, TC33xED) || <math>6 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (5 + \text{Module Wait State})</math>
|
|-
| Data write to Back Bone Bus (BBB) (TC35x, TC33xED) || <math>3 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (4 + \text{Module Wait State})</math>
|
|}


* '''Module Wait State''': The number of wait states for read and for write accesses is >= 1 and depends on the accessed module and its configuration.


==== CPU Accesses: Stall cycles for local and SRI resources ====
{| class="wikitable"
|+
! CPU Access Type !! Local CPU !! Local SRI !! Remote SRI Domain
|-
| Data read from DSPR || 0 || 7 || 10
|-
| Data write to DSPR || 0 || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from DSPR || See local SRI column || 7 || 10
|-
| Data read from DLMU || 0 || 7 || 10
|-
| Data write to DLMU || 2 || 5, {{rev|3|with Pipelining}}|| 5, 4
|-
| Instruction fetch from DLMU || See local SRI column || 7 || 10
|-
| Data read from PSPR || See local SRI column || 7 || 10
|-
| Data write to PSPR || See local SRI column || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from PSPR || 0 || 7 || 10
|-
| Data read from PFlash || 5 + PWS || 10 + PWS || 13 + PWS
|-
| Instruction fetch from PFlash (buffer miss) || 2 + PWS || 9 + PWS || 12 + PWS
|-
| Instruction fetch from PFlash (buffer hit) || 3 || 6 || 9
|-
| Data read from LMU || n.a. || 7 || 10
|-
| Data write to LMU || n.a. || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from LMU || n.a. || 7 || 10
|-
| Data read from DFlash || n.a. || 5 + 3*(3 + DCWS) || 8 + 3*(3 + DCWS)
|-
| Data read access from EMEM (TC39x, TC37xED) || n.a. || n.a. || 14, {{rev|15|fBBB < fSRI}}
|-
| Data write access to EMEM (TC39x, TC37xED) || n.a. || n.a. || 9
|-
| Data read access from EMEM (TC35x, TC33xED) || n.a. || 11, {{rev|12|fBBB < fSRI}}|| n.a.
|-
| Data write access to EMEM (TC35x, TC33xED) || n.a. || 9 || n.a.
|-
| Data read access from DAM || n.a. || 10 || 13
|-
| Data write access to DAM || n.a. || 7 || 7
|}

* '''Remote SRI Domain''': Only applies to products with SRI extenders. Additional latency due to access going through an S2S
* '''PWS''': Configured PFlash Wait States (Includes cycles for PFlash access cycles only). ECC correction latency is only incurred when the incoming data requires ECC correction.
* '''PWS''': Configured PFlash Wait States (Includes cycles for PFlash access cycles only). ECC correction latency is only incurred when the incoming data requires ECC correction.
* '''DCWS''': Configured DFlash Corrected Wait States (Includes cycles for DFlash access cycles and ECC correction latency)

== CPU Subsystem ==
[[File:TC3xx Processor Core, Local Memory and Connectivity.png|alt=TC3xx Processor Core, Local Memory and Connectivity|thumb|Processor Core, Local Memory and Connectivity]]The Infineon AURIX™ TC3xx features up to 6 processor cores (CPU0 ... CPU5) implementing the [[TriCore Instruction Set Architecture|TC1.6.2 instruction set architecture]]. The following section focuses on the microarchitectural details of the CPU subsystem. For more information about the ISA, please take a look at the [[TriCore Instruction Set Architecture]].

The processor core connects to the following memories and bus interfaces (where implemented):
*Program Scratch-Pad SRAM (PSPR)
*Data Scratch-Pad SRAM (DSPR)
*Program Cache (PCache)
*Data Cache (DCache)
*Local Memory Unit (DLMU)
*Local Pflash bank (LPB)
*SRI slave interface (x2)
*SRI master Interface
*SPB master interface

=== TC1.6.2P Implementation Features ===
*Most instructions executed in 1 cycle
*Branch instructions in 1, 2 or 3 cycles (using dynamic branch prediction)
*Wide memory interface for fast context switch
* Automatic context save-on-entry and restore-on-exit for: subroutine, interrupt, trap
*Six memory protection register sets
*Dual instruction issuing (in parallel into Integer Pipeline and Load/Store Pipeline)
*Third pipeline for loop instruction only (zero overhead loop)
*Single precision Floating Point Unit (IEEE-754 Compatible)
*Dedicated Integer divide unit
*18 data memory protection ranges, 10 code memory protection ranges arranged in 6 sets

=== Superscalar Architecture ===
The processor core within the AURIX™ TC3xx family, specifically the TC1.6.2P implementation, employs a superscalar architecture characterized by three parallel pipelines: the Integer Pipeline, the Load/Store Pipeline, and the Loop Pipeline. Superscalar execution is a form of instruction-level parallelism that enables the processor to issue and execute multiple instructions during a single clock cycle. The TriCore™ TC3xx core's superscalar architecture allows it to issue and execute multiple instructions in parallel. Specifically, it can issue up to two instructions simultaneously to the Integer and Load/Store pipelines. However, there are certain constraints on this dual issuing capability. For example, back-to-back data arithmetic instructions can only be issued in separate cycles, and a load/store instruction can be issued either on its own or paired with a data arithmetic instruction, provided the load/store instruction is the second in the pair. Under ideal conditions, with careful instruction scheduling, this dual-issue capability can lead to a throughput of close to 0.5 clock cycles per instruction, effectively executing two instructions per cycle.

=== Pipeline Stages ===
The execution of instructions within the TriCore™ TC3xx core is managed through a pipeline consisting of several stages. In one document it is mentioned that the pipeline consists of 6 stages <ref name="ref3635926" />, but the exact stages remain unclear. From the architecture the following stages can be inferred:

* '''Fetch Stage''': The initial stage in the pipeline is the Fetch stage, where instructions are retrieved from memory. This task is handled by the Instruction Fetch Unit (IFU), which is responsible for fetching instructions from the memory system. To improve efficiency, the IFU employs a pre-fetching mechanism, anticipating the instructions that will be needed and bringing them into the processor before they are actually required. Instructions are fetched through a 64-bit wide Program Memory Interface (PMI), allowing for the retrieval of a significant amount of instruction data in each cycle. The fetched instructions are then placed into an issue FIFO, a buffer capable of holding up to six instructions. This buffer plays a crucial role in managing the flow of instructions to the subsequent execution pipelines. The 64-bit fetch width and the instruction buffer are indicative of a design that aims to ensure a continuous supply of instructions to the pipelines, preventing them from being starved of work. A wider fetch path allows for more instruction bits to be obtained from memory in each clock cycle, while the buffer helps to mitigate temporary delays in instruction fetching.
* '''Execution Unit''': The Execution Unit contains the Integer Pipeline, the Load/Store Pipeline and the Loop Pipeline. All three pipelines operate in parallel and are capable of executing instructions simultaneously. Each pipline has its own decode stage and two execute stages. Furthermore, the TC3xx features a Floating Point Unit (FPU). It is not clear whether the FPU is part of the execution unit or a separate unit. It is assumed that the FPU also has its own decode stage and an unknown number of execute stages
** '''Decode Stage''': Following the Fetch stage, the instruction are issued to one of the pipelines. In the decode stage of each pipeline, the instruction is examined and translated to determine the specific operation it represents and to identify the operands it will operate on. It is assumed that operands are read from the register file during the decode stage.
** '''Execute Stage''': The Execute stage is where the actual operation specified by the instruction is carried out. Pipeline hazards (stalls) are minimised by the use of forwarding paths between pipeline stages allowing the results of one instruction to be used by a following instruction as soon as the result becomes available.
** '''Writeback Stage''': The final stage in the pipeline is the Writeback stage. In this stage, the results produced by the executed instruction are written back to the processor's register file, making them available for subsequent instructions. It is unclear whether the writeback stage is part of the (two) execution stages or a separate stage.

=== Execution Pipelines ===
The TriCore™ TC3xx core leverages four parallel pipelines to enhance its performance. Each pipeline is designed to handle a specific class of instructions:

* '''Integer Pipeline:''' This pipeline is responsible for executing integer arithmetic and logical instructions, including data-conditional jump instructions, bit manipulation operations, as well as division and multiply-accumulate (MAC) instructions.
* '''Load/Store Pipeline:''' The primary function of this pipeline is to manage memory access operations, including loading data from memory and storing data to memory. It also handles address arithmetic, unconditional jump instructions, procedure call instructions, context-switching operations, and control flow related to context save areas (CSAs).
* '''Loop Pipeline:''' This is a specialized pipeline designed to facilitate zero-overhead loops, a technique that significantly improves the performance of iterative code sections. Its design aims to eliminate or minimize the overhead typically associated with loop control, such as incrementing counters and checking loop conditions. Some documentation suggests that the loop pipeline comes along with a "Loop Cache". This dedicated cache would likely be used to store instructions belonging to the loop, enabling very fast access and execution for repeated iterations.
* '''Floating Point Unit (FPU):''' The FPU is responsible for executing floating-point arithmetic operations

=== Store Buffers ===
The TriCore™ TC3xx core include '''Store Buffers''' to decouple memory write operations from CPU instruction execution. All stores from the Load/Store Pipeline are placed in the store buffer prior to being written to local memory or transferred via the bus system. Write data is taken from the store buffers and written to memory when the target memory or bus interface becomes available. In normal operation the CPU will prioritise memory load operations over store operations in order to improve performance unless the store buffer is full or the order of load and store operations must be preserved (e.g. peripheral space access). The store buffer can hold the data for up to 6 stores operations. To improve performance the store buffer will merge consecutive byte, half-word, and word writes of the same location to reduce the number of memory accesses required.

=== Instruction Timing ===

==Functional Safety and Security Features==
===Hardware Security Module and Encryption===
One of the defining features of the AURIX™ TC3xx family is its robust hardware-based security subsystem, implemented to protect against cyber threats and unauthorized manipulation of vehicle systems. Each TC3xx MCU includes a dedicated ''Hardware Security Module'' (HSM), which is essentially an on-chip co-processor with its own CPU and cryptographic engine designed to handle secure operations. In the second-generation AURIX™ (TC3xx), the HSM was upgraded with support for asymmetric cryptography (e.g., RSA, ECC algorithms) in hardware, providing significantly faster public-key encryption and authentication capabilities than pure software implementations. This HSM supports '''EVITA Full''' (the highest level of the EU’s EVITA automotive security requirements), meaning it can perform secure boot, message authentication, and encryption at a level suitable for protecting critical in-vehicle communications. For example, the HSM can encrypt and authenticate CAN/Ethernet messages to prevent spoofing or tampering on the vehicle network, and it can manage cryptographic keys securely isolated from the main application cores.<ref name="ref14281090104">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref2022357806" />

The security module enables features like '''secure boot''', where the AURIX™ will only execute firmware that is digitally signed by the vehicle manufacturer, thereby preventing unauthorized or malicious code. It also facilitates ''over-the-air (OTA) updates'' in a secure manner: the TC3xx HSM can verify and decrypt update packages received via telematics, allowing firmware upgrades while protecting against attackers attempting to hijack the software. In addition, the HSM includes a true random number generator and supports protocols for immobilizer and theft protection systems. Infineon’s implementation essentially treats the HSM as an “embedded smart card” inside the microcontroller. This approach, building on Infineon’s expertise in chip card security, helps to safeguard sensitive assets like cryptographic keys and to perform secure operations (encryption, decryption, authentication) in hardware, making attacks significantly more difficult. The strong cybersecurity provisions of the AURIX™ TC3xx have made it a preferred choice for vehicle gateway ECUs and central body controllers, which are points of entry for connected car communications and thus high-value targets for hackers. By incorporating the HSM, automotive OEMs can implement advanced security features such as encrypted onboard communication (to thwart bus tampering) and secure diagnostics, ensuring the vehicle’s electronic data is protected against cyber threats even as cars become more connected.<ref name="ref14281090104" /><ref name="ref5727814513">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref><ref name="ref19484776953">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref>
=== Functional Safety and Fault Tolerance===
Beyond cybersecurity, the AURIX™ TC3xx architecture is built with extensive ''functional safety'' features to meet the highest safety integrity levels in automotive systems. The multi-core design supports ''lockstep operation'', where redundant checker cores run in parallel with main cores and continuously compare results cycle-by-cycle. In TC3xx devices, up to four of the six TriCore™ CPUs have such lockstep partner cores, allowing the microcontroller to detect any single-point CPU failure instantly (if a discrepancy arises between the core and its checker, a fault is signaled). A ''Safety Management Unit (SMU)'' is integrated on-chip to monitor various fault conditions throughout the device – it aggregates error signals from the lockstep cores, memory ECC monitors, clock/watchdog monitors, and peripheral self-tests, and can initiate safe-state actions (like resetting the chip or signaling an error pin to an external supervisor) if a critical fault is detected. The AURIX™ safety concept also includes a distributed Memory Protection Unit (MPU) arrangement, with multiple memory protection contexts that prevent errant or malicious code from writing to wrong memory areas. This helps contain faults and eases the integration of software with mixed criticality (Infineon allows partitioning software components of different ASIL levels on the same MCU while keeping them isolated).<ref name="ref14281090104" /><ref name="ref5727814513" /><ref name="ref19519075552">Safety Microcontrollers: Texas Instruments Hercules vs Infineon AURIX https://www.linkedin.com/pulse/safety-microcontrollers-texas-instruments-hercules-vs-cook-meng-miet</ref>

Crucially, the TC3xx family was developed according to ISO 26262 processes and can achieve '''ASIL-D''' (Automotive Safety Integrity Level D), the highest grade for automotive functional safety. Compared to a traditional dual-core lockstep approach, the AURIX’s™ multi-core safety architecture allowed Infineon to reduce certain safety development overheads (earlier Infineon data suggested up to 30% reduction in safety software workload) by providing built-in safety mechanisms and diagnostics. Infineon supplies a comprehensive safety manual and diagnostic libraries for the AURIX™, helping engineers utilize features like CPU self-tests, RAM tests, and CRC checks to comply with safety standards. In addition to automotive standards, the AURIX™ TC3xx has also been qualified for '''industrial safety''': in 2023, Infineon announced support for IEC 61508 metrics, enabling designs with AURIX™ to reach SIL-2 and SIL-3 safety integrity levels for industrial applications. This cross-industry safety compliance is facilitated by the MCU’s redundant design and detailed failure mode documentation (FMEDA) provided by Infineon. In summary, the AURIX™ TC3xx integrates both proactive safety (fault prevention via lockstep, monitoring and protection) and reactive safety (fault detection and safe shutdown), making it a dependable component for systems that cannot afford unintended behavior, whether in cars, factories, or aerospace. <ref name="ref14281090104" /><ref name="ref5727814513" /><ref name="ref4967712052">Infineon's AURIX™ & TRAVEO™ microcontroller families extend their support for IEC 61508 hardware and software metrics enabling industrial safety up to SIL-3 - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2023/INFATV202303-078.html</ref><ref name="ref196858272">MCUs support industrial functional safety - Electronic Products https://www.electronicproducts.com/mcus-support-industrial-functional-safety/</ref>
== Platform Devices ==
The following table shows a feature overview of the AURIX™ TC3xx Platform family focusing on memory and number of cores.
{| class="wikitable"
!
!Feature
!TC33x
!TC33xEXT
!TC35x
!TC36x
!TC37x
!TC37xEXT
!TC38x
!TC39x
|-
| rowspan="2" |CPUs
|Cores / Checker Cores
|1 / 1
|2 / 1
|3 / 2
|2 / 2
|3 / 2
|3 / 3
|4 / 2
|6 / 4
|-
|Max. Freq.
| colspan="8" |300 MHz
|-
| rowspan="2" |Cache per CPU
|Program [KB]
| colspan="8" |32
|-
|Data [KB]
| colspan="8" |16
|-
| rowspan="3" |SRAM per CPU
|PSPR [KB]
|8
|{{rev|32|CPU0}}
{{rev|64|other}}
|64
|32
|64
|64
|64
|64
|-
|DSPR [KB]
|192
|{{rev|192|CPU0}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|192
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|-
|DLMU [KB]
|8
|{{rev|8|CPU0}}
{{rev|64|other}}
|64
|64
|64
|64
|64
|64
|-
| rowspan="2" |SRAM global
|LMU [KB]
| -
| -
|512
| -
| -
| -
|128
|768
|-
|DAM [KB]
| -
| -
|32
| -
|64
|64
|128
|128
|-
| rowspan="3" |Extension Memory (EMEM)
|TCM [MB]
| -
|1
|2
| -
| -
|2
| -
|2
|-
|XCM [MB]
| -
| -
| -
| -
| -
|1
| -
|2
|-
|XTM [KB]
| -
|16
|16
| -
| -
|16
| -
|16
|-
| rowspan="2" |Program Flash
|Size [MB]
|2
|4
|4
|4
|6
|10
|10
|16
|-
|Banks [MB]
|1 x 2
|2 x 2
|2 x 2
|2 x 2
|2 x 3
|3 x 3, 1 x 1
|3 x 3, 1 x 1
|5 x 3, 1 x 1
|-
| rowspan="2" |Data Flash
|DF0 Size (single-ended) [KB]
|128
|128
|128
|128
|256
|512
|512
|1024
|-
|DF1 Size (single-ended) [KB]
|128
|128
|128
|128
|128
|128
|128
|128
|-
| rowspan="3" |DMA
|Channels
|64
|64
|64
|64
|128
|128
|128
|128
|-
|Move Engines
|2
|2
|2
|2
|2
|2
|2
|2
|-
|Resource Partitions
|4
|4
|4
|4
|4
|4
|4
|4
|}

== Compilers ==
The AURIX™ TC3xx family is a series of high-performance microcontrollers widely used in automotive and industrial applications. Compilers for the AURIX™ TC3xx are crucial for developers aiming to optimize performance, reliability, and safety in their applications. One significant aspect of the compiler landscape for AURIX™ TC3xx is the limited direct support from mainline open-source compilers such as GCC or LLVM/Clang. The primary reason for this is the stringent requirements for functional safety in automotive and industrial applications, which demand specialized features and compliance with safety standards that are often not met by general-purpose open-source compilers.

=== Commercial Compilers ===

# '''Tasking''': Tasking compilers are renowned for their robust support for automotive applications, offering advanced debugging capabilities and optimization techniques tailored for the AURIX™ architecture. They provide extensive code optimization, comprehensive debugging tools, and strong support for safety standards such as ISO 26262, making them ideal for developing high-performance, reliable, and safe applications.
# '''HighTec''': The HighTec compiler is a popular choice, known for its Eclipse-based development environment and strong multicore support. HighTec provides both GCC and LLVM-based ports of open-source compilers tailored specifically for the AURIX™ TC3xx family. These compilers offer efficient parallel execution, advanced code analysis, and an integrated development environment, ensuring robust performance and compliance with safety standards.
# '''Green Hills Software''': Green Hills Software provides a highly optimized toolchain aimed at safety-critical applications, focusing on high performance and strict compliance with automotive standards. Their compiler offers superior optimization, extensive safety features, and a proprietary IDE with specialized tools for automotive development, ensuring developers can meet the stringent demands of functional safety.

=== GCC for AURIX™ ===

While mainline GCC does not directly support the AURIX™ TC3xx family, there is an unofficial GCC version available for AURIX™. Due to the GNU General Public License (GPL), the source code from HighTec was retrieved and, along with binary versions, published on GitHub:

*Infineon's release of GCC for Aurix with [https://softwaretools.infineon.com/tools/com.ifx.tb.tool.aurixgcc binaries for both Linux and Windows] and Infineon's instruction set simulator [https://softwaretools.infineon.com/tools/com.ifx.tb.tool.tsimtricoreinstructionsetsimulator TSim] for Aurix.
*GCC 4.9.4/Binutils 2.20/Newlib 1.18 for Tricore™ AURIX™ [[https://github.com/volumit/package_494 Source]] [[https://github.com/volumit/tricore_gcc494_mingw_bins Prebuild Mingw Binaries]] [[https://github.com/volumit/tricore_gcc494_linux_bins Prebuild Linux Binaries]]
*GCC 9.4.0/Binutils 2.20/Newlib 1.18 for Tricore™ AURIX™ [[https://github.com/volumit/package_940 Source]] [[https://github.com/volumit/tricore_gcc940_mingw_bins Prebuild Mingw Binaries]] [[https://github.com/volumit/tricore_gcc940_linux_bins Prebuild Linux Binaries]]
*EEESLab's repositories of GCC, Binutils and Newlib for Tricore™ AURIX™ [[https://github.com/EEESlab/tricore-gcc-toolchain-11.3.0 Source]]
*NoMore201's fork of EEESLab's GCC for Tricore™ AURIX™ including GCC, Binutils, Newlib, GDB and QEmu [[https://github.com/NoMore201/tricore-gcc-toolchain Source]] [[https://github.com/NoMore201/tricore-gcc-toolchain/releases/tag/11.3.1-20250101 Sources and prebuilt binaries of gcc-11.3.1 for Linux and Windows]] [[https://github.com/NoMore201/tricore-gcc-toolchain/releases/tag/13.3-20250516 Sources and prebuilt binaries of gcc-13.3.0 for Linux and Windows]]
*GDB 10.0.50 for Tricore™ AURIX™ [[https://github.com/volumit/gdb-tricore Source]]
==emmtrix Tools for AURIX™ TC3xx==
[[File:lowres-Signet Associated Partner EN.eps.png|thumb|305x305px|emmtrix Technologies is an Infineon Associated Partner with over 10 years of experience working with the '''Infineon AURIX™ microcontroller family''' and has been actively collaborating with Infineon for the past five years.|alt=emmtrix Associated Partner]]
emmtrix offers the following tool for the Infineon AURIX™ TC3xx architecture:
=== emmtrix Performance Estimator ===
[[emmtrix Performance Estimator|emmtrix Performance Estimator (ePE)]] provides static timing analysis of C code. Compared to simulation or measurement on hardware, static performance analysis can be applied significantly earlier in the development process and will deliver results on average 6 months earlier compared to a typical automotive HIL setup. The analysis only takes a few minutes at most and runs on the developer’s PC independently of any target hardware. Function developers can analyze their runnables or SWCs without the need of a fully integrated program. emmtrix Performance Estimator is fully compatible with '''Infineon's AURIX™ [[Infineon AURIX TC2xx|TC2xx]] / TC3xx/ [[Infineon AURIX TC4x|TC4x]] microcontroller family,''' ensuring precise and reliable performance analysis for embedded systems.

A unique feature is the combination with TargetLink or Embedded Coder generated code. Without any measurement overhead, our static performance estimation can analyze even the smallest code snippets. This allows us to map the timing analysis to Simulink blocks, giving function developers insight into the timing behavior of their models.

ePE offers three accuracy levels:

* analysis of C code
* generically compiler-optimized code
* assembly code from the target compiler.

Method 1 yields results with minimum effort while method 3 takes the timing of the processor pipeline into account. All methods offer excellent reliability when tracking the tendency of changes in software runtimes e.g. when used in a continuous integration environment.

=== Services ===
====Architecture & Variant Consulting====
* Support in selecting suitable AURIX derivatives for new product generations (trade-offs between performance, price, safety, and peripheral features)
*Analysis of requirements and mapping to specific AURIX product families (e.g., TC3xx vs. TC4xx)
*Analysis/identification of performance margins for down- or upgrades
==== Runtime Analysis & Performance Engineering ====
* Execution of detailed runtime analyses (maximum/minimum vs. average)
* Identification of bottlenecks in program execution, including benchmarking
*Optimization of access to flash, RAM, and peripherals (e.g., cache configuration, DMA utilization)
====Dependency Analysis====
*Freedom from interference (ASIL level check)

==== Multicore Design & Scheduling Concepts ====

* Development of core mapping strategies (static vs. dynamic assignment of compute-intensive tasks)

*Support for integrating bare-metal scheduling on AURIX
*Assistance with architectural decisions to meet functional safety requirements in multicore systems

==== Training & Know-how Transfer ====

* Technical in-house workshops on AURIX optimization, multicore strategies

*Coaching of employees/project teams in performance analysis and systematic tuning
==See Also==

*[[Infineon AURIX TC4x|Infineon AURIX™ TC4x]]
*[[Infineon AURIX TC2xx|Infineon AURIX™ TC2xx]]
*[[TriCore Instruction Set Architecture]]

==External Links==

*https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/
*[https://documentation.infineon.com/aurixtc3xx/docs/qmd1702366622648 AURIX™ TC3xx user manuals]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Part1-UserManual-v02_00-EN.pdf?fileId=5546d462712ef9b701717d3605221d96 AURIX™ TC3xx User Manual Part-1]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Part2-UserManual-v02_00-EN.pdf?fileId=5546d462712ef9b701717d35f8541d94 AURIX™ TC3xx User Manual Part-2]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Architecture_vol1-UserManual-v01_00-EN.pdf?fileId=5546d46276fb756a01771bc4c2e33bdd AURIX™ TC3xx Architecture vol 1]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Architecture_vol2-UserManual-v01_00-EN.pdf?fileId=5546d46276fb756a01771bc4a6d73b70 AURIX™ TC3xx Architecture vol 2]

== References ==
<references />
[[Category:Supported Architectures]]

{{#seo:
|title=Infineon AURIX TC3xx Family – Deep Dive
|description=This deep dive into Infineon's AURIX TC3xx family explores its multi-core TriCore architecture, real-time capabilities, safety and security features and tools
|image=File:AURIX_TC399_LFBGA-516_plain.jpg
|keywords=AURIX, Infineon, TC3xx, microcontroller, TriCore, automotive, ADAS, ISO 26262, functional safety, embedded security, ASIL-D, deep dive
}}

Infineon AURIX TC3xx

2025-07-04T07:03:46Z

Tobias.columbus: /* GCC for AURIX™ */

[[File:AURIX TC399 LFBGA-516 plain.jpg|thumb|Infineon AURIX™ TC3xx second-generation microcontroller (TC399 BGA package). The AURIX™ TC3xx family integrates multiple TriCore™ CPUs and on-chip safety/security modules for automotive applications.|alt=TC399 BGA package]]
The '''Infineon AURIX™ TC3xx''' (Automotive Realtime Integrated neXt-generation architecture) is a family of 32-bit automotive microcontrollers introduced as the second generation of Infineon’s AURIX™ platform. Launched in 2016 as a successor to the earlier [[Infineon AURIX TC2xx|AURIX™ TC2xx series]], the TC3xx devices emphasize high performance, functional safety, and embedded security for advanced automotive and industrial applications. AURIX™ TC3xx microcontrollers feature a hexa-core [[TriCore Instruction Set Architecture|''TriCore'' processor architecture]] with enhanced safety measures, making them well-suited for demanding tasks such as autonomous driving domain controllers, powertrain control, and sensor data fusion in advanced driver-assistance systems (ADAS). The combination of multiple CPU cores, extensive on-chip memory, and a rich peripheral set allows TC3xx chips to deliver real-time responsiveness and reliability in safety-critical environments while meeting stringent automotive standards (such as ISO 26262 for functional safety).<ref name="ref1951907555">Safety Microcontrollers: Texas Instruments Hercules vs Infineon AURIX https://www.linkedin.com/pulse/safety-microcontrollers-texas-instruments-hercules-vs-cook-meng-miet</ref><ref name="ref1428109010">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref1948477695">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref>
==Applications==
AURIX™ TC3xx microcontrollers are used in a variety of safety-critical and high-performance applications across the automotive and industrial sectors. Key application domains include:
*'''Automotive Systems:''' The TC3xx family was primarily designed for automotive use and finds broad application in vehicles’ electronic control units (ECUs). Notably, it is used in ''powertrain and drivetrain control'' (engine management, transmission control, hybrid/electric vehicle inverter control, battery management) where its real-time processing and resilience support precise actuator control. It is also deployed in ''chassis and safety systems'' such as anti-lock braking systems (ABS), electronic stability control, airbag controllers, and electric power steering, leveraging its redundancy and fast response for fail-safe operation. With the growth of ADAS and autonomous driving, AURIX™ TC3xx devices serve as domain controllers for ''ADAS sensor fusion'', handling data from radar, LiDAR, camera, and ultrasonic sensors and performing environment modeling and decision-making algorithms. Their combination of multiple cores and a built-in radar signal processing sub-system makes them an attractive choice for tasks like front radar processing, sensor fusion hubs, and ''autonomous driving domain controllers'' that must meet ASIL-D safety levels.<ref name="ref14281090102">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref572781451">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref>
*'''Industrial Automation and Robotics:''' Infineon has also positioned the AURIX™ family for use in industrial applications that demand high reliability. The TC3xx MCUs, with their hardware self-test mechanisms and safety documentation, can be found in ''industrial motor drives, robotics controllers, and PLCs (programmable logic controllers)'', where they help achieve functional safety certifications up to SIL-3 (according to IEC 61508). The powerful TriCore™ cores and rich peripheral set enable complex motor control algorithms (e.g., field-oriented control for servo motors) and real-time sensor processing in factory automation. Additionally, the support for automotive-grade networking (CAN/CAN-FD, Ethernet) and timing peripherals makes them suitable for synchronous control in robotics and machinery. Infineon’s provision of AUTOSAR-compatible software for AURIX™ has even facilitated its use in non-automotive settings such as medical devices and elevator controllers, where proven safety and security are required.<ref name="ref496771205">Infineon's AURIX™ & TRAVEO™ microcontroller families extend their support for IEC 61508 hardware and software metrics enabling industrial safety up to SIL-3 - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2023/INFATV202303-078.html</ref>
*'''Aerospace and Defense:''' The high fault-tolerance and deterministic performance of the AURIX™ TC3xx architecture also attract interest for aerospace and other mission-critical uses. In avionics systems or autonomous drones, for instance, the lockstep core configuration and robust error checking of AURIX™ can provide an added layer of reliability for flight control computers or navigation systems. While primarily an automotive chip, its ability to operate in harsh conditions (−40°C to 150°C range) and to detect internal failures in real-time makes it viable for certain aerospace electronic systems. Some defense and aerospace projects leverage COTS (commercial off-the-shelf) automotive components like AURIX™ for applications such as unmanned vehicle control and high-reliability communication links, given its safety pedigree. (In these domains, additional analysis and possibly radiation testing would be performed if the devices are used in high-altitude or space environments.)
== Architecture Overview ==
[[File:Infineon TC3xx Architecture.webp|545x545px|thumb|alt=TC3xx Architecture Overview|TC3xx Architecture Overview]]
=== Processor Cores and Architecture===
The AURIX™ TC3xx family implements Infineon’s TriCore™ architecture, which uniquely combines aspects of RISC microcontrollers, DSP (digital signal processor) capabilities, and conventional microprocessor features into a single core design. Each TC3xx device can include up to six independent TriCore™ 32-bit CPU cores (TriCore™ version 1.6.2), all capable of running at up to 300 MHz clock frequency. Four of these cores can operate in dual-core lockstep pairs (with one core acting as a redundant checker for its partner) to provide fault detection for safety-critical functions. The TriCore™ cores use a superscalar Harvard architecture with 32-bit instruction words (and support for mixed 16/32-bit instruction encoding for code density). Each core includes a dedicated Floating Point Unit (FPU) for single-precision arithmetic and supports DSP-oriented instructions (e.g. single-cycle 16×16 MAC operations, SIMD for 16-bit/8-bit data) to accelerate signal processing tasks. For fast real-time performance, the architecture offers low interrupt latency (with automatic context save on-chip) and features like zero-overhead loops and a programmable peripheral timer unit for scheduling tasks. In total, a high-end TC3xx (such as the TC39x) provides six 300 MHz cores plus four checker cores, yielding a theoretical processing throughput of up to ~2400 DMIPS (Dhrystone MIPS) when all cores are utilized. This represents roughly a threefold increase in computational power over the previous AURIX™ generation (which achieved ~740 DMIPS with three cores).<ref name="ref19484776952">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref><ref name="ref2022357806">UDE Debug, Trace and Test solutions for Infineon TriCore™ AURIX™ TC32, TC33, TC35, TC36, TC37, TC38, TC39, TC3x Microcontrollers https://www.pls-mc.com/products/infineon-tricore-aurix-tc32-tc33-tc35-tc36-tc37-tc38-tc39-microcontrollers/</ref><ref name="ref14281090103">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref>
===Memory Subsystem and Cache===
AURIX™ TC3xx microcontrollers integrate a large on-chip memory system to meet real-time and safety requirements. Program flash memory sizes range up to 16 MB on the largest models, with over 6 MB of on-chip SRAM available for data and scratchpad usage. Each TriCore™ CPU has its own tightly-coupled local memories as well as caches: for example, each core includes a 32 KB instruction cache and a 16 KB data cache. In addition, every core has separate local RAM blocks (Harvard architecture) for instructions and data (often termed PSPR and DSPR – Program Scratch-Pad RAM and Data Scratch-Pad RAM) that allow deterministic access for time-critical routines. Shared global memory is provided via a Local Memory Unit (LMU) which can be up to several hundred kilobytes (for instance, 768 KB in the TC39x) accessible by all cores. The memory system is connected by a high-bandwidth internal bus fabric (the SRI crossbar and peripheral buses) that arbitrates access between cores, DMA engines, and peripherals. This architecture ensures that each core can quickly fetch instructions and data either from its local cache/RAM or the central memory, enabling efficient parallel processing. Memory protection hardware is also built-in to isolate tasks of different criticality, an important feature for safety and security.<ref name="ref19484776952" /><ref name="ref5727814512">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref>
===Peripherals and Interfaces===
One of the strengths of the AURIX™ TC3xx architecture is its extensive set of on-chip peripherals and interface controllers, designed to handle the complex networking and I/O needs of modern vehicles and industrial systems. Key peripheral features and interfaces include:<ref name="ref19484776952" /><ref name="ref2022357806" /><ref name="ref14281090103" /><ref name="ref3635926">AURIX™ Training System Architecture https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_System_Architecture-Training-v01_00-EN.pdf?fileId=5546d46272e49d2a0172eb476d56739e</ref>

* '''Networking Interfaces:''' Multiple CAN FD controllers (supporting up to 12 CAN-FD channels in high-end variants) for in-vehicle networking, with legacy CAN and LIN interfaces (up to 24 LIN channels) for lower-speed device communication. Many TC3xx devices also integrate up to two FlexRay controllers for time-triggered automotive networks (maintaining compatibility with earlier automotive communication standards). For high-bandwidth data, a Gigabit Ethernet MAC is included, enabling uses like automotive Ethernet (e.g., audio-video bridging and IP-based connectivity).
* '''Analog and Timers:''' A suite of analog peripherals including multiple ADC units for sensor interfacing and motor control, and DACs in some models. Sophisticated timer units are on-chip, notably the Generic Timer Module (GTM) and Capture/Compare Units (CCU6), which can generate complex PWM waveforms and handle events for engine control, power inverters, or robotics with minimal CPU intervention. These timers enable precise control of actuators (e.g. fuel injection timing, electric motor commutation) in real time.
*'''Serial Interfaces:''' SPI, I²C, UART/LIN and other serial interfaces for connecting to external sensors, actuator controllers, and memory. The controllers often support multiple instances (several SPI channels, etc.) to accommodate numerous devices. AURIX™ TC3xx also provides an external bus interface (EBU) for parallel memory or FPGA connectivity, and an SD/MMC interface (eMMC) to connect external flash memory for data logging or over-the-air update storage.
*'''Dedicated Processing Units:''' Some AURIX™ TC3xx models include special accelerators, such as a hardware Fast Fourier Transform unit (HW-FFT) and up to two Signal Processing Units (SPUs) optimized for radar signal processing. These enable the microcontroller to handle radar front-end data or other intensive DSP tasks (like Fourier transforms for radar or audio signals) on-chip, which is crucial for advanced driver assistance sensors. There is also a ''Security Module'' (covered in a later section) and a Safety Management Unit that supervise system integrity.
*'''Other On-chip Modules:''' Watchdog timers, error-correction coders for memories (ECC on flash and RAM for reliability), a programmable interrupt system, multiple DMA channels (up to 128 DMA channels) for efficient data movement, and debug interfaces (JTAG and a 2/3-pin DAP) for development. The on-chip debug system supports tracing of program execution (via a built-in Emulation Memory, MCDS) to aid in complex multicore software development.

Overall, the AURIX™TC3xx provides a highly integrated SoC-like platform, allowing a single chip to manage tasks ranging from powertrain control and chassis control to infotainment gateways. This high level of integration reduces the need for separate companion chips and helps to lower system complexity and cost.
===Performance and Benchmarking===
Fabricated in a 40 nm embedded flash process<ref name="ref2022357806" />, AURIX™ TC3xx processors achieve significant performance gains over prior generations while maintaining automotive-grade power efficiency. With six 32-bit cores at 300 MHz (four of them paired in lockstep), a flagship TC3xx device (e.g., TC39x) can deliver up to approximately 2,400 DMIPS of aggregate computing throughput<ref name="ref2022357806" />. In terms of per-core performance, the TriCore™ architecture yields around 1.3–2.0 DMIPS/MHz depending on the instruction mix, meaning each 300 MHz core can approach ~400–600 DMIPS in optimized scenarios<ref name="ref14281090103" /><ref name="ref1222155140">Infineon AURIX - Wikipedia https://en.wikipedia.org/wiki/Infineon_AURIX</ref>. This is on par with or exceeding many contemporary 32-bit automotive MCUs. The integrated DSP extensions and optional accelerators (like the FFT unit) also enable high-speed signal processing, with Infineon citing up to ~1.8 GFLOPS of DSP throughput for certain operations<ref name="ref1222155140" />.

Real-world performance improvements of the TC3xx over its predecessor are notable: for example, compared to the first-generation AURIX™ (which offered up to 740 DMIPS), the TC3xx’s expanded core count and clock speed provide roughly three times the computational power on the same type of workload<ref name="ref14281090103" />. This extra headroom allows more functions (such as running multiple control algorithms or sensor fusion tasks in parallel) to be consolidated onto one microcontroller without compromising real-time deadlines<ref name="ref14281090103" />. Despite the increase in speed and core count, the TC3xx family was designed with power and thermal constraints in mind, achieving these gains within similar power consumption envelopes as the previous generation by leveraging the smaller 40 nm process and power-saving features like clock gating<ref name="ref5727814512" />. The deterministic real-time performance (with features like lockstep and tightly-coupled memory) makes the AURIX™ TC3xx suitable for the most demanding automotive applications, where consistent low latency and high throughput are required simultaneously.

== On-Chip System Connectivity and Bridges ==
[[File:TC3xx On-Chip System Connectivity.png|thumb|The TC3xx has two '''SRI Domains''' (SRI0 and SRI1). CPU0 to CPU3 are connected to SRI0, CPU4/5 are connected to SRI1.|alt=TC3xx On-Chip System Connectivity|423x423px]]
The AURIX™ TC3xx Platform has three independent on-chip connectivity resources:

* '''System Resource Interconnect Fabric (SRI Fabric)''' connects the TriCore™ CPUs, the DMA module, and other high bandwidth requestors to high bandwidth memories and other resources for instruction fetches and data accesses. A key component of the fabric is the SRI crossbar, which connects all the agents in one SRI domain. The SRI crossbar carries the transactions between the SRI Masters and SRI Slaves of the domain. The SRI crossbar supports parallel transactions between different SRI Master and SRI Slave agents. In addition to the parallelism of concurrent requests, it also supports pipelined requests from an SRI Master to a SRI Slave.
* '''System Peripheral Bus (SPB)''' connects the TriCore™ CPUs, the DMA module, and other SPB masters to the medium and low bandwidth peripherals. SPB masters do not directly connect to the SRI Fabric, and will access SRI attached resources via a SFI_F2S Bridge.
* '''Back Bone Bus (BBB)''' connects the TriCore™ CPUs, the DMA module, and SPB masters with ADAS resources. SRI Masters do not directly connect to the BBB, but access BBB attached resources via a SFI_S2F Bridge. SPB masters also do not directly connect to the BBB, but access BBB attached resources via bridging over the SRI Fabric.

=== CPU Resource Access Times ===
These tables describe the CPU access times to various resources in CPU clock cycles for the AURIX™ TC3xx Platform. In the case of load or fetch accesses, the access times are the minimum number of CPU stall cycles to complete the access. If there is a conflict for the resource accessed, there may be additional stall cycles till the conflicting access completes.

For write access, the access times are the maximum for a sequence of such access (non-conflicting). In many cases for a singleton access, or a short sequence, write buffering reduces the stall effect seen by a CPU, sometimes to 0. However, as with loads and fetches, if there is a conflict for the resource accessed, there may be additional stall cycles till the conflicting access completes.

==== Access latency for global resources ====
{| class="wikitable"
|+
! CPU Access Type !! CPU stall cycles
!Notes
|-
| Data read from System Peripheral Bus (SPB) || <math>\frac{f_\text{CPU}}{f_\text{SPB}} \cdot (4 + \text{Module Wait State})</math>
| rowspan="2" |The final number of stall cycles will depend on the real number of WS generated by the target resource.
|-
| Data write to System Peripheral Bus (SPB) || <math>\frac{f_\text{CPU}}{f_\text{SPB}} \cdot (4 + \text{Module Wait State})</math>
|-
| Data read from Back Bone Bus (BBB) (TC39x, TC37xED) || <math>9 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (5 + \text{Module Wait State})</math>
| rowspan="2" |When SFI_S2F is connected to XBar2 (TC39x and TC37xED) there is an additional latency due to access going through an S2S.
|-
| Data write to Back Bone Bus (BBB) (TC39x, TC37xED) || <math>5 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (4 + \text{Module Wait State})</math>
|-
| Data read from Back Bone Bus (BBB) (TC35x, TC33xED) || <math>6 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (5 + \text{Module Wait State})</math>
|
|-
| Data write to Back Bone Bus (BBB) (TC35x, TC33xED) || <math>3 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (4 + \text{Module Wait State})</math>
|
|}


* '''Module Wait State''': The number of wait states for read and for write accesses is >= 1 and depends on the accessed module and its configuration.


==== CPU Accesses: Stall cycles for local and SRI resources ====
{| class="wikitable"
|+
! CPU Access Type !! Local CPU !! Local SRI !! Remote SRI Domain
|-
| Data read from DSPR || 0 || 7 || 10
|-
| Data write to DSPR || 0 || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from DSPR || See local SRI column || 7 || 10
|-
| Data read from DLMU || 0 || 7 || 10
|-
| Data write to DLMU || 2 || 5, {{rev|3|with Pipelining}}|| 5, 4
|-
| Instruction fetch from DLMU || See local SRI column || 7 || 10
|-
| Data read from PSPR || See local SRI column || 7 || 10
|-
| Data write to PSPR || See local SRI column || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from PSPR || 0 || 7 || 10
|-
| Data read from PFlash || 5 + PWS || 10 + PWS || 13 + PWS
|-
| Instruction fetch from PFlash (buffer miss) || 2 + PWS || 9 + PWS || 12 + PWS
|-
| Instruction fetch from PFlash (buffer hit) || 3 || 6 || 9
|-
| Data read from LMU || n.a. || 7 || 10
|-
| Data write to LMU || n.a. || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from LMU || n.a. || 7 || 10
|-
| Data read from DFlash || n.a. || 5 + 3*(3 + DCWS) || 8 + 3*(3 + DCWS)
|-
| Data read access from EMEM (TC39x, TC37xED) || n.a. || n.a. || 14, {{rev|15|fBBB < fSRI}}
|-
| Data write access to EMEM (TC39x, TC37xED) || n.a. || n.a. || 9
|-
| Data read access from EMEM (TC35x, TC33xED) || n.a. || 11, {{rev|12|fBBB < fSRI}}|| n.a.
|-
| Data write access to EMEM (TC35x, TC33xED) || n.a. || 9 || n.a.
|-
| Data read access from DAM || n.a. || 10 || 13
|-
| Data write access to DAM || n.a. || 7 || 7
|}

* '''Remote SRI Domain''': Only applies to products with SRI extenders. Additional latency due to access going through an S2S
* '''PWS''': Configured PFlash Wait States (Includes cycles for PFlash access cycles only). ECC correction latency is only incurred when the incoming data requires ECC correction.
* '''PWS''': Configured PFlash Wait States (Includes cycles for PFlash access cycles only). ECC correction latency is only incurred when the incoming data requires ECC correction.
* '''DCWS''': Configured DFlash Corrected Wait States (Includes cycles for DFlash access cycles and ECC correction latency)

== CPU Subsystem ==
[[File:TC3xx Processor Core, Local Memory and Connectivity.png|alt=TC3xx Processor Core, Local Memory and Connectivity|thumb|Processor Core, Local Memory and Connectivity]]The Infineon AURIX™ TC3xx features up to 6 processor cores (CPU0 ... CPU5) implementing the [[TriCore Instruction Set Architecture|TC1.6.2 instruction set architecture]]. The following section focuses on the microarchitectural details of the CPU subsystem. For more information about the ISA, please take a look at the [[TriCore Instruction Set Architecture]].

The processor core connects to the following memories and bus interfaces (where implemented):
*Program Scratch-Pad SRAM (PSPR)
*Data Scratch-Pad SRAM (DSPR)
*Program Cache (PCache)
*Data Cache (DCache)
*Local Memory Unit (DLMU)
*Local Pflash bank (LPB)
*SRI slave interface (x2)
*SRI master Interface
*SPB master interface

=== TC1.6.2P Implementation Features ===
*Most instructions executed in 1 cycle
*Branch instructions in 1, 2 or 3 cycles (using dynamic branch prediction)
*Wide memory interface for fast context switch
* Automatic context save-on-entry and restore-on-exit for: subroutine, interrupt, trap
*Six memory protection register sets
*Dual instruction issuing (in parallel into Integer Pipeline and Load/Store Pipeline)
*Third pipeline for loop instruction only (zero overhead loop)
*Single precision Floating Point Unit (IEEE-754 Compatible)
*Dedicated Integer divide unit
*18 data memory protection ranges, 10 code memory protection ranges arranged in 6 sets

=== Superscalar Architecture ===
The processor core within the AURIX™ TC3xx family, specifically the TC1.6.2P implementation, employs a superscalar architecture characterized by three parallel pipelines: the Integer Pipeline, the Load/Store Pipeline, and the Loop Pipeline. Superscalar execution is a form of instruction-level parallelism that enables the processor to issue and execute multiple instructions during a single clock cycle. The TriCore™ TC3xx core's superscalar architecture allows it to issue and execute multiple instructions in parallel. Specifically, it can issue up to two instructions simultaneously to the Integer and Load/Store pipelines. However, there are certain constraints on this dual issuing capability. For example, back-to-back data arithmetic instructions can only be issued in separate cycles, and a load/store instruction can be issued either on its own or paired with a data arithmetic instruction, provided the load/store instruction is the second in the pair. Under ideal conditions, with careful instruction scheduling, this dual-issue capability can lead to a throughput of close to 0.5 clock cycles per instruction, effectively executing two instructions per cycle.

=== Pipeline Stages ===
The execution of instructions within the TriCore™ TC3xx core is managed through a pipeline consisting of several stages. In one document it is mentioned that the pipeline consists of 6 stages <ref name="ref3635926" />, but the exact stages remain unclear. From the architecture the following stages can be inferred:

* '''Fetch Stage''': The initial stage in the pipeline is the Fetch stage, where instructions are retrieved from memory. This task is handled by the Instruction Fetch Unit (IFU), which is responsible for fetching instructions from the memory system. To improve efficiency, the IFU employs a pre-fetching mechanism, anticipating the instructions that will be needed and bringing them into the processor before they are actually required. Instructions are fetched through a 64-bit wide Program Memory Interface (PMI), allowing for the retrieval of a significant amount of instruction data in each cycle. The fetched instructions are then placed into an issue FIFO, a buffer capable of holding up to six instructions. This buffer plays a crucial role in managing the flow of instructions to the subsequent execution pipelines. The 64-bit fetch width and the instruction buffer are indicative of a design that aims to ensure a continuous supply of instructions to the pipelines, preventing them from being starved of work. A wider fetch path allows for more instruction bits to be obtained from memory in each clock cycle, while the buffer helps to mitigate temporary delays in instruction fetching.
* '''Execution Unit''': The Execution Unit contains the Integer Pipeline, the Load/Store Pipeline and the Loop Pipeline. All three pipelines operate in parallel and are capable of executing instructions simultaneously. Each pipline has its own decode stage and two execute stages. Furthermore, the TC3xx features a Floating Point Unit (FPU). It is not clear whether the FPU is part of the execution unit or a separate unit. It is assumed that the FPU also has its own decode stage and an unknown number of execute stages
** '''Decode Stage''': Following the Fetch stage, the instruction are issued to one of the pipelines. In the decode stage of each pipeline, the instruction is examined and translated to determine the specific operation it represents and to identify the operands it will operate on. It is assumed that operands are read from the register file during the decode stage.
** '''Execute Stage''': The Execute stage is where the actual operation specified by the instruction is carried out. Pipeline hazards (stalls) are minimised by the use of forwarding paths between pipeline stages allowing the results of one instruction to be used by a following instruction as soon as the result becomes available.
** '''Writeback Stage''': The final stage in the pipeline is the Writeback stage. In this stage, the results produced by the executed instruction are written back to the processor's register file, making them available for subsequent instructions. It is unclear whether the writeback stage is part of the (two) execution stages or a separate stage.

=== Execution Pipelines ===
The TriCore™ TC3xx core leverages four parallel pipelines to enhance its performance. Each pipeline is designed to handle a specific class of instructions:

* '''Integer Pipeline:''' This pipeline is responsible for executing integer arithmetic and logical instructions, including data-conditional jump instructions, bit manipulation operations, as well as division and multiply-accumulate (MAC) instructions.
* '''Load/Store Pipeline:''' The primary function of this pipeline is to manage memory access operations, including loading data from memory and storing data to memory. It also handles address arithmetic, unconditional jump instructions, procedure call instructions, context-switching operations, and control flow related to context save areas (CSAs).
* '''Loop Pipeline:''' This is a specialized pipeline designed to facilitate zero-overhead loops, a technique that significantly improves the performance of iterative code sections. Its design aims to eliminate or minimize the overhead typically associated with loop control, such as incrementing counters and checking loop conditions. Some documentation suggests that the loop pipeline comes along with a "Loop Cache". This dedicated cache would likely be used to store instructions belonging to the loop, enabling very fast access and execution for repeated iterations.
* '''Floating Point Unit (FPU):''' The FPU is responsible for executing floating-point arithmetic operations

=== Store Buffers ===
The TriCore™ TC3xx core include '''Store Buffers''' to decouple memory write operations from CPU instruction execution. All stores from the Load/Store Pipeline are placed in the store buffer prior to being written to local memory or transferred via the bus system. Write data is taken from the store buffers and written to memory when the target memory or bus interface becomes available. In normal operation the CPU will prioritise memory load operations over store operations in order to improve performance unless the store buffer is full or the order of load and store operations must be preserved (e.g. peripheral space access). The store buffer can hold the data for up to 6 stores operations. To improve performance the store buffer will merge consecutive byte, half-word, and word writes of the same location to reduce the number of memory accesses required.

=== Instruction Timing ===

==Functional Safety and Security Features==
===Hardware Security Module and Encryption===
One of the defining features of the AURIX™ TC3xx family is its robust hardware-based security subsystem, implemented to protect against cyber threats and unauthorized manipulation of vehicle systems. Each TC3xx MCU includes a dedicated ''Hardware Security Module'' (HSM), which is essentially an on-chip co-processor with its own CPU and cryptographic engine designed to handle secure operations. In the second-generation AURIX™ (TC3xx), the HSM was upgraded with support for asymmetric cryptography (e.g., RSA, ECC algorithms) in hardware, providing significantly faster public-key encryption and authentication capabilities than pure software implementations. This HSM supports '''EVITA Full''' (the highest level of the EU’s EVITA automotive security requirements), meaning it can perform secure boot, message authentication, and encryption at a level suitable for protecting critical in-vehicle communications. For example, the HSM can encrypt and authenticate CAN/Ethernet messages to prevent spoofing or tampering on the vehicle network, and it can manage cryptographic keys securely isolated from the main application cores.<ref name="ref14281090104">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref2022357806" />

The security module enables features like '''secure boot''', where the AURIX™ will only execute firmware that is digitally signed by the vehicle manufacturer, thereby preventing unauthorized or malicious code. It also facilitates ''over-the-air (OTA) updates'' in a secure manner: the TC3xx HSM can verify and decrypt update packages received via telematics, allowing firmware upgrades while protecting against attackers attempting to hijack the software. In addition, the HSM includes a true random number generator and supports protocols for immobilizer and theft protection systems. Infineon’s implementation essentially treats the HSM as an “embedded smart card” inside the microcontroller. This approach, building on Infineon’s expertise in chip card security, helps to safeguard sensitive assets like cryptographic keys and to perform secure operations (encryption, decryption, authentication) in hardware, making attacks significantly more difficult. The strong cybersecurity provisions of the AURIX™ TC3xx have made it a preferred choice for vehicle gateway ECUs and central body controllers, which are points of entry for connected car communications and thus high-value targets for hackers. By incorporating the HSM, automotive OEMs can implement advanced security features such as encrypted onboard communication (to thwart bus tampering) and secure diagnostics, ensuring the vehicle’s electronic data is protected against cyber threats even as cars become more connected.<ref name="ref14281090104" /><ref name="ref5727814513">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref><ref name="ref19484776953">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref>
=== Functional Safety and Fault Tolerance===
Beyond cybersecurity, the AURIX™ TC3xx architecture is built with extensive ''functional safety'' features to meet the highest safety integrity levels in automotive systems. The multi-core design supports ''lockstep operation'', where redundant checker cores run in parallel with main cores and continuously compare results cycle-by-cycle. In TC3xx devices, up to four of the six TriCore™ CPUs have such lockstep partner cores, allowing the microcontroller to detect any single-point CPU failure instantly (if a discrepancy arises between the core and its checker, a fault is signaled). A ''Safety Management Unit (SMU)'' is integrated on-chip to monitor various fault conditions throughout the device – it aggregates error signals from the lockstep cores, memory ECC monitors, clock/watchdog monitors, and peripheral self-tests, and can initiate safe-state actions (like resetting the chip or signaling an error pin to an external supervisor) if a critical fault is detected. The AURIX™ safety concept also includes a distributed Memory Protection Unit (MPU) arrangement, with multiple memory protection contexts that prevent errant or malicious code from writing to wrong memory areas. This helps contain faults and eases the integration of software with mixed criticality (Infineon allows partitioning software components of different ASIL levels on the same MCU while keeping them isolated).<ref name="ref14281090104" /><ref name="ref5727814513" /><ref name="ref19519075552">Safety Microcontrollers: Texas Instruments Hercules vs Infineon AURIX https://www.linkedin.com/pulse/safety-microcontrollers-texas-instruments-hercules-vs-cook-meng-miet</ref>

Crucially, the TC3xx family was developed according to ISO 26262 processes and can achieve '''ASIL-D''' (Automotive Safety Integrity Level D), the highest grade for automotive functional safety. Compared to a traditional dual-core lockstep approach, the AURIX’s™ multi-core safety architecture allowed Infineon to reduce certain safety development overheads (earlier Infineon data suggested up to 30% reduction in safety software workload) by providing built-in safety mechanisms and diagnostics. Infineon supplies a comprehensive safety manual and diagnostic libraries for the AURIX™, helping engineers utilize features like CPU self-tests, RAM tests, and CRC checks to comply with safety standards. In addition to automotive standards, the AURIX™ TC3xx has also been qualified for '''industrial safety''': in 2023, Infineon announced support for IEC 61508 metrics, enabling designs with AURIX™ to reach SIL-2 and SIL-3 safety integrity levels for industrial applications. This cross-industry safety compliance is facilitated by the MCU’s redundant design and detailed failure mode documentation (FMEDA) provided by Infineon. In summary, the AURIX™ TC3xx integrates both proactive safety (fault prevention via lockstep, monitoring and protection) and reactive safety (fault detection and safe shutdown), making it a dependable component for systems that cannot afford unintended behavior, whether in cars, factories, or aerospace. <ref name="ref14281090104" /><ref name="ref5727814513" /><ref name="ref4967712052">Infineon's AURIX™ & TRAVEO™ microcontroller families extend their support for IEC 61508 hardware and software metrics enabling industrial safety up to SIL-3 - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2023/INFATV202303-078.html</ref><ref name="ref196858272">MCUs support industrial functional safety - Electronic Products https://www.electronicproducts.com/mcus-support-industrial-functional-safety/</ref>
== Platform Devices ==
The following table shows a feature overview of the AURIX™ TC3xx Platform family focusing on memory and number of cores.
{| class="wikitable"
!
!Feature
!TC33x
!TC33xEXT
!TC35x
!TC36x
!TC37x
!TC37xEXT
!TC38x
!TC39x
|-
| rowspan="2" |CPUs
|Cores / Checker Cores
|1 / 1
|2 / 1
|3 / 2
|2 / 2
|3 / 2
|3 / 3
|4 / 2
|6 / 4
|-
|Max. Freq.
| colspan="8" |300 MHz
|-
| rowspan="2" |Cache per CPU
|Program [KB]
| colspan="8" |32
|-
|Data [KB]
| colspan="8" |16
|-
| rowspan="3" |SRAM per CPU
|PSPR [KB]
|8
|{{rev|32|CPU0}}
{{rev|64|other}}
|64
|32
|64
|64
|64
|64
|-
|DSPR [KB]
|192
|{{rev|192|CPU0}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|192
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|-
|DLMU [KB]
|8
|{{rev|8|CPU0}}
{{rev|64|other}}
|64
|64
|64
|64
|64
|64
|-
| rowspan="2" |SRAM global
|LMU [KB]
| -
| -
|512
| -
| -
| -
|128
|768
|-
|DAM [KB]
| -
| -
|32
| -
|64
|64
|128
|128
|-
| rowspan="3" |Extension Memory (EMEM)
|TCM [MB]
| -
|1
|2
| -
| -
|2
| -
|2
|-
|XCM [MB]
| -
| -
| -
| -
| -
|1
| -
|2
|-
|XTM [KB]
| -
|16
|16
| -
| -
|16
| -
|16
|-
| rowspan="2" |Program Flash
|Size [MB]
|2
|4
|4
|4
|6
|10
|10
|16
|-
|Banks [MB]
|1 x 2
|2 x 2
|2 x 2
|2 x 2
|2 x 3
|3 x 3, 1 x 1
|3 x 3, 1 x 1
|5 x 3, 1 x 1
|-
| rowspan="2" |Data Flash
|DF0 Size (single-ended) [KB]
|128
|128
|128
|128
|256
|512
|512
|1024
|-
|DF1 Size (single-ended) [KB]
|128
|128
|128
|128
|128
|128
|128
|128
|-
| rowspan="3" |DMA
|Channels
|64
|64
|64
|64
|128
|128
|128
|128
|-
|Move Engines
|2
|2
|2
|2
|2
|2
|2
|2
|-
|Resource Partitions
|4
|4
|4
|4
|4
|4
|4
|4
|}

== Compilers ==
The AURIX™ TC3xx family is a series of high-performance microcontrollers widely used in automotive and industrial applications. Compilers for the AURIX™ TC3xx are crucial for developers aiming to optimize performance, reliability, and safety in their applications. One significant aspect of the compiler landscape for AURIX™ TC3xx is the limited direct support from mainline open-source compilers such as GCC or LLVM/Clang. The primary reason for this is the stringent requirements for functional safety in automotive and industrial applications, which demand specialized features and compliance with safety standards that are often not met by general-purpose open-source compilers.

=== Commercial Compilers ===

# '''Tasking''': Tasking compilers are renowned for their robust support for automotive applications, offering advanced debugging capabilities and optimization techniques tailored for the AURIX™ architecture. They provide extensive code optimization, comprehensive debugging tools, and strong support for safety standards such as ISO 26262, making them ideal for developing high-performance, reliable, and safe applications.
# '''HighTec''': The HighTec compiler is a popular choice, known for its Eclipse-based development environment and strong multicore support. HighTec provides both GCC and LLVM-based ports of open-source compilers tailored specifically for the AURIX™ TC3xx family. These compilers offer efficient parallel execution, advanced code analysis, and an integrated development environment, ensuring robust performance and compliance with safety standards.
# '''Green Hills Software''': Green Hills Software provides a highly optimized toolchain aimed at safety-critical applications, focusing on high performance and strict compliance with automotive standards. Their compiler offers superior optimization, extensive safety features, and a proprietary IDE with specialized tools for automotive development, ensuring developers can meet the stringent demands of functional safety.

=== GCC for AURIX™ ===

While mainline GCC does not directly support the AURIX™ TC3xx family, there is an unofficial GCC version available for AURIX™. Due to the GNU General Public License (GPL), the source code from HighTec was retrieved and, along with binary versions, published on GitHub:

*Infineon's release of GCC for Aurix with binaries for both Linux and Windows [https://softwaretools.infineon.com/tools/com.ifx.tb.tool.aurixgcc]
*GCC 4.9.4/Binutils 2.20/Newlib 1.18 for Tricore™ AURIX™ [[https://github.com/volumit/package_494 Source]] [[https://github.com/volumit/tricore_gcc494_mingw_bins Prebuild Mingw Binaries]] [[https://github.com/volumit/tricore_gcc494_linux_bins Prebuild Linux Binaries]]
*GCC 9.4.0/Binutils 2.20/Newlib 1.18 for Tricore™ AURIX™ [[https://github.com/volumit/package_940 Source]] [[https://github.com/volumit/tricore_gcc940_mingw_bins Prebuild Mingw Binaries]] [[https://github.com/volumit/tricore_gcc940_linux_bins Prebuild Linux Binaries]]
*EEESLab's repositories of GCC, Binutils and Newlib for Tricore™ AURIX™ [[https://github.com/EEESlab/tricore-gcc-toolchain-11.3.0 Source]]
*NoMore201's fork of EEESLab's GCC for Tricore™ AURIX™ including GCC, Binutils, Newlib, GDB and QEmu [[https://github.com/NoMore201/tricore-gcc-toolchain Source]] [[https://github.com/NoMore201/tricore-gcc-toolchain/releases/tag/11.3.1-20250101 Sources and prebuilt binaries of gcc-11.3.1 for Linux and Windows]] [[https://github.com/NoMore201/tricore-gcc-toolchain/releases/tag/13.3-20250516 Sources and prebuilt binaries of gcc-13.3.0 for Linux and Windows]]
*GDB 10.0.50 for Tricore™ AURIX™ [[https://github.com/volumit/gdb-tricore Source]]
==emmtrix Tools for AURIX™ TC3xx==
[[File:lowres-Signet Associated Partner EN.eps.png|thumb|305x305px|emmtrix Technologies is an Infineon Associated Partner with over 10 years of experience working with the '''Infineon AURIX™ microcontroller family''' and has been actively collaborating with Infineon for the past five years.|alt=emmtrix Associated Partner]]
emmtrix offers the following tool for the Infineon AURIX™ TC3xx architecture:
=== emmtrix Performance Estimator ===
[[emmtrix Performance Estimator|emmtrix Performance Estimator (ePE)]] provides static timing analysis of C code. Compared to simulation or measurement on hardware, static performance analysis can be applied significantly earlier in the development process and will deliver results on average 6 months earlier compared to a typical automotive HIL setup. The analysis only takes a few minutes at most and runs on the developer’s PC independently of any target hardware. Function developers can analyze their runnables or SWCs without the need of a fully integrated program. emmtrix Performance Estimator is fully compatible with '''Infineon's AURIX™ [[Infineon AURIX TC2xx|TC2xx]] / TC3xx/ [[Infineon AURIX TC4x|TC4x]] microcontroller family,''' ensuring precise and reliable performance analysis for embedded systems.

A unique feature is the combination with TargetLink or Embedded Coder generated code. Without any measurement overhead, our static performance estimation can analyze even the smallest code snippets. This allows us to map the timing analysis to Simulink blocks, giving function developers insight into the timing behavior of their models.

ePE offers three accuracy levels:

* analysis of C code
* generically compiler-optimized code
* assembly code from the target compiler.

Method 1 yields results with minimum effort while method 3 takes the timing of the processor pipeline into account. All methods offer excellent reliability when tracking the tendency of changes in software runtimes e.g. when used in a continuous integration environment.

=== Services ===
====Architecture & Variant Consulting====
* Support in selecting suitable AURIX derivatives for new product generations (trade-offs between performance, price, safety, and peripheral features)
*Analysis of requirements and mapping to specific AURIX product families (e.g., TC3xx vs. TC4xx)
*Analysis/identification of performance margins for down- or upgrades
==== Runtime Analysis & Performance Engineering ====
* Execution of detailed runtime analyses (maximum/minimum vs. average)
* Identification of bottlenecks in program execution, including benchmarking
*Optimization of access to flash, RAM, and peripherals (e.g., cache configuration, DMA utilization)
====Dependency Analysis====
*Freedom from interference (ASIL level check)

==== Multicore Design & Scheduling Concepts ====

* Development of core mapping strategies (static vs. dynamic assignment of compute-intensive tasks)

*Support for integrating bare-metal scheduling on AURIX
*Assistance with architectural decisions to meet functional safety requirements in multicore systems

==== Training & Know-how Transfer ====

* Technical in-house workshops on AURIX optimization, multicore strategies

*Coaching of employees/project teams in performance analysis and systematic tuning
==See Also==

*[[Infineon AURIX TC4x|Infineon AURIX™ TC4x]]
*[[Infineon AURIX TC2xx|Infineon AURIX™ TC2xx]]
*[[TriCore Instruction Set Architecture]]

==External Links==

*https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/
*[https://documentation.infineon.com/aurixtc3xx/docs/qmd1702366622648 AURIX™ TC3xx user manuals]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Part1-UserManual-v02_00-EN.pdf?fileId=5546d462712ef9b701717d3605221d96 AURIX™ TC3xx User Manual Part-1]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Part2-UserManual-v02_00-EN.pdf?fileId=5546d462712ef9b701717d35f8541d94 AURIX™ TC3xx User Manual Part-2]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Architecture_vol1-UserManual-v01_00-EN.pdf?fileId=5546d46276fb756a01771bc4c2e33bdd AURIX™ TC3xx Architecture vol 1]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Architecture_vol2-UserManual-v01_00-EN.pdf?fileId=5546d46276fb756a01771bc4a6d73b70 AURIX™ TC3xx Architecture vol 2]

== References ==
<references />
[[Category:Supported Architectures]]

{{#seo:
|title=Infineon AURIX TC3xx Family – Deep Dive
|description=This deep dive into Infineon's AURIX TC3xx family explores its multi-core TriCore architecture, real-time capabilities, safety and security features and tools
|image=File:AURIX_TC399_LFBGA-516_plain.jpg
|keywords=AURIX, Infineon, TC3xx, microcontroller, TriCore, automotive, ADAS, ISO 26262, functional safety, embedded security, ASIL-D, deep dive
}}

Infineon AURIX TC3xx

2025-07-03T09:37:34Z

Tobias.columbus: more toolchains

[[File:AURIX TC399 LFBGA-516 plain.jpg|thumb|Infineon AURIX™ TC3xx second-generation microcontroller (TC399 BGA package). The AURIX™ TC3xx family integrates multiple TriCore™ CPUs and on-chip safety/security modules for automotive applications.|alt=TC399 BGA package]]
The '''Infineon AURIX™ TC3xx''' (Automotive Realtime Integrated neXt-generation architecture) is a family of 32-bit automotive microcontrollers introduced as the second generation of Infineon’s AURIX™ platform. Launched in 2016 as a successor to the earlier [[Infineon AURIX TC2xx|AURIX™ TC2xx series]], the TC3xx devices emphasize high performance, functional safety, and embedded security for advanced automotive and industrial applications. AURIX™ TC3xx microcontrollers feature a hexa-core [[TriCore Instruction Set Architecture|''TriCore'' processor architecture]] with enhanced safety measures, making them well-suited for demanding tasks such as autonomous driving domain controllers, powertrain control, and sensor data fusion in advanced driver-assistance systems (ADAS). The combination of multiple CPU cores, extensive on-chip memory, and a rich peripheral set allows TC3xx chips to deliver real-time responsiveness and reliability in safety-critical environments while meeting stringent automotive standards (such as ISO 26262 for functional safety).<ref name="ref1951907555">Safety Microcontrollers: Texas Instruments Hercules vs Infineon AURIX https://www.linkedin.com/pulse/safety-microcontrollers-texas-instruments-hercules-vs-cook-meng-miet</ref><ref name="ref1428109010">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref1948477695">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref>
==Applications==
AURIX™ TC3xx microcontrollers are used in a variety of safety-critical and high-performance applications across the automotive and industrial sectors. Key application domains include:
*'''Automotive Systems:''' The TC3xx family was primarily designed for automotive use and finds broad application in vehicles’ electronic control units (ECUs). Notably, it is used in ''powertrain and drivetrain control'' (engine management, transmission control, hybrid/electric vehicle inverter control, battery management) where its real-time processing and resilience support precise actuator control. It is also deployed in ''chassis and safety systems'' such as anti-lock braking systems (ABS), electronic stability control, airbag controllers, and electric power steering, leveraging its redundancy and fast response for fail-safe operation. With the growth of ADAS and autonomous driving, AURIX™ TC3xx devices serve as domain controllers for ''ADAS sensor fusion'', handling data from radar, LiDAR, camera, and ultrasonic sensors and performing environment modeling and decision-making algorithms. Their combination of multiple cores and a built-in radar signal processing sub-system makes them an attractive choice for tasks like front radar processing, sensor fusion hubs, and ''autonomous driving domain controllers'' that must meet ASIL-D safety levels.<ref name="ref14281090102">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref572781451">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref>
*'''Industrial Automation and Robotics:''' Infineon has also positioned the AURIX™ family for use in industrial applications that demand high reliability. The TC3xx MCUs, with their hardware self-test mechanisms and safety documentation, can be found in ''industrial motor drives, robotics controllers, and PLCs (programmable logic controllers)'', where they help achieve functional safety certifications up to SIL-3 (according to IEC 61508). The powerful TriCore™ cores and rich peripheral set enable complex motor control algorithms (e.g., field-oriented control for servo motors) and real-time sensor processing in factory automation. Additionally, the support for automotive-grade networking (CAN/CAN-FD, Ethernet) and timing peripherals makes them suitable for synchronous control in robotics and machinery. Infineon’s provision of AUTOSAR-compatible software for AURIX™ has even facilitated its use in non-automotive settings such as medical devices and elevator controllers, where proven safety and security are required.<ref name="ref496771205">Infineon's AURIX™ & TRAVEO™ microcontroller families extend their support for IEC 61508 hardware and software metrics enabling industrial safety up to SIL-3 - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2023/INFATV202303-078.html</ref>
*'''Aerospace and Defense:''' The high fault-tolerance and deterministic performance of the AURIX™ TC3xx architecture also attract interest for aerospace and other mission-critical uses. In avionics systems or autonomous drones, for instance, the lockstep core configuration and robust error checking of AURIX™ can provide an added layer of reliability for flight control computers or navigation systems. While primarily an automotive chip, its ability to operate in harsh conditions (−40°C to 150°C range) and to detect internal failures in real-time makes it viable for certain aerospace electronic systems. Some defense and aerospace projects leverage COTS (commercial off-the-shelf) automotive components like AURIX™ for applications such as unmanned vehicle control and high-reliability communication links, given its safety pedigree. (In these domains, additional analysis and possibly radiation testing would be performed if the devices are used in high-altitude or space environments.)
== Architecture Overview ==
[[File:Infineon TC3xx Architecture.webp|545x545px|thumb|alt=TC3xx Architecture Overview|TC3xx Architecture Overview]]
=== Processor Cores and Architecture===
The AURIX™ TC3xx family implements Infineon’s TriCore™ architecture, which uniquely combines aspects of RISC microcontrollers, DSP (digital signal processor) capabilities, and conventional microprocessor features into a single core design. Each TC3xx device can include up to six independent TriCore™ 32-bit CPU cores (TriCore™ version 1.6.2), all capable of running at up to 300 MHz clock frequency. Four of these cores can operate in dual-core lockstep pairs (with one core acting as a redundant checker for its partner) to provide fault detection for safety-critical functions. The TriCore™ cores use a superscalar Harvard architecture with 32-bit instruction words (and support for mixed 16/32-bit instruction encoding for code density). Each core includes a dedicated Floating Point Unit (FPU) for single-precision arithmetic and supports DSP-oriented instructions (e.g. single-cycle 16×16 MAC operations, SIMD for 16-bit/8-bit data) to accelerate signal processing tasks. For fast real-time performance, the architecture offers low interrupt latency (with automatic context save on-chip) and features like zero-overhead loops and a programmable peripheral timer unit for scheduling tasks. In total, a high-end TC3xx (such as the TC39x) provides six 300 MHz cores plus four checker cores, yielding a theoretical processing throughput of up to ~2400 DMIPS (Dhrystone MIPS) when all cores are utilized. This represents roughly a threefold increase in computational power over the previous AURIX™ generation (which achieved ~740 DMIPS with three cores).<ref name="ref19484776952">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref><ref name="ref2022357806">UDE Debug, Trace and Test solutions for Infineon TriCore™ AURIX™ TC32, TC33, TC35, TC36, TC37, TC38, TC39, TC3x Microcontrollers https://www.pls-mc.com/products/infineon-tricore-aurix-tc32-tc33-tc35-tc36-tc37-tc38-tc39-microcontrollers/</ref><ref name="ref14281090103">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref>
===Memory Subsystem and Cache===
AURIX™ TC3xx microcontrollers integrate a large on-chip memory system to meet real-time and safety requirements. Program flash memory sizes range up to 16 MB on the largest models, with over 6 MB of on-chip SRAM available for data and scratchpad usage. Each TriCore™ CPU has its own tightly-coupled local memories as well as caches: for example, each core includes a 32 KB instruction cache and a 16 KB data cache. In addition, every core has separate local RAM blocks (Harvard architecture) for instructions and data (often termed PSPR and DSPR – Program Scratch-Pad RAM and Data Scratch-Pad RAM) that allow deterministic access for time-critical routines. Shared global memory is provided via a Local Memory Unit (LMU) which can be up to several hundred kilobytes (for instance, 768 KB in the TC39x) accessible by all cores. The memory system is connected by a high-bandwidth internal bus fabric (the SRI crossbar and peripheral buses) that arbitrates access between cores, DMA engines, and peripherals. This architecture ensures that each core can quickly fetch instructions and data either from its local cache/RAM or the central memory, enabling efficient parallel processing. Memory protection hardware is also built-in to isolate tasks of different criticality, an important feature for safety and security.<ref name="ref19484776952" /><ref name="ref5727814512">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref>
===Peripherals and Interfaces===
One of the strengths of the AURIX™ TC3xx architecture is its extensive set of on-chip peripherals and interface controllers, designed to handle the complex networking and I/O needs of modern vehicles and industrial systems. Key peripheral features and interfaces include:<ref name="ref19484776952" /><ref name="ref2022357806" /><ref name="ref14281090103" /><ref name="ref3635926">AURIX™ Training System Architecture https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_System_Architecture-Training-v01_00-EN.pdf?fileId=5546d46272e49d2a0172eb476d56739e</ref>

* '''Networking Interfaces:''' Multiple CAN FD controllers (supporting up to 12 CAN-FD channels in high-end variants) for in-vehicle networking, with legacy CAN and LIN interfaces (up to 24 LIN channels) for lower-speed device communication. Many TC3xx devices also integrate up to two FlexRay controllers for time-triggered automotive networks (maintaining compatibility with earlier automotive communication standards). For high-bandwidth data, a Gigabit Ethernet MAC is included, enabling uses like automotive Ethernet (e.g., audio-video bridging and IP-based connectivity).
* '''Analog and Timers:''' A suite of analog peripherals including multiple ADC units for sensor interfacing and motor control, and DACs in some models. Sophisticated timer units are on-chip, notably the Generic Timer Module (GTM) and Capture/Compare Units (CCU6), which can generate complex PWM waveforms and handle events for engine control, power inverters, or robotics with minimal CPU intervention. These timers enable precise control of actuators (e.g. fuel injection timing, electric motor commutation) in real time.
*'''Serial Interfaces:''' SPI, I²C, UART/LIN and other serial interfaces for connecting to external sensors, actuator controllers, and memory. The controllers often support multiple instances (several SPI channels, etc.) to accommodate numerous devices. AURIX™ TC3xx also provides an external bus interface (EBU) for parallel memory or FPGA connectivity, and an SD/MMC interface (eMMC) to connect external flash memory for data logging or over-the-air update storage.
*'''Dedicated Processing Units:''' Some AURIX™ TC3xx models include special accelerators, such as a hardware Fast Fourier Transform unit (HW-FFT) and up to two Signal Processing Units (SPUs) optimized for radar signal processing. These enable the microcontroller to handle radar front-end data or other intensive DSP tasks (like Fourier transforms for radar or audio signals) on-chip, which is crucial for advanced driver assistance sensors. There is also a ''Security Module'' (covered in a later section) and a Safety Management Unit that supervise system integrity.
*'''Other On-chip Modules:''' Watchdog timers, error-correction coders for memories (ECC on flash and RAM for reliability), a programmable interrupt system, multiple DMA channels (up to 128 DMA channels) for efficient data movement, and debug interfaces (JTAG and a 2/3-pin DAP) for development. The on-chip debug system supports tracing of program execution (via a built-in Emulation Memory, MCDS) to aid in complex multicore software development.

Overall, the AURIX™TC3xx provides a highly integrated SoC-like platform, allowing a single chip to manage tasks ranging from powertrain control and chassis control to infotainment gateways. This high level of integration reduces the need for separate companion chips and helps to lower system complexity and cost.
===Performance and Benchmarking===
Fabricated in a 40 nm embedded flash process<ref name="ref2022357806" />, AURIX™ TC3xx processors achieve significant performance gains over prior generations while maintaining automotive-grade power efficiency. With six 32-bit cores at 300 MHz (four of them paired in lockstep), a flagship TC3xx device (e.g., TC39x) can deliver up to approximately 2,400 DMIPS of aggregate computing throughput<ref name="ref2022357806" />. In terms of per-core performance, the TriCore™ architecture yields around 1.3–2.0 DMIPS/MHz depending on the instruction mix, meaning each 300 MHz core can approach ~400–600 DMIPS in optimized scenarios<ref name="ref14281090103" /><ref name="ref1222155140">Infineon AURIX - Wikipedia https://en.wikipedia.org/wiki/Infineon_AURIX</ref>. This is on par with or exceeding many contemporary 32-bit automotive MCUs. The integrated DSP extensions and optional accelerators (like the FFT unit) also enable high-speed signal processing, with Infineon citing up to ~1.8 GFLOPS of DSP throughput for certain operations<ref name="ref1222155140" />.

Real-world performance improvements of the TC3xx over its predecessor are notable: for example, compared to the first-generation AURIX™ (which offered up to 740 DMIPS), the TC3xx’s expanded core count and clock speed provide roughly three times the computational power on the same type of workload<ref name="ref14281090103" />. This extra headroom allows more functions (such as running multiple control algorithms or sensor fusion tasks in parallel) to be consolidated onto one microcontroller without compromising real-time deadlines<ref name="ref14281090103" />. Despite the increase in speed and core count, the TC3xx family was designed with power and thermal constraints in mind, achieving these gains within similar power consumption envelopes as the previous generation by leveraging the smaller 40 nm process and power-saving features like clock gating<ref name="ref5727814512" />. The deterministic real-time performance (with features like lockstep and tightly-coupled memory) makes the AURIX™ TC3xx suitable for the most demanding automotive applications, where consistent low latency and high throughput are required simultaneously.

== On-Chip System Connectivity and Bridges ==
[[File:TC3xx On-Chip System Connectivity.png|thumb|The TC3xx has two '''SRI Domains''' (SRI0 and SRI1). CPU0 to CPU3 are connected to SRI0, CPU4/5 are connected to SRI1.|alt=TC3xx On-Chip System Connectivity|423x423px]]
The AURIX™ TC3xx Platform has three independent on-chip connectivity resources:

* '''System Resource Interconnect Fabric (SRI Fabric)''' connects the TriCore™ CPUs, the DMA module, and other high bandwidth requestors to high bandwidth memories and other resources for instruction fetches and data accesses. A key component of the fabric is the SRI crossbar, which connects all the agents in one SRI domain. The SRI crossbar carries the transactions between the SRI Masters and SRI Slaves of the domain. The SRI crossbar supports parallel transactions between different SRI Master and SRI Slave agents. In addition to the parallelism of concurrent requests, it also supports pipelined requests from an SRI Master to a SRI Slave.
* '''System Peripheral Bus (SPB)''' connects the TriCore™ CPUs, the DMA module, and other SPB masters to the medium and low bandwidth peripherals. SPB masters do not directly connect to the SRI Fabric, and will access SRI attached resources via a SFI_F2S Bridge.
* '''Back Bone Bus (BBB)''' connects the TriCore™ CPUs, the DMA module, and SPB masters with ADAS resources. SRI Masters do not directly connect to the BBB, but access BBB attached resources via a SFI_S2F Bridge. SPB masters also do not directly connect to the BBB, but access BBB attached resources via bridging over the SRI Fabric.

=== CPU Resource Access Times ===
These tables describe the CPU access times to various resources in CPU clock cycles for the AURIX™ TC3xx Platform. In the case of load or fetch accesses, the access times are the minimum number of CPU stall cycles to complete the access. If there is a conflict for the resource accessed, there may be additional stall cycles till the conflicting access completes.

For write access, the access times are the maximum for a sequence of such access (non-conflicting). In many cases for a singleton access, or a short sequence, write buffering reduces the stall effect seen by a CPU, sometimes to 0. However, as with loads and fetches, if there is a conflict for the resource accessed, there may be additional stall cycles till the conflicting access completes.

==== Access latency for global resources ====
{| class="wikitable"
|+
! CPU Access Type !! CPU stall cycles
!Notes
|-
| Data read from System Peripheral Bus (SPB) || <math>\frac{f_\text{CPU}}{f_\text{SPB}} \cdot (4 + \text{Module Wait State})</math>
| rowspan="2" |The final number of stall cycles will depend on the real number of WS generated by the target resource.
|-
| Data write to System Peripheral Bus (SPB) || <math>\frac{f_\text{CPU}}{f_\text{SPB}} \cdot (4 + \text{Module Wait State})</math>
|-
| Data read from Back Bone Bus (BBB) (TC39x, TC37xED) || <math>9 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (5 + \text{Module Wait State})</math>
| rowspan="2" |When SFI_S2F is connected to XBar2 (TC39x and TC37xED) there is an additional latency due to access going through an S2S.
|-
| Data write to Back Bone Bus (BBB) (TC39x, TC37xED) || <math>5 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (4 + \text{Module Wait State})</math>
|-
| Data read from Back Bone Bus (BBB) (TC35x, TC33xED) || <math>6 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (5 + \text{Module Wait State})</math>
|
|-
| Data write to Back Bone Bus (BBB) (TC35x, TC33xED) || <math>3 + \frac{f_\text{CPU}}{f_\text{BBB}} \cdot (4 + \text{Module Wait State})</math>
|
|}


* '''Module Wait State''': The number of wait states for read and for write accesses is >= 1 and depends on the accessed module and its configuration.


==== CPU Accesses: Stall cycles for local and SRI resources ====
{| class="wikitable"
|+
! CPU Access Type !! Local CPU !! Local SRI !! Remote SRI Domain
|-
| Data read from DSPR || 0 || 7 || 10
|-
| Data write to DSPR || 0 || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from DSPR || See local SRI column || 7 || 10
|-
| Data read from DLMU || 0 || 7 || 10
|-
| Data write to DLMU || 2 || 5, {{rev|3|with Pipelining}}|| 5, 4
|-
| Instruction fetch from DLMU || See local SRI column || 7 || 10
|-
| Data read from PSPR || See local SRI column || 7 || 10
|-
| Data write to PSPR || See local SRI column || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from PSPR || 0 || 7 || 10
|-
| Data read from PFlash || 5 + PWS || 10 + PWS || 13 + PWS
|-
| Instruction fetch from PFlash (buffer miss) || 2 + PWS || 9 + PWS || 12 + PWS
|-
| Instruction fetch from PFlash (buffer hit) || 3 || 6 || 9
|-
| Data read from LMU || n.a. || 7 || 10
|-
| Data write to LMU || n.a. || 5, {{rev|3|with Pipelining}}|| 5, {{rev|4|with Pipelining}}
|-
| Instruction fetch from LMU || n.a. || 7 || 10
|-
| Data read from DFlash || n.a. || 5 + 3*(3 + DCWS) || 8 + 3*(3 + DCWS)
|-
| Data read access from EMEM (TC39x, TC37xED) || n.a. || n.a. || 14, {{rev|15|fBBB < fSRI}}
|-
| Data write access to EMEM (TC39x, TC37xED) || n.a. || n.a. || 9
|-
| Data read access from EMEM (TC35x, TC33xED) || n.a. || 11, {{rev|12|fBBB < fSRI}}|| n.a.
|-
| Data write access to EMEM (TC35x, TC33xED) || n.a. || 9 || n.a.
|-
| Data read access from DAM || n.a. || 10 || 13
|-
| Data write access to DAM || n.a. || 7 || 7
|}

* '''Remote SRI Domain''': Only applies to products with SRI extenders. Additional latency due to access going through an S2S
* '''PWS''': Configured PFlash Wait States (Includes cycles for PFlash access cycles only). ECC correction latency is only incurred when the incoming data requires ECC correction.
* '''PWS''': Configured PFlash Wait States (Includes cycles for PFlash access cycles only). ECC correction latency is only incurred when the incoming data requires ECC correction.
* '''DCWS''': Configured DFlash Corrected Wait States (Includes cycles for DFlash access cycles and ECC correction latency)

== CPU Subsystem ==
[[File:TC3xx Processor Core, Local Memory and Connectivity.png|alt=TC3xx Processor Core, Local Memory and Connectivity|thumb|Processor Core, Local Memory and Connectivity]]The Infineon AURIX™ TC3xx features up to 6 processor cores (CPU0 ... CPU5) implementing the [[TriCore Instruction Set Architecture|TC1.6.2 instruction set architecture]]. The following section focuses on the microarchitectural details of the CPU subsystem. For more information about the ISA, please take a look at the [[TriCore Instruction Set Architecture]].

The processor core connects to the following memories and bus interfaces (where implemented):
*Program Scratch-Pad SRAM (PSPR)
*Data Scratch-Pad SRAM (DSPR)
*Program Cache (PCache)
*Data Cache (DCache)
*Local Memory Unit (DLMU)
*Local Pflash bank (LPB)
*SRI slave interface (x2)
*SRI master Interface
*SPB master interface

=== TC1.6.2P Implementation Features ===
*Most instructions executed in 1 cycle
*Branch instructions in 1, 2 or 3 cycles (using dynamic branch prediction)
*Wide memory interface for fast context switch
* Automatic context save-on-entry and restore-on-exit for: subroutine, interrupt, trap
*Six memory protection register sets
*Dual instruction issuing (in parallel into Integer Pipeline and Load/Store Pipeline)
*Third pipeline for loop instruction only (zero overhead loop)
*Single precision Floating Point Unit (IEEE-754 Compatible)
*Dedicated Integer divide unit
*18 data memory protection ranges, 10 code memory protection ranges arranged in 6 sets

=== Superscalar Architecture ===
The processor core within the AURIX™ TC3xx family, specifically the TC1.6.2P implementation, employs a superscalar architecture characterized by three parallel pipelines: the Integer Pipeline, the Load/Store Pipeline, and the Loop Pipeline. Superscalar execution is a form of instruction-level parallelism that enables the processor to issue and execute multiple instructions during a single clock cycle. The TriCore™ TC3xx core's superscalar architecture allows it to issue and execute multiple instructions in parallel. Specifically, it can issue up to two instructions simultaneously to the Integer and Load/Store pipelines. However, there are certain constraints on this dual issuing capability. For example, back-to-back data arithmetic instructions can only be issued in separate cycles, and a load/store instruction can be issued either on its own or paired with a data arithmetic instruction, provided the load/store instruction is the second in the pair. Under ideal conditions, with careful instruction scheduling, this dual-issue capability can lead to a throughput of close to 0.5 clock cycles per instruction, effectively executing two instructions per cycle.

=== Pipeline Stages ===
The execution of instructions within the TriCore™ TC3xx core is managed through a pipeline consisting of several stages. In one document it is mentioned that the pipeline consists of 6 stages <ref name="ref3635926" />, but the exact stages remain unclear. From the architecture the following stages can be inferred:

* '''Fetch Stage''': The initial stage in the pipeline is the Fetch stage, where instructions are retrieved from memory. This task is handled by the Instruction Fetch Unit (IFU), which is responsible for fetching instructions from the memory system. To improve efficiency, the IFU employs a pre-fetching mechanism, anticipating the instructions that will be needed and bringing them into the processor before they are actually required. Instructions are fetched through a 64-bit wide Program Memory Interface (PMI), allowing for the retrieval of a significant amount of instruction data in each cycle. The fetched instructions are then placed into an issue FIFO, a buffer capable of holding up to six instructions. This buffer plays a crucial role in managing the flow of instructions to the subsequent execution pipelines. The 64-bit fetch width and the instruction buffer are indicative of a design that aims to ensure a continuous supply of instructions to the pipelines, preventing them from being starved of work. A wider fetch path allows for more instruction bits to be obtained from memory in each clock cycle, while the buffer helps to mitigate temporary delays in instruction fetching.
* '''Execution Unit''': The Execution Unit contains the Integer Pipeline, the Load/Store Pipeline and the Loop Pipeline. All three pipelines operate in parallel and are capable of executing instructions simultaneously. Each pipline has its own decode stage and two execute stages. Furthermore, the TC3xx features a Floating Point Unit (FPU). It is not clear whether the FPU is part of the execution unit or a separate unit. It is assumed that the FPU also has its own decode stage and an unknown number of execute stages
** '''Decode Stage''': Following the Fetch stage, the instruction are issued to one of the pipelines. In the decode stage of each pipeline, the instruction is examined and translated to determine the specific operation it represents and to identify the operands it will operate on. It is assumed that operands are read from the register file during the decode stage.
** '''Execute Stage''': The Execute stage is where the actual operation specified by the instruction is carried out. Pipeline hazards (stalls) are minimised by the use of forwarding paths between pipeline stages allowing the results of one instruction to be used by a following instruction as soon as the result becomes available.
** '''Writeback Stage''': The final stage in the pipeline is the Writeback stage. In this stage, the results produced by the executed instruction are written back to the processor's register file, making them available for subsequent instructions. It is unclear whether the writeback stage is part of the (two) execution stages or a separate stage.

=== Execution Pipelines ===
The TriCore™ TC3xx core leverages four parallel pipelines to enhance its performance. Each pipeline is designed to handle a specific class of instructions:

* '''Integer Pipeline:''' This pipeline is responsible for executing integer arithmetic and logical instructions, including data-conditional jump instructions, bit manipulation operations, as well as division and multiply-accumulate (MAC) instructions.
* '''Load/Store Pipeline:''' The primary function of this pipeline is to manage memory access operations, including loading data from memory and storing data to memory. It also handles address arithmetic, unconditional jump instructions, procedure call instructions, context-switching operations, and control flow related to context save areas (CSAs).
* '''Loop Pipeline:''' This is a specialized pipeline designed to facilitate zero-overhead loops, a technique that significantly improves the performance of iterative code sections. Its design aims to eliminate or minimize the overhead typically associated with loop control, such as incrementing counters and checking loop conditions. Some documentation suggests that the loop pipeline comes along with a "Loop Cache". This dedicated cache would likely be used to store instructions belonging to the loop, enabling very fast access and execution for repeated iterations.
* '''Floating Point Unit (FPU):''' The FPU is responsible for executing floating-point arithmetic operations

=== Store Buffers ===
The TriCore™ TC3xx core include '''Store Buffers''' to decouple memory write operations from CPU instruction execution. All stores from the Load/Store Pipeline are placed in the store buffer prior to being written to local memory or transferred via the bus system. Write data is taken from the store buffers and written to memory when the target memory or bus interface becomes available. In normal operation the CPU will prioritise memory load operations over store operations in order to improve performance unless the store buffer is full or the order of load and store operations must be preserved (e.g. peripheral space access). The store buffer can hold the data for up to 6 stores operations. To improve performance the store buffer will merge consecutive byte, half-word, and word writes of the same location to reduce the number of memory accesses required.

=== Instruction Timing ===

==Functional Safety and Security Features==
===Hardware Security Module and Encryption===
One of the defining features of the AURIX™ TC3xx family is its robust hardware-based security subsystem, implemented to protect against cyber threats and unauthorized manipulation of vehicle systems. Each TC3xx MCU includes a dedicated ''Hardware Security Module'' (HSM), which is essentially an on-chip co-processor with its own CPU and cryptographic engine designed to handle secure operations. In the second-generation AURIX™ (TC3xx), the HSM was upgraded with support for asymmetric cryptography (e.g., RSA, ECC algorithms) in hardware, providing significantly faster public-key encryption and authentication capabilities than pure software implementations. This HSM supports '''EVITA Full''' (the highest level of the EU’s EVITA automotive security requirements), meaning it can perform secure boot, message authentication, and encryption at a level suitable for protecting critical in-vehicle communications. For example, the HSM can encrypt and authenticate CAN/Ethernet messages to prevent spoofing or tampering on the vehicle network, and it can manage cryptographic keys securely isolated from the main application cores.<ref name="ref14281090104">AURIX™ microcontroller TC3xx family of Infineon fuels automated driving and electromobility - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2016/INFATV201610-005.html</ref><ref name="ref2022357806" />

The security module enables features like '''secure boot''', where the AURIX™ will only execute firmware that is digitally signed by the vehicle manufacturer, thereby preventing unauthorized or malicious code. It also facilitates ''over-the-air (OTA) updates'' in a secure manner: the TC3xx HSM can verify and decrypt update packages received via telematics, allowing firmware upgrades while protecting against attackers attempting to hijack the software. In addition, the HSM includes a true random number generator and supports protocols for immobilizer and theft protection systems. Infineon’s implementation essentially treats the HSM as an “embedded smart card” inside the microcontroller. This approach, building on Infineon’s expertise in chip card security, helps to safeguard sensitive assets like cryptographic keys and to perform secure operations (encryption, decryption, authentication) in hardware, making attacks significantly more difficult. The strong cybersecurity provisions of the AURIX™ TC3xx have made it a preferred choice for vehicle gateway ECUs and central body controllers, which are points of entry for connected car communications and thus high-value targets for hackers. By incorporating the HSM, automotive OEMs can implement advanced security features such as encrypted onboard communication (to thwart bus tampering) and secure diagnostics, ensuring the vehicle’s electronic data is protected against cyber threats even as cars become more connected.<ref name="ref14281090104" /><ref name="ref5727814513">Safety Joins Performance: Infineon Introduces Automotive Multicore 32-bit Microcontroller Family AURIX™ to Meet Safety and Powertrain Requirements of Upcoming Vehicle Generations - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2012/INFATV201205-040.html</ref><ref name="ref19484776953">32-bit TriCore™ AURIX™– TC3xx - Infineon Technologies https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/</ref>
=== Functional Safety and Fault Tolerance===
Beyond cybersecurity, the AURIX™ TC3xx architecture is built with extensive ''functional safety'' features to meet the highest safety integrity levels in automotive systems. The multi-core design supports ''lockstep operation'', where redundant checker cores run in parallel with main cores and continuously compare results cycle-by-cycle. In TC3xx devices, up to four of the six TriCore™ CPUs have such lockstep partner cores, allowing the microcontroller to detect any single-point CPU failure instantly (if a discrepancy arises between the core and its checker, a fault is signaled). A ''Safety Management Unit (SMU)'' is integrated on-chip to monitor various fault conditions throughout the device – it aggregates error signals from the lockstep cores, memory ECC monitors, clock/watchdog monitors, and peripheral self-tests, and can initiate safe-state actions (like resetting the chip or signaling an error pin to an external supervisor) if a critical fault is detected. The AURIX™ safety concept also includes a distributed Memory Protection Unit (MPU) arrangement, with multiple memory protection contexts that prevent errant or malicious code from writing to wrong memory areas. This helps contain faults and eases the integration of software with mixed criticality (Infineon allows partitioning software components of different ASIL levels on the same MCU while keeping them isolated).<ref name="ref14281090104" /><ref name="ref5727814513" /><ref name="ref19519075552">Safety Microcontrollers: Texas Instruments Hercules vs Infineon AURIX https://www.linkedin.com/pulse/safety-microcontrollers-texas-instruments-hercules-vs-cook-meng-miet</ref>

Crucially, the TC3xx family was developed according to ISO 26262 processes and can achieve '''ASIL-D''' (Automotive Safety Integrity Level D), the highest grade for automotive functional safety. Compared to a traditional dual-core lockstep approach, the AURIX’s™ multi-core safety architecture allowed Infineon to reduce certain safety development overheads (earlier Infineon data suggested up to 30% reduction in safety software workload) by providing built-in safety mechanisms and diagnostics. Infineon supplies a comprehensive safety manual and diagnostic libraries for the AURIX™, helping engineers utilize features like CPU self-tests, RAM tests, and CRC checks to comply with safety standards. In addition to automotive standards, the AURIX™ TC3xx has also been qualified for '''industrial safety''': in 2023, Infineon announced support for IEC 61508 metrics, enabling designs with AURIX™ to reach SIL-2 and SIL-3 safety integrity levels for industrial applications. This cross-industry safety compliance is facilitated by the MCU’s redundant design and detailed failure mode documentation (FMEDA) provided by Infineon. In summary, the AURIX™ TC3xx integrates both proactive safety (fault prevention via lockstep, monitoring and protection) and reactive safety (fault detection and safe shutdown), making it a dependable component for systems that cannot afford unintended behavior, whether in cars, factories, or aerospace. <ref name="ref14281090104" /><ref name="ref5727814513" /><ref name="ref4967712052">Infineon's AURIX™ & TRAVEO™ microcontroller families extend their support for IEC 61508 hardware and software metrics enabling industrial safety up to SIL-3 - Infineon Technologies https://www.infineon.com/cms/en/about-infineon/press/market-news/2023/INFATV202303-078.html</ref><ref name="ref196858272">MCUs support industrial functional safety - Electronic Products https://www.electronicproducts.com/mcus-support-industrial-functional-safety/</ref>
== Platform Devices ==
The following table shows a feature overview of the AURIX™ TC3xx Platform family focusing on memory and number of cores.
{| class="wikitable"
!
!Feature
!TC33x
!TC33xEXT
!TC35x
!TC36x
!TC37x
!TC37xEXT
!TC38x
!TC39x
|-
| rowspan="2" |CPUs
|Cores / Checker Cores
|1 / 1
|2 / 1
|3 / 2
|2 / 2
|3 / 2
|3 / 3
|4 / 2
|6 / 4
|-
|Max. Freq.
| colspan="8" |300 MHz
|-
| rowspan="2" |Cache per CPU
|Program [KB]
| colspan="8" |32
|-
|Data [KB]
| colspan="8" |16
|-
| rowspan="3" |SRAM per CPU
|PSPR [KB]
|8
|{{rev|32|CPU0}}
{{rev|64|other}}
|64
|32
|64
|64
|64
|64
|-
|DSPR [KB]
|192
|{{rev|192|CPU0}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|192
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|{{rev|240|CPU0&1}}
{{rev|64|other}}
|-
|DLMU [KB]
|8
|{{rev|8|CPU0}}
{{rev|64|other}}
|64
|64
|64
|64
|64
|64
|-
| rowspan="2" |SRAM global
|LMU [KB]
| -
| -
|512
| -
| -
| -
|128
|768
|-
|DAM [KB]
| -
| -
|32
| -
|64
|64
|128
|128
|-
| rowspan="3" |Extension Memory (EMEM)
|TCM [MB]
| -
|1
|2
| -
| -
|2
| -
|2
|-
|XCM [MB]
| -
| -
| -
| -
| -
|1
| -
|2
|-
|XTM [KB]
| -
|16
|16
| -
| -
|16
| -
|16
|-
| rowspan="2" |Program Flash
|Size [MB]
|2
|4
|4
|4
|6
|10
|10
|16
|-
|Banks [MB]
|1 x 2
|2 x 2
|2 x 2
|2 x 2
|2 x 3
|3 x 3, 1 x 1
|3 x 3, 1 x 1
|5 x 3, 1 x 1
|-
| rowspan="2" |Data Flash
|DF0 Size (single-ended) [KB]
|128
|128
|128
|128
|256
|512
|512
|1024
|-
|DF1 Size (single-ended) [KB]
|128
|128
|128
|128
|128
|128
|128
|128
|-
| rowspan="3" |DMA
|Channels
|64
|64
|64
|64
|128
|128
|128
|128
|-
|Move Engines
|2
|2
|2
|2
|2
|2
|2
|2
|-
|Resource Partitions
|4
|4
|4
|4
|4
|4
|4
|4
|}

== Compilers ==
The AURIX™ TC3xx family is a series of high-performance microcontrollers widely used in automotive and industrial applications. Compilers for the AURIX™ TC3xx are crucial for developers aiming to optimize performance, reliability, and safety in their applications. One significant aspect of the compiler landscape for AURIX™ TC3xx is the limited direct support from mainline open-source compilers such as GCC or LLVM/Clang. The primary reason for this is the stringent requirements for functional safety in automotive and industrial applications, which demand specialized features and compliance with safety standards that are often not met by general-purpose open-source compilers.

=== Commercial Compilers ===

# '''Tasking''': Tasking compilers are renowned for their robust support for automotive applications, offering advanced debugging capabilities and optimization techniques tailored for the AURIX™ architecture. They provide extensive code optimization, comprehensive debugging tools, and strong support for safety standards such as ISO 26262, making them ideal for developing high-performance, reliable, and safe applications.
# '''HighTec''': The HighTec compiler is a popular choice, known for its Eclipse-based development environment and strong multicore support. HighTec provides both GCC and LLVM-based ports of open-source compilers tailored specifically for the AURIX™ TC3xx family. These compilers offer efficient parallel execution, advanced code analysis, and an integrated development environment, ensuring robust performance and compliance with safety standards.
# '''Green Hills Software''': Green Hills Software provides a highly optimized toolchain aimed at safety-critical applications, focusing on high performance and strict compliance with automotive standards. Their compiler offers superior optimization, extensive safety features, and a proprietary IDE with specialized tools for automotive development, ensuring developers can meet the stringent demands of functional safety.

=== GCC for AURIX™ ===

While mainline GCC does not directly support the AURIX™ TC3xx family, there is an unofficial GCC version available for AURIX™. Due to the GNU General Public License (GPL), the source code from HighTec was retrieved and, along with binary versions, published on GitHub:

*GCC 4.9.4/Binutils 2.20/Newlib 1.18 for Tricore™ AURIX™ [[https://github.com/volumit/package_494 Source]] [[https://github.com/volumit/tricore_gcc494_mingw_bins Prebuild Mingw Binaries]] [[https://github.com/volumit/tricore_gcc494_linux_bins Prebuild Linux Binaries]]
*GCC 9.4.0/Binutils 2.20/Newlib 1.18 for Tricore™ AURIX™ [[https://github.com/volumit/package_940 Source]] [[https://github.com/volumit/tricore_gcc940_mingw_bins Prebuild Mingw Binaries]] [[https://github.com/volumit/tricore_gcc940_linux_bins Prebuild Linux Binaries]]
*EEESLab's repositories of GCC, Binutils and Newlib for Tricore™ AURIX™ [[https://github.com/EEESlab/tricore-gcc-toolchain-11.3.0 Source]]
*NoMore201's fork of EEESLab's GCC for Tricore™ AURIX™ including GCC, Binutils, Newlib, GDB and QEmu [[https://github.com/NoMore201/tricore-gcc-toolchain Source]] [[https://github.com/NoMore201/tricore-gcc-toolchain/releases/tag/11.3.1-20250101 Sources and prebuilt binaries of gcc-11.3.1 for Linux and Windows]] [[https://github.com/NoMore201/tricore-gcc-toolchain/releases/tag/13.3-20250516 Sources and prebuilt binaries of gcc-13.3.0 for Linux and Windows]]
*GDB 10.0.50 for Tricore™ AURIX™ [[https://github.com/volumit/gdb-tricore Source]]
==emmtrix Tools for AURIX™ TC3xx==
[[File:lowres-Signet Associated Partner EN.eps.png|thumb|305x305px|emmtrix Technologies is an Infineon Associated Partner with over 10 years of experience working with the '''Infineon AURIX™ microcontroller family''' and has been actively collaborating with Infineon for the past five years.|alt=emmtrix Associated Partner]]
emmtrix offers the following tool for the Infineon AURIX™ TC3xx architecture:
=== emmtrix Performance Estimator ===
[[emmtrix Performance Estimator|emmtrix Performance Estimator (ePE)]] provides static timing analysis of C code. Compared to simulation or measurement on hardware, static performance analysis can be applied significantly earlier in the development process and will deliver results on average 6 months earlier compared to a typical automotive HIL setup. The analysis only takes a few minutes at most and runs on the developer’s PC independently of any target hardware. Function developers can analyze their runnables or SWCs without the need of a fully integrated program. emmtrix Performance Estimator is fully compatible with '''Infineon's AURIX™ [[Infineon AURIX TC2xx|TC2xx]] / TC3xx/ [[Infineon AURIX TC4x|TC4x]] microcontroller family,''' ensuring precise and reliable performance analysis for embedded systems.

A unique feature is the combination with TargetLink or Embedded Coder generated code. Without any measurement overhead, our static performance estimation can analyze even the smallest code snippets. This allows us to map the timing analysis to Simulink blocks, giving function developers insight into the timing behavior of their models.

ePE offers three accuracy levels:

* analysis of C code
* generically compiler-optimized code
* assembly code from the target compiler.

Method 1 yields results with minimum effort while method 3 takes the timing of the processor pipeline into account. All methods offer excellent reliability when tracking the tendency of changes in software runtimes e.g. when used in a continuous integration environment.

=== Services ===
====Architecture & Variant Consulting====
* Support in selecting suitable AURIX derivatives for new product generations (trade-offs between performance, price, safety, and peripheral features)
*Analysis of requirements and mapping to specific AURIX product families (e.g., TC3xx vs. TC4xx)
*Analysis/identification of performance margins for down- or upgrades
==== Runtime Analysis & Performance Engineering ====
* Execution of detailed runtime analyses (maximum/minimum vs. average)
* Identification of bottlenecks in program execution, including benchmarking
*Optimization of access to flash, RAM, and peripherals (e.g., cache configuration, DMA utilization)
====Dependency Analysis====
*Freedom from interference (ASIL level check)

==== Multicore Design & Scheduling Concepts ====

* Development of core mapping strategies (static vs. dynamic assignment of compute-intensive tasks)

*Support for integrating bare-metal scheduling on AURIX
*Assistance with architectural decisions to meet functional safety requirements in multicore systems

==== Training & Know-how Transfer ====

* Technical in-house workshops on AURIX optimization, multicore strategies

*Coaching of employees/project teams in performance analysis and systematic tuning
==See Also==

*[[Infineon AURIX TC4x|Infineon AURIX™ TC4x]]
*[[Infineon AURIX TC2xx|Infineon AURIX™ TC2xx]]
*[[TriCore Instruction Set Architecture]]

==External Links==

*https://www.infineon.com/cms/en/product/microcontroller/32-bit-tricore-microcontroller/32-bit-tricore-aurix-tc3xx/
*[https://documentation.infineon.com/aurixtc3xx/docs/qmd1702366622648 AURIX™ TC3xx user manuals]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Part1-UserManual-v02_00-EN.pdf?fileId=5546d462712ef9b701717d3605221d96 AURIX™ TC3xx User Manual Part-1]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Part2-UserManual-v02_00-EN.pdf?fileId=5546d462712ef9b701717d35f8541d94 AURIX™ TC3xx User Manual Part-2]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Architecture_vol1-UserManual-v01_00-EN.pdf?fileId=5546d46276fb756a01771bc4c2e33bdd AURIX™ TC3xx Architecture vol 1]
**[https://www.infineon.com/dgdl/Infineon-AURIX_TC3xx_Architecture_vol2-UserManual-v01_00-EN.pdf?fileId=5546d46276fb756a01771bc4a6d73b70 AURIX™ TC3xx Architecture vol 2]

== References ==
<references />
[[Category:Supported Architectures]]

{{#seo:
|title=Infineon AURIX TC3xx Family – Deep Dive
|description=This deep dive into Infineon's AURIX TC3xx family explores its multi-core TriCore architecture, real-time capabilities, safety and security features and tools
|image=File:AURIX_TC399_LFBGA-516_plain.jpg
|keywords=AURIX, Infineon, TC3xx, microcontroller, TriCore, automotive, ADAS, ISO 26262, functional safety, embedded security, ASIL-D, deep dive
}}

Explicit Cast Insertion Transformation

2025-05-26T14:44:17Z

Tobias.columbus:

{{DISPLAYTITLE:Explicit Cast Insertion Transformation}}

Explicit cast insertion is a transformation that introduces explicit type casts in situations where implicit type conversions would otherwise occur. By making type conversions explicit, this technique improves code clarity, prevents unintended behavior, and enhances static code analysis. It is particularly useful in strongly typed languages, ensuring that conversions are intentional and reducing ambiguity in expressions involving mixed data types. While preserving program semantics, explicit cast insertion helps avoid compiler warnings and improves maintainability by making type changes more transparent.
==Explicit Cast Insertion Transformation in emmtrix Studio==
emmtrix Studio can implement explicit cast insertion using #pragma directives or via the GUI. Cast insertion is a transformation that inserts explicit type casts in situations where implicit type conversion will take place. The transformation preserves the code-semantics.
===Typical Usage and Benefits===
The transformation is used to generate clearer code and to increase capabilities of the code analysis.
===Example===
{| class="wikitable"
|-
| <syntaxhighlight lang="c">
/* The following code tests cast insertion transformation applied to main function.
* In the given example, in expressions sum(a, b), if (a) and x ? a : b, there is implicit type conversion.
* Explicit type casts are inserted in the relevant places.
*/

int sum(int num1, int num2) {
return num1 + num2;
}
#pragma EMX_TRANSFORMATION ExplicitCastInserter
int main(void) {
char a = 5;
char x = 's';
float b = 3.14159;
int c;
sum(a, b);
if (a) {
printf(” % c\ n”, a);
}
c = x ? a : b;
return 0;
}
</syntaxhighlight>
|<syntaxhighlight lang="c">
/* The following code is the generated code after the transformation has been applied.
*/

int sum(int num1, int num2) {
return num1 + num2;
}
int main() {
char a = (char) 5;
char x = (char)
's';
float b = (float) 3.14159;
int c;
sum((int) a, (int) b);
if ((_Bool) a) {
printf(” % c\ n”, a);
}
c = (int)((_Bool) x ? (float) a : b);
return 0;
}
</syntaxhighlight>
|}
[[Category:Code Transformation]]

Constant Propagation Transformation

2025-05-26T14:42:15Z

Tobias.columbus:

{{DISPLAYTITLE:Constant Propagation Transformation}}

Constant propagation is an optimization technique used in compilers to improve execution efficiency by replacing variables with known constant values during compilation. If an expression consists entirely of constants or previously propagated values, it is evaluated at compile time and replaced with its computed result. This transformation reduces runtime computations, simplifies code, and enables further optimizations by minimizing unnecessary variable assignments. By eliminating redundant calculations, constant propagation enhances program performance while preserving its original behavior.
==Constant Propagation Transformation in emmtrix Studio==
emmtrix Studio implements constant propagation using #pragma directives or via the GUI. Constant propagation is a transformation that propagates all known variable values within the block it is applied to. If an expression consists of propagated values and of constants, it will itself be evaluated and replaced with its constant value.

All arithmetic operations for integral types are supported. Interprocedural propagation, i.e. propagating into and out of function calls, is partially supported.

===Typical Usage and Benefits===
Constant propagation is typically used to generate a clearer code, to reduce complexity for dependency analysis and increase potential for better optimization possibilities.
===Example===
{| class="wikitable"
|-
|<syntaxhighlight lang="c">
/* The following code tests constant propagation applied to main function.
* In the given example, variables a, b and c are known.
* They are propagated to the rest of the body of main.
*/

#pragma EMX_TRANSFORMATION ConstPropagation
int main(void) {
int a = 2;
int b = a;

int c, d;
c = 2 + 2;
d = b + c;

return 0;
}
</syntaxhighlight>
|<syntaxhighlight lang="c">
/* The following code is the generated code after the transformation has been applied.
*/

int main(void) {
int a = 2;
int b = a;
int c;
int d;

c = 4;
d = 6;

return 0;
}
</syntaxhighlight>
|}

=== Parameters ===
{| class="wikitable"
|+
!Id
!Possible Values
!Default Value
!Description
|-
|<code>global</code>
|<code>true, false</code>
|<code>false</code>
|Determines whether the constant propagation should work across function boundaries
|-
|<code>modify_nonstatic_functions</code>
|<code>true, false</code>
|<code>false</code>
|Determines whether the constant propagation may modify non-static functions. This should be used with care as it might be illegal if not all call-sites of the non-static functions are known.
|-
|<code>remove_dead_blocks</code>
|<code>no, defensive, aggressive</code>
|<code>no</code>
|Determines whether parts of the code that are unreachable after constant propagation should be removed. The <code>aggressive</code> variant might seldomly insert additional <code>goto</code> statements in cases where the<code>defensive</code> variant rather keeps some unreachable parts of the code to avoid <code>goto</code> statements.
|}
[[Category:Code Transformation]]

Constant Propagation Transformation

2025-05-26T14:39:31Z

Tobias.columbus:

Constant propagation is an optimization technique used in compilers to improve execution efficiency by replacing variables with known constant values during compilation. If an expression consists entirely of constants or previously propagated values, it is evaluated at compile time and replaced with its computed result. This transformation reduces runtime computations, simplifies code, and enables further optimizations by minimizing unnecessary variable assignments. By eliminating redundant calculations, constant propagation enhances program performance while preserving its original behavior.
==Constant Propagation Transformation in emmtrix Studio==
emmtrix Studio implements constant propagation using #pragma directives or via the GUI. Constant propagation is a transformation that propagates all known variable values within the block it is applied to. If an expression consists of propagated values and of constants, it will itself be evaluated and replaced with its constant value.

All arithmetic operations for integral types are supported. Interprocedural propagation, i.e. propagating into and out of function calls, is partially supported.

===Typical Usage and Benefits===
Constant propagation is typically used to generate a clearer code, to reduce complexity for dependency analysis and increase potential for better optimization possibilities.
===Example===
{| class="wikitable"
|-
|<syntaxhighlight lang="c">
/* The following code tests constant propagation applied to main function.
* In the given example, variables a, b and c are known.
* They are propagated to the rest of the body of main.
*/

#pragma EMX_TRANSFORMATION ConstPropagation
int main(void) {
int a = 2;
int b = a;

int c, d;
c = 2 + 2;
d = b + c;

return 0;
}
</syntaxhighlight>
|<syntaxhighlight lang="c">
/* The following code is the generated code after the transformation has been applied.
*/

int main(void) {
int a = 2;
int b = a;
int c;
int d;

c = 4;
d = 6;

return 0;
}
</syntaxhighlight>
|}

=== Parameters ===
{| class="wikitable"
|+
!Id
!Possible Values
!Default Value
!Description
|-
|<code>global</code>
|<code>true, false</code>
|<code>false</code>
|Determines whether the constant propagation should work across function boundaries
|-
|<code>modify_nonstatic_functions</code>
|<code>true, false</code>
|<code>false</code>
|Determines whether the constant propagation may modify non-static functions. This should be used with care as it might be illegal if not all call-sites of the non-static functions are known.
|-
|<code>remove_dead_blocks</code>
|<code>no, defensive, aggressive</code>
|<code>no</code>
|Determines whether parts of the code that are unreachable after constant propagation should be removed. The <code>aggressive</code> variant might seldomly insert additional <code>goto</code> statements in cases where the<code>defensive</code> variant rather keeps some unreachable parts of the code to avoid <code>goto</code> statements.
|}
[[Category:Code Transformation]]

Constant Propagation Transformation

2025-02-14T15:01:40Z

Tobias.columbus:

Constant propagation is an optimization technique used in compilers to improve execution efficiency by replacing variables with known constant values during compilation. If an expression consists entirely of constants or previously propagated values, it is evaluated at compile time and replaced with its computed result. This transformation reduces runtime computations, simplifies code, and enables further optimizations by minimizing unnecessary variable assignments. By eliminating redundant calculations, constant propagation enhances program performance while preserving its original behavior.
==Constant Propagation Transformation in emmtrix Studio==
emmtrix Studio implements constant propagation using #pragma directives or via the GUI. Constant propagation is a transformation that propagates all known variable values within the block it is applied to. If an expression consists of propagated values and of constants, it will itself be evaluated to and replaced with its constant value.

All arithmetic operations for integral types are supported. Interprocedural propagation, i.e. propagating into and out of function calls, is partially supported.

===Typical Usage and Benefits===
Constant propagation is typically used to generate a clearer code, to reduce complexity for dependency analysis and increase potential for better optimization possibilities.
===Example===
{| class="wikitable"
|-
|<syntaxhighlight lang="c">
/* The following code tests constant propagation applied to main function.
* In the given example, variables a, b and c are known.
* They are propagated to the rest of the body of main.
*/

#pragma EMX_TRANSFORMATION ConstPropagation
int main(void) {
int a = 2;
int b = a;

int c, d;
c = 2 + 2;
d = b + c;

return 0;
}
</syntaxhighlight>
|<syntaxhighlight lang="c">
/* The following code is the generated code after the transformation has been applied.
*/

int main(void) {
int a = 2;
int b = a;
int c;
int d;

c = 4;
d = 6;

return 0;
}
</syntaxhighlight>
|}

=== Parameters ===
{| class="wikitable"
|+
!Id
!Possible Values
!Default Value
!Description
|-
|<code>global</code>
|<code>true, false</code>
|<code>false</code>
|Determines whether the constant propagation should work across function boundaries
|-
|<code>modify_nonstatic_functions</code>
|<code>true, false</code>
|<code>false</code>
|Determines whether the constant propagation may modify non-static functions. This should be used with care as it might be illegal if not all call-sites of the non-static functions are known.
|-
|<code>remove_dead_blocks</code>
|<code>no, defensive, aggressive</code>
|<code>no</code>
|Determines whether parts of the code that are unreachable after constant propagation should be removed. The <code>aggressive</code> variant might seldomly insert additional <code>goto</code> statements in cases where the<code>defensive</code> variant rather keeps some unreachable parts of the code to avoid <code>goto</code> statements.
|}
[[Category:Code Transformation]]

Constant Propagation Transformation

2025-02-14T13:30:27Z

Tobias.columbus:

Constant propagation is an optimization technique used in compilers to improve execution efficiency by replacing variables with known constant values during compilation. If an expression consists entirely of constants or previously propagated values, it is evaluated at compile time and replaced with its computed result. This transformation reduces runtime computations, simplifies code, and enables further optimizations by minimizing unnecessary variable assignments. By eliminating redundant calculations, constant propagation enhances program performance while preserving its original behavior.
==Constant Propagation Transformation in emmtrix Studio==
emmtrix Studio implements constant propagation using #pragma directives or via the GUI. Constant propagation is a transformation that propagates all known variable values within the block it is applied to. If an expression consists of propagated values and of constants, it will itself be evaluated to and replaced with its constant value.

All arithmetic operations for integral types are supported. Interprocedural propagation, i.e. propagating into and out of function calls, is partially supported.

===Typical Usage and Benefits===
Constant propagation is typically used to generate a clearer code, to reduce complexity for dependency analysis and increase potential for better optimization possibilities.
===Example===
{| class="wikitable"
|-
|<syntaxhighlight lang="c">
/* The following code tests constant propagation applied to main function.
* In the given example, variables a, b and c are known.
* They are propagated to the rest of the body of main.
*/

#pragma EMX_TRANSFORMATION ConstPropagation
int main(void) {
int a = 2;
int b = a;

int c, d;
c = 2 + 2;
d = b + c;

return 0;
}
</syntaxhighlight>
|<syntaxhighlight lang="c">
/* The following code is the generated code after the transformation has been applied.
*/

int main(void) {
int a = 2;
int b = a;
int c;
int d;

c = 4;
d = 6;

return 0;
}
</syntaxhighlight>
|}

=== Parameters ===
{| class="wikitable"
|+
!Id
!Possible Values
!Default Value
!Description
|-
|<code>global</code>
|<code>true, false</code>
|<code>true</code>
|Determines whether the constant propagation should work across function boundaries
|-
|<code>modify_nonstatic_functions</code>
|<code>true, false</code>
|<code>false</code>
|Determines whether the constant propagation may modify non-static functions. This should be used with care as it might be illegal if not all call-sites of the non-static functions are known.
|-
|<code>remove_dead_blocks</code>
|<code>no, defensive, aggressive</code>
|<code>no</code>
|Determines whether parts of the code that are unreachable after constant propagation should be removed. The <code>aggressive</code> variant might seldomly insert additional <code>goto</code> statements in cases where the<code>defensive</code> variant rather keeps some unreachable parts of the code to avoid <code>goto</code> statements.
|}
[[Category:Code Transformation]]

Obfuscation and Anonymization Transformation

2025-02-14T13:17:07Z

Tobias.columbus:

Obfuscation is a code transformation technique used to make source code difficult to read and understand while preserving its functionality. This process typically involves renaming identifiers, restructuring code, or inserting misleading elements to obscure the original logic. Obfuscation is often used to protect intellectual property, prevent reverse engineering, or secure sensitive logic in software. While the transformed code remains executable, it becomes significantly harder for humans to analyze, ensuring that key implementation details are concealed without altering program behavior.
==Obfuscation Transformation in emmtrix Studio==
emmtrix Studio implements obfuscation using #pragma directives or via the GUI. Obfuscation is a transformation that renames identifiers so that they become obscure. This feature is typically used to ensure that the code is unrecognizable. Functionality of the code and its original structure are preserved. The algorithms used are Secure Hash Algorithms SHA-1 and SHA-256.
===Typical Usage and Benefits===
The transformation is used make the source code hard to understand for humans while still preserving the original structure of the source code. It is meant for cases where the source code needs to be shared (e.g. for debugging) but no intellectual property should be shown.The transformation can be applied only to functions.

Even though the transformation is selectable only for functions, it can affect other identifiers, as well, depending on the user settings. In its full scope, obfuscation affects all identifiers, including:

* functions and their parameters
* global and local variables
* user-defined types
* structs and unions
* enumerators
* file names

===Example===
{| class="wikitable"
|-
|<syntaxhighlight lang="c">
/* The following code tests obfuscation transformation applied to main function with default parameters.
* According to the default settings, all identifiers except for the external definitions and the main func-
tion, shall be renamed and become obscure.
* In the current code example the identifiers with the suffix _obfu are renamed.
* Other identifiers include printf and main functions and they remain unmodified.
*/

const int g_obfu = 10;
void print_obfu(int a_obfu) {
printf(” % d\ n”, a_obfu);
}
#pragma EMX_TRANSFORMATION ObfuscateIdentifiers
int main() {
int l_obfu = 1;
print_obfu(l_obfu);
print_obfu(g_obfu);
return 0;
}
</syntaxhighlight>
|<syntaxhighlight lang="c">
/* The following code is the generated code after the transformation has been applied.
*/

const int var_ee832f = 10;
void func_3db980(int var_e86e08) {
printf(” % d\ n”, var_e86e08);
}
void func_baf390(int var_e86e08) {
printf(” % d\ n”, var_e86e08);
}
int main() {
int var_32bc72 = 1;
func_baf390(var_32bc72);
func_3db980(var_ee832f);
return 0;
}
</syntaxhighlight>
|}Along with the transformed code, a mapping between the old and the new identifiers is created. It is stored in a CSV file obfuscation_mapping.csv.<syntaxhighlight lang="c">
file_b93f1b;test_obfuscation00
func_3db980;print_obfu
func_baf390;print_obfu_duplicate2
var_e86e08;a_obfu
var_ee832f;g_obfu
var_32bc72;l_obfu
</syntaxhighlight>
===Parameters===
Following parameters can be set (each description is followed by keyword in pragma-syntax and default value):
{| class="wikitable"
|+
!Id
!Default Value
!Description
|-
|<code>all</code>
|true
|'''Whole Project''' - apply obfuscation on all translation units across project
|-
|<code>external</code>
|false
|'''External definitions''' - apply obfuscation on identifiers in header files; use with caution, since it affects used system identifiers and produces uncompilable code
|-
|<code>output</code>
|true
|'''Output identifiers''' - generate CSV file containing mapping of old and new names
|-
|<code>seed</code>
|enc1
|'''Seed for hash-function''' - arbitrary string used as input for hashing algorithms
|-
|<code>n</code>
|6
|'''Hash-length''' - length of hash code in obfuscated identifiers
|}
===Note===
*For same seeds and hash-lengths, obfuscation is deterministic.
[[Category:Code Transformation]]

emmtrix Performance Estimator

2024-04-18T11:41:45Z

Tobias.columbus: Created page with "emmtrix Performance Estimator (ePE) supports different ways to acquire the duration of the tasks of an application. These methods vary in accuracy and additional software or hardware requirements. Static code analysis provides basic information without the need for hardware or special software and may thus be seamlessly incorporated into early stages of the Software Development Life Cycle (SDLC). More accurate numbers can be collected with interfaces to simulators or the..."

emmtrix Performance Estimator (ePE) supports different ways to acquire the duration of the tasks of an application. These methods vary in accuracy and additional software or hardware requirements. Static code analysis provides basic information without the need for hardware or special software and may thus be seamlessly incorporated into early stages of the Software Development Life Cycle (SDLC). More accurate numbers can be collected with interfaces to simulators or the hardware. Depending on the requirements, the methods can be combined as desired.

Addressing performance issues at the onset of the SDLC is not only proactive but also cost-efficient. Early estimation and intervention, as suggested by the below graph, can drastically reduce the complexities and expenses associated with fixing defects post-deployment. Although early estimates may not be as precise as measurements taken during later stages, they serve as a crucial checkpoint to prevent potential timing issues from escalating. This preemptive approach aligns with the principle that the cost to repair defects increases exponentially as they progress through the SDLC, as shown by the sharp rise in cost depicted in the graph. Hence, initial performance estimations are a strategic investment, minimizing the risk of facing a steep climb in remediation costs and efforts at later stages.
[[File:DefectDetectionandRemediation.webp|center|frameless|800x800px|Cost of Defect Remediation across the Software Development Life Cycle]]

File:DefectDetectionandRemediation.webp

2024-04-18T11:36:38Z

Tobias.columbus:

Graph showing cost of remediation of defects across the SDLC

Main Page

2024-04-18T11:33:27Z

Tobias.columbus:

<languages/>
<translate>


Welcome to the emmtrix Technologies Wiki. As a company with a deep-rooted passion for compilers, we specialize in source-to-source compilers designed to analyze, optimize and transform your code. This Wiki aims to offer detailed, technical background information that complements the tools and resources available on our official website. Here, you'll find in-depth explanations, usage guidelines, and insights into the engineering behind our specialized software solutions. Whether you're a developer or a technically-inclined enthusiast, this space is designed to deepen your understanding of what makes our tools essential for your projects.


=== emmtrix Products ===


* [[emmtrix Studio Release Notes]]
* emmtrix Parallel Studio
* [[emmtrix Performance Estimator]]
* [[emmtrix C++ to C Compiler]]
** [https://online-ecpp2c.emmtrix.com Live C++ to C compiler demo]

</translate>

=== Compiler Background ===

* [[Loop Transformations]]
*[[Demystifying C++]]
*[[The alias Attribute|The alias attribute]]
*[[Clang Diagnostics Overview]]
*[[:Category:Clang Diagnostics]]

=== FAQ ===

* [[Error Handling]]

The alias Attribute - Some things I learned about the alias attribute

2024-03-11T15:12:53Z

Tobias.columbus:

<seo title="Some things I learned about the alias attribute"
description="A deep dive into the pre- and post-C23 syntax and semantics of the alias attribute in GNU C, with fun examples for both GCC and clang."
keywords="alias attribute, alias attribute on variables, GNU C attributes, C23 attributes, symbol table"
robots="index, follow"
og:title="Some things I learned about the alias attribute"
og:type="website"
og:description="A deep dive into the pre- and post-C23 syntax and semantics of the alias attribute in GNU C, with fun examples for both GCC and clang."
/>

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.
== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer]. Just make sure that you don't omit the flag <code>-std=c23</code> when invoking clang.

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some address in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.
The columns are also explained in <code>objdump</code>'s [https://man7.org/linux/man-pages/man1/objdump.1.html manpage] and reading through <code>nm</code> 's [https://man7.org/linux/man-pages/man1/nm.1.html manpage] might give some further information if you're really curious.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are highly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute from a slightly different perspective.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

-----

<references />

[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-03-11T15:11:45Z

Tobias.columbus:

<seo title="Some things I learned about the alias attribute"
description="A deep dive into the pre- and post-C23 syntax and semantics of the alias attribute in GNU C, with fun examples for both GCC and clang."
keywords="alias attribute, alias attribute on variables, GNU C attributes, C23 attributes, symbol table"
robots="index, follow"
og:title="Some things I learned about the alias attribute"
og:type="website"
og:description="A deep dive into the pre- and post-C23 syntax and semantics of the alias attribute in GNU C, with fun examples for both GCC and clang."
google-site-verification"="OkCmr1SjqUIZTGUdEvGSYWmj36SN9CCuhvH8lbDx5Qg"
/>

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.
== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer]. Just make sure that you don't omit the flag <code>-std=c23</code> when invoking clang.

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some address in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.
The columns are also explained in <code>objdump</code>'s [https://man7.org/linux/man-pages/man1/objdump.1.html manpage] and reading through <code>nm</code> 's [https://man7.org/linux/man-pages/man1/nm.1.html manpage] might give some further information if you're really curious.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are highly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute from a slightly different perspective.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

-----

<references />

[[Category:Compiler Background]]

Demystifying C++ - Range-Based for Loops

2024-02-28T08:00:35Z

Tobias.columbus: seo block

{{#seo:
|title=Emulating C++ Range-Based For Loops in C: A Transpiler Perspective
|description=This article explores our transpiler's approach to preserving range-based loop behavior and temporary variable lifespan during C++ to C translation.
|keywords=range-based for loops, C++17, C programming, transpiler, code translation, modern C++, loop emulation, software development techniques, programming best practices
|robots=index, follow
}}

Range-based for loops in modern C++ offer a neat and intuitive way to iterate over the elements of a container or array. Compared to traditional loops where indices or iterators need to be explicitly managed, range-based for-loops offer a more concise and less error-prone syntax.

Here's the substitute code for the loop that is written in the C++17 standard:

{| class="wikitable"
|-
!Substitute Code
|<pre>
for (range-declaration : range-expression) {
...
}

</pre>
|<pre>
auto && __range = range-expression;
auto __begin = begin-expr;
auto __end = end-expr;
for ( ; __begin != __end; ++__begin) {
range-declaration = *__begin;

...
}
</pre>
|}

The following example showcases the C-code for a simple instance with `std::initializer_list`. The code follows the principle of the substitute code:

{| class="wikitable"
|-
!Range-based for loop
with std::initializer_list
|<pre>
#include <initializer_list>

void work(int);

void func() {
for (int i : {1, 2, 3}) {
work(i);
}
}

</pre>
|<pre>
struct std::initializer_list<int> {
const int *__begin_;
size_t __size_;
};

inline const int *std::initializer_list<int>::begin(const struct std::initializer_list<int> *this) {
return this->__begin_;
}
inline const int *std::initializer_list<int>::end(const struct std::initializer_list<int> *this) {
return this->__begin_ + this->__size_;
}

void work(int);

void func(void) {
{
const int init[3] = {1, 2, 3};
struct std::initializer_list<int> tmpExpr1 = {init, 3};
struct std::initializer_list<int> *__range1 = &tmpExpr1;
const int *__begin1 = std::initializer_list<int>::begin(__range1);
const int *__end1 = std::initializer_list<int>::end(__range1);
for (; __begin1 != __end1; ++__begin1) {
int i = *__begin1;
work(i);
}
}
}

</pre>
|}

This mechanism ensures that the correct lifespan of temporary variables is maintained, preserving the intended behavior of the original C++ code when translating to C.
[[Category:Demystifying C++|Range-Based_for_Loops]]

Demystifying C++ - Templates

2024-02-28T07:57:43Z

Tobias.columbus: seo block

{{#seo:
|title=Transpiling C++ Templates into C: Bridging Generic Programming Concepts
|description=Discover how C++ templates, a cornerstone of generic programming, are transpiled into C.
|keywords=C++ templates, generic programming, template instantiation, code duplication, C++ to C transpiler, data types, function templates, class templates, programming languages, software development
|robots=index, follow
}}

Templates [https://en.cppreference.com/w/cpp/language/templates] are a fundamental feature of C++ essential for generic programming. They allow programmers to write code that is independent of the data type, enhancing the reusability of the code. Templates are not limited to simple data types; they can also be used with custom types such as classes and structures.

In C++, a template is introduced with the keyword <code>template</code>, followed by a template parameter list in angle brackets (<code><></code>). The compiler then creates a new function or class from the template when it encounters a declaration with a specific type. This technique is called template instantiation. The C++ to C compiler realizes templates through the duplication of code. For each template instance of a function or class, a variant is also generated in the C code. If a template is not used, it completely disappears from the code.

C++ templates enable the creation of functions that can work with any data type. Here's a simple example in C++:

{| class="wikitable"
!Template Function
|<pre>
template <typename T>
T max(T a, T b) {
return (a > b) ? a : b;
}

void func() {
int a = max<int>(10, 20);
float f = max<float>(10.0, 20.0);

...
}
</pre>
|<pre>
int max_int(int a, int b) {
return (a > b) ? a : b;
}

float max_float(float a, float b) {
return (a > b) ? a : b;
}

void func(void) {
int a = max_int(10, 20);
float f = max_float(10.0f, 20.0f);

...
}

</pre>
|-
!Template Class
|<pre>
template <class T, int N1, int N2>
class Matrix {
public:
T data[N1][N2];
};

Matrix<int, 5, 5> m1;
</pre>
|<pre>
struct Matrix_int_3_5 {
int data[3][5];
};

struct Matrix_int_3_5 m1;

</pre>
|}

[[Category:Demystifying C++|Templates]]

Demystifying C++ - Strict Return

2024-02-28T07:55:01Z

Tobias.columbus: deo block

{{#seo:
|title=Handling Missing Return Statements in C and C++: Compiler Strategies and Code Stability
|description=Explore how missing return statements in C and C++ functions can lead to undefined behavior, and how our transpiler addresses this issue.
|keywords=missing return statement, transpiler, undefined behavior, C programming, C++ programming, compiler warnings, __builtin_unreachable, clang compiler, GCC compiler, software development best practices
|robots=index, follow
}}

In C and C++ programming, ensuring that functions behave predictably and efficiently is paramount. One particular scenario that often requires attention is when a non-void function fails to return a value on all control paths, potentially leading to undefined behavior and compromising the stability of the program. This situation is commonly flagged by compilers, which provide warnings to alert developers of potential issues in the code.

In the following example, a function with missing <code>return</code> statement is translated. Surprisingly, even that the input code only uses C constructs, the semantic equivalent C code contains <code>__builtin_unreachable</code> as additional function call. <code>__builtin_unreachable</code> is an builtin function available in clang and GCC compiler that marks unreachable code. If control flow reaches the point of the <code>__builtin_unreachable</code>, the program is undefined. It is useful in situations where the compiler cannot deduce the unreachability of the code. (see https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html).

{| class="wikitable"
|-
!Code with missing return
|<pre>
int func1(void* ptr);

int func2(void* ptr) {
if (ptr)
return func1(ptr);

// warning: non-void function does not
// return a value in all control paths
}

</pre>
|<pre>
int func1(void* ptr);

int func2(void* ptr) {
if (ptr)
return func1(ptr);

__builtin_unreachable();
}

</pre>
|}
The reason for this is that C++ and C have different requirements regarding missing <code>return</code> within the standard. In C11 the standard says that<blockquote>'''If the '}' that terminates a function is reached, and the value of the function call is used by the caller, the behavior is undefined. (6.9.1p12)'''</blockquote>That means a function with missing <code>return</code> is only undefined behavior if the return value is used. In C++ the standard says that<blockquote>'''Flowing off the end of a function [...] results in undefined behavior in a value-returning function. ([stmt.return]p2)'''</blockquote>which means that in C++ any function with missing <code>return</code> is undefined behavior independent if it is used or not. In contrast to C, the clang compiler marks the position within the source code as unreachable in case of a missing <code>return</code> in C++. Within the compiler frontend, that behavior is called '''strict return'''. To mimic strict <code>return</code> also in C, the <code>__builtin_unreachable</code> must be added in the generated C source code.

However, marking code paths as unreachable by the compiler frontend in case of missing <code>return</code> can lead to strange effects that every developer should be aware of. In the following code, the C code before and after optimization is shown:
{| class="wikitable"
!After frontend (before optimization)
!After optimization
|-
|<pre>
int func1(void* ptr);

int func2(void* ptr) {
if (ptr)
return func1(ptr);

__builtin_unreachable();
}

</pre>
|<pre>
int func1(void* ptr);

int func2(void* ptr) {
return func1(ptr);
}

</pre>
|}
During optimization the compiler recognizes two code path. If the condition is true, the result of func1 is returned. Otherwise, the code is unreachable. As code that is unreachable should never be reached, the optimizers thinks that the condition is meaningless and optimizes it away. That means for an end users, that a missing <code>return</code> cannot only lead to run-time errors at the location where the <code>return</code> is missing but can even influence code before! This optimization is reproducible both for clang and gcc compiler.

For that reason, missing <code>return</code> warnings should be taken seriously and either enable an error in that case with <code>-Werror=return-type</code> or deactivate strict <code>return</code> within the compiler using <code>--no-strict-return</code>.
[[Category:Demystifying C++]]

Demystifying C++ - Strict Return

2024-02-28T07:53:11Z

Tobias.columbus: code markup for return

In C and C++ programming, ensuring that functions behave predictably and efficiently is paramount. One particular scenario that often requires attention is when a non-void function fails to return a value on all control paths, potentially leading to undefined behavior and compromising the stability of the program. This situation is commonly flagged by compilers, which provide warnings to alert developers of potential issues in the code.

In the following example, a function with missing <code>return</code> statement is translated. Surprisingly, even that the input code only uses C constructs, the semantic equivalent C code contains <code>__builtin_unreachable</code> as additional function call. <code>__builtin_unreachable</code> is an builtin function available in clang and GCC compiler that marks unreachable code. If control flow reaches the point of the <code>__builtin_unreachable</code>, the program is undefined. It is useful in situations where the compiler cannot deduce the unreachability of the code. (see https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html).

{| class="wikitable"
|-
!Code with missing return
|<pre>
int func1(void* ptr);

int func2(void* ptr) {
if (ptr)
return func1(ptr);

// warning: non-void function does not
// return a value in all control paths
}

</pre>
|<pre>
int func1(void* ptr);

int func2(void* ptr) {
if (ptr)
return func1(ptr);

__builtin_unreachable();
}

</pre>
|}
The reason for this is that C++ and C have different requirements regarding missing <code>return</code> within the standard. In C11 the standard says that<blockquote>'''If the '}' that terminates a function is reached, and the value of the function call is used by the caller, the behavior is undefined. (6.9.1p12)'''</blockquote>That means a function with missing <code>return</code> is only undefined behavior if the return value is used. In C++ the standard says that<blockquote>'''Flowing off the end of a function [...] results in undefined behavior in a value-returning function. ([stmt.return]p2)'''</blockquote>which means that in C++ any function with missing <code>return</code> is undefined behavior independent if it is used or not. In contrast to C, the clang compiler marks the position within the source code as unreachable in case of a missing <code>return</code> in C++. Within the compiler frontend, that behavior is called '''strict return'''. To mimic strict <code>return</code> also in C, the <code>__builtin_unreachable</code> must be added in the generated C source code.

However, marking code paths as unreachable by the compiler frontend in case of missing <code>return</code> can lead to strange effects that every developer should be aware of. In the following code, the C code before and after optimization is shown:
{| class="wikitable"
!After frontend (before optimization)
!After optimization
|-
|<pre>
int func1(void* ptr);

int func2(void* ptr) {
if (ptr)
return func1(ptr);

__builtin_unreachable();
}

</pre>
|<pre>
int func1(void* ptr);

int func2(void* ptr) {
return func1(ptr);
}

</pre>
|}
During optimization the compiler recognizes two code path. If the condition is true, the result of func1 is returned. Otherwise, the code is unreachable. As code that is unreachable should never be reached, the optimizers thinks that the condition is meaningless and optimizes it away. That means for an end users, that a missing <code>return</code> cannot only lead to run-time errors at the location where the <code>return</code> is missing but can even influence code before! This optimization is reproducible both for clang and gcc compiler.

For that reason, missing <code>return</code> warnings should be taken seriously and either enable an error in that case with <code>-Werror=return-type</code> or deactivate strict <code>return</code> within the compiler using <code>--no-strict-return</code>.
[[Category:Demystifying C++]]

Demystifying C++ - Cleanup Code

2024-02-28T07:47:53Z

Tobias.columbus:

{{#seo:
|title=Transpiling C++ RAII cleanup code to C: Bridging Modern Resource Management
|description=Explore the transpilation of C++'s RAII idiom into C, showcasing the capabilities of our C++ transpiler.
|keywords=RAII, Resource Acquisition Is Initialization, cleanup code, C++ to C transpiler, automatic cleanup, resource management software development tools
|robots=index, follow
}}

The '''RAII (Resource Acquisition Is Initialization)''' idiom is pivotal in modern C++. It ensures that resources are properly released and destructors are correctly called as variables and objects go out of their scope. In C++, leveraging the RAII idiom means the cleanup code is automatically generated and inserted as needed, especially in scenarios with complex control structures like loops and branches. This idiom guarantees that in the event of premature exits from a block due to statements like <code>return</code>, <code>break</code>, <code>continue</code>, or via jumps with <code>goto</code>, the cleanup code for the respective blocks will be executed correctly, ensuring resource and exception safety.

Interestingly, the clang C++ frontend doesn't directly insert this cleanup code right before such statements. Instead, the cleanup code is generated only at one location and jumped to directly. A state variable and a switch block at the end of the cleanup code ensure that the control flow continues at the original location.

At first glance, this approach might seem inefficient as it adds additional code for the state variable and <code>switch</code> blocks. However, from optimization level -O1 onwards, in later compiler phases, this overhead gets eliminated by compiler optimizations like Jump Threading [https://beza1e1.tuxen.de/articles/jump_threading.html]. In this process, the cleanup code gets duplicated, and the state variable and the <code>switch</code> blocks can be removed, making the generated code more efficient and straightforward.

In the C implementation, as shown in the example, the state variable like <code>cleanupDestSlot</code> is used to determine the jump destination after executing the cleanup code. The <code>goto</code> mechanism is then used to jump to the relevant cleanup code and then onward to the final destination, based on the value of the state variable.

{| class="wikitable"
|-
!Cleanup Code
|<pre>
void func() {

ClassWithDtor var1;

for (int i = 0; i < 10; ++i) {
ClassWithDtor var2;

for (int j = 0; j < 10; ++j) {
ClassWithDtor var3;

if (i == 5) {

continue;
}
if (i == 9) {

return;
}

// ...

}

// ...

}

// ...

}

</pre>
|<pre>
void func(void) {
unsigned int cleanupDestSlot;
struct ClassWithDtor var1;

for (int i = 0; i < 10; ++i) {
struct ClassWithDtor var2;

for (int j = 0; j < 10; ++j) {
struct ClassWithDtor var3;

if (i == 5) {
cleanupDestSlot = 1;
goto __cleanup1;
}
if (i == 9) {
cleanupDestSlot = 2;
goto __cleanup1;
}

// ...

cleanupDestSlot = 0;
__cleanup1:
ClassWithDtor::__ctor_complete(&var3);
switch (cleanupDestSlot) {
case 2: goto __cleanup3;
}
}

// ...

cleanupDestSlot = 0;
__cleanup3:
ClassWithDtor::__ctor_complete(&var2);
switch (cleanupDestSlot) {
case 2: goto __cleanup2;
}
}

// ...

__cleanup2:
ClassWithDtor::__ctor_complete(&var1);
}

</pre>
|}

This cleanup mechanism ensures that even in complex control flow scenarios, all required cleanup operations are executed, maintaining the integrity and safety of the program.
[[Category:Demystifying C++|Cleanup_Code]]

Demystifying C++ - Cleanup Code

2024-02-28T07:45:58Z

Tobias.columbus: seo block

{{#seo:
|title=Transpiling C++ RAII to C: Bridging Modern Resource Management
|description=Explore the transpilation of C++'s RAII idiom into C, showcasing the capabilities of our C++ transpiler.
|keywords=RAII, Resource Acquisition Is Initialization, cleanup code, C++ to C transpiler, automatic cleanup, resource management software development tools
|robots=index, follow
}}

The '''RAII (Resource Acquisition Is Initialization)''' idiom is pivotal in modern C++. It ensures that resources are properly released and destructors are correctly called as variables and objects go out of their scope. In C++, leveraging the RAII idiom means the cleanup code is automatically generated and inserted as needed, especially in scenarios with complex control structures like loops and branches. This idiom guarantees that in the event of premature exits from a block due to statements like <code>return</code>, <code>break</code>, <code>continue</code>, or via jumps with <code>goto</code>, the cleanup code for the respective blocks will be executed correctly, ensuring resource and exception safety.

Interestingly, the clang C++ frontend doesn't directly insert this cleanup code right before such statements. Instead, the cleanup code is generated only at one location and jumped to directly. A state variable and a switch block at the end of the cleanup code ensure that the control flow continues at the original location.

At first glance, this approach might seem inefficient as it adds additional code for the state variable and <code>switch</code> blocks. However, from optimization level -O1 onwards, in later compiler phases, this overhead gets eliminated by compiler optimizations like Jump Threading [https://beza1e1.tuxen.de/articles/jump_threading.html]. In this process, the cleanup code gets duplicated, and the state variable and the <code>switch</code> blocks can be removed, making the generated code more efficient and straightforward.

In the C implementation, as shown in the example, the state variable like <code>cleanupDestSlot</code> is used to determine the jump destination after executing the cleanup code. The <code>goto</code> mechanism is then used to jump to the relevant cleanup code and then onward to the final destination, based on the value of the state variable.

{| class="wikitable"
|-
!Cleanup Code
|<pre>
void func() {

ClassWithDtor var1;

for (int i = 0; i < 10; ++i) {
ClassWithDtor var2;

for (int j = 0; j < 10; ++j) {
ClassWithDtor var3;

if (i == 5) {

continue;
}
if (i == 9) {

return;
}

// ...

}

// ...

}

// ...

}

</pre>
|<pre>
void func(void) {
unsigned int cleanupDestSlot;
struct ClassWithDtor var1;

for (int i = 0; i < 10; ++i) {
struct ClassWithDtor var2;

for (int j = 0; j < 10; ++j) {
struct ClassWithDtor var3;

if (i == 5) {
cleanupDestSlot = 1;
goto __cleanup1;
}
if (i == 9) {
cleanupDestSlot = 2;
goto __cleanup1;
}

// ...

cleanupDestSlot = 0;
__cleanup1:
ClassWithDtor::__ctor_complete(&var3);
switch (cleanupDestSlot) {
case 2: goto __cleanup3;
}
}

// ...

cleanupDestSlot = 0;
__cleanup3:
ClassWithDtor::__ctor_complete(&var2);
switch (cleanupDestSlot) {
case 2: goto __cleanup2;
}
}

// ...

__cleanup2:
ClassWithDtor::__ctor_complete(&var1);
}

</pre>
|}

This cleanup mechanism ensures that even in complex control flow scenarios, all required cleanup operations are executed, maintaining the integrity and safety of the program.
[[Category:Demystifying C++|Cleanup_Code]]

Demystifying C++ - Cleanup Code

2024-02-28T07:41:51Z

Tobias.columbus: explicitly mention raii idiom and safety in beginning paragraph

The '''RAII (Resource Acquisition Is Initialization)''' idiom is pivotal in modern C++. It ensures that resources are properly released and destructors are correctly called as variables and objects go out of their scope. In C++, leveraging the RAII idiom means the cleanup code is automatically generated and inserted as needed, especially in scenarios with complex control structures like loops and branches. This idiom guarantees that in the event of premature exits from a block due to statements like <code>return</code>, <code>break</code>, <code>continue</code>, or via jumps with <code>goto</code>, the cleanup code for the respective blocks will be executed correctly, ensuring resource and exception safety.

Interestingly, the clang C++ frontend doesn't directly insert this cleanup code right before such statements. Instead, the cleanup code is generated only at one location and jumped to directly. A state variable and a switch block at the end of the cleanup code ensure that the control flow continues at the original location.

At first glance, this approach might seem inefficient as it adds additional code for the state variable and <code>switch</code> blocks. However, from optimization level -O1 onwards, in later compiler phases, this overhead gets eliminated by compiler optimizations like Jump Threading [https://beza1e1.tuxen.de/articles/jump_threading.html]. In this process, the cleanup code gets duplicated, and the state variable and the <code>switch</code> blocks can be removed, making the generated code more efficient and straightforward.

In the C implementation, as shown in the example, the state variable like <code>cleanupDestSlot</code> is used to determine the jump destination after executing the cleanup code. The <code>goto</code> mechanism is then used to jump to the relevant cleanup code and then onward to the final destination, based on the value of the state variable.

{| class="wikitable"
|-
!Cleanup Code
|<pre>
void func() {

ClassWithDtor var1;

for (int i = 0; i < 10; ++i) {
ClassWithDtor var2;

for (int j = 0; j < 10; ++j) {
ClassWithDtor var3;

if (i == 5) {

continue;
}
if (i == 9) {

return;
}

// ...

}

// ...

}

// ...

}

</pre>
|<pre>
void func(void) {
unsigned int cleanupDestSlot;
struct ClassWithDtor var1;

for (int i = 0; i < 10; ++i) {
struct ClassWithDtor var2;

for (int j = 0; j < 10; ++j) {
struct ClassWithDtor var3;

if (i == 5) {
cleanupDestSlot = 1;
goto __cleanup1;
}
if (i == 9) {
cleanupDestSlot = 2;
goto __cleanup1;
}

// ...

cleanupDestSlot = 0;
__cleanup1:
ClassWithDtor::__ctor_complete(&var3);
switch (cleanupDestSlot) {
case 2: goto __cleanup3;
}
}

// ...

cleanupDestSlot = 0;
__cleanup3:
ClassWithDtor::__ctor_complete(&var2);
switch (cleanupDestSlot) {
case 2: goto __cleanup2;
}
}

// ...

__cleanup2:
ClassWithDtor::__ctor_complete(&var1);
}

</pre>
|}

This cleanup mechanism ensures that even in complex control flow scenarios, all required cleanup operations are executed, maintaining the integrity and safety of the program.
[[Category:Demystifying C++|Cleanup_Code]]

Demystifying C++ - Initialization of Global Variables

2024-02-28T07:37:21Z

Tobias.columbus: seo

{{#seo:
|title=Global Variable Initialization in C vs. C++
|description=Uncover the differences in global variable initialization between C and C++ and how this is managed through special functions and attributes.
|keywords=global variable initialization, transpiling, C programming, C++ programming, runtime expressions, constructors, destructors, __attribute__((constructor)), __cxa_atexit, software development, programming languages
|robots=index, follow
}}

In C, the initialization of global variables is restricted to constant expressions. This means that all global variables must be initialized at compile time, and runtime calculations or functions cannot be used. In contrast, C++ allows for more flexible initialization. When global objects or variables in C++ are created that require non-constant initialization or have a constructor, the compiler generates a special initialization function (often referred to as "global constructor"). This function is automatically called at the start of the program, even before the main() function is invoked. The clang or gcc compiler allows the specification of global constructors using the function attribute <code>__attribute__((constructor)).</code>

Furthermore, the C++ compiler generates a special destructor function in the case of global objects with a destructor. This function is registered during the initialization of the global object using the "Itanium ABI" function <code>__cxa_atexit</code> and is automatically called when the program ends normally (e.g., when return is called in the main() function or when exit() is invoked). Additionally, a DSO handle is passed to the function. DSO stands for Dynamic Shared Object, and it allows, for example, separate execution of all destructor functions for shared object (.so) files.

{| class="wikitable"
|-
!Initialization of Global Variable
|<pre>
double sqrt2 = sqrt(2.0);
</pre>
|<pre>
__attribute__((constructor)) static void __cxx_global_var_init_sqrt2(void) {
sqrt2 = sqrt(2.0);
}
</pre>
|-
!Global Variable with Constructor/Destructor
|<pre>
C1 obj;
</pre>
|<pre>
extern char __dso_handle;

__attribute__((constructor)) static void __cxx_global_var_init_obj(void) {
C1_ctor_complete(&obj);
__cxa_atexit(&C1_dtor_complete, &obj, &__dso_handle);
}
</pre>
|}
[[Category:Demystifying C++|Initialization_of_Global_Variables]]

Demystifying C++ - Virtual Classes (Polymorphism)

2024-02-28T07:33:54Z

Tobias.columbus:

{{#seo:
|title=Transpiling Polymorphism in C++ to C
|description=Delve into the concept of polymorphism in C++ and learn how virtual methods can be emulated in C.
|keywords=polymorphism, transpiling, object-oriented programming, C++, C programming, virtual methods, function pointers, software development, programming languages
|robots=index, follow
}}

Polymorphism, a core concept of object-oriented programming (OOP), allows different objects to be treated uniformly, typically through a common interface. C++ natively supports polymorphism through its class syntax, especially with the use of virtual methods.

C does not support native polymorphism, as it lacks classes or virtual methods. However, polymorphism in C can be emulated using structures, function pointers, and manual initialization of virtual tables, much like a C++ compiler would implement in assembler. The following examples show a simplified C code by changing global variable names and omitting elements from the virtual function table relevant to multiple inheritances.

To implement polymorphism in C, a __vptr is first inserted into the base class. This points to a table of function pointers. Depending on which class is derived from Base and which virtual methods are overridden, this pointer points to different tables. The derived class does not need its own __vptr, as it reuses the __vptr of the base class.

{| class="wikitable"
|-
!Virtual Classes
|<pre>
class Base {
public:
virtual void func1() {}
virtual void func2() {}
};

class Derived : public Base {
public:
void func1() override {}
virtual void func3() {}
};
</pre>
|<pre>
struct Base_vftable1 {
void (*func1)(struct Base *);
void (*func2)(struct Base *);
};

struct Derived_vftable1 {
struct Base_vftable1 base1;
void (*func3)(struct Derived *);
};

struct Base {
const struct Base_vftable1 *__vptr;
};

struct Derived {
struct Base __base1;
};
</pre>
|}

If a virtual class does not have a constructor, an implicit constructor is created. The constructor first calls the constructors of the base classes and then sets the __vptr. In this example, Derived_ctor_complete first calls Base_ctor_base. In both functions, the __vptr is sequentially set to different values. Although this may initially seem inefficient and unintuitive, it has a crucial rationale. Thus, code in the Base constructor can call virtual methods without them having already been modified. In practice, this is often unnecessary, and the first __vptr initialization can be optimized away in subsequent compiler phases, resulting in no disadvantages.

{| class="wikitable"
!Constructor
|Implicit
|<pre>
const struct Base_vftable1 Base_vtable = {&Base_func1, &Base_func2};
const struct Derived_vftable1 Derived_vtable = {{&Derived_func1, &Base_func2}, &Derived_func3};

inline void Base_ctor_base(struct Base *this) {
this->__vptr = &Base_vtable;
}

inline void Derived_ctor_complete(struct Derived *this) {
Base_ctor_base((struct Base*)this);
this->__base1.__vptr = &Derived_vtable;
}
</pre>
|}

The call of a virtual method is relatively simple. The respective function pointer in __vptr is used and an indirect function call is executed.

{| class="wikitable"
!Virtual Method Call
|<pre>
void call_virtual_method(Base* base) {
base->func1();
}
</pre>
|<pre>
void call_virtual_method(struct Base *base) {
(*base->__vptr->func1)(base);
}
</pre>
|}

Indirect function calls are not only computationally intensive in the processor but also prevent compiler optimizations like inlining. Therefore, the compiler tries to resolve these in advance whenever possible. This technique is called devirtualization. In C++11, the 'final' keyword was introduced, which can be used for both virtual methods and classes. This keyword is not only a security feature, similar to 'public', 'private', and 'protected', but it also supports the compiler in devirtualization by clarifying that a method or class cannot be changed by a derived class.

{| class="wikitable"
!Devirtualized Method Call
|<pre>
void call_devirtualized_method() {
Derived d;

d.func1();
}
</pre>
|<pre>
void call_devirtualized_method() {
Derived d;

Derived_ctor_complete(&d);
Derived_func1(&d);
}
</pre>
|}

Dynamic casting from base classes to a derived class is enabled in C++ by the dynamic_cast operator. In the background, the compiler uses the helper function __dynamic_cast, which is implemented in libcxx. This receives type information (RTTI) of the two classes, which contain the entire class hierarchy. Within the class hierarchy of the derived class, the base class is then searched for, and if a match is found, the pointer is adjusted by an offset. The RTTI information is represented in the example via global variables typeinfo_*, without going into their content. Interested readers can view the implementation of the __dynamic_cast function from the LLVM libcxx at [https://github.com/llvm/llvm-project/blob/release/16.x/libcxxabi/src/private_typeinfo.cpp#L622].

{| class="wikitable"
!Dynamic Cast
|<pre>
Derived& dynamic_cast_ref(Base& base) {
return dynamic_cast<Derived&>(base);
}
</pre>
|<pre>
struct Derived* dynamic_cast_ref(struct Base* base) {
struct Derived* tmpPtr1 = __dynamic_cast(base, &typeinfo_Base, &typeinfo_Derived, 0);
if (!tmpPtr1) {
cxa_bad_cast();
}
return tmpPtr1;
}
</pre>
|}
[[Category:Demystifying C++|Virtual_Classes_(Polymorphism)]]

Demystifying C++ - New and Delete Operators

2024-02-28T07:31:41Z

Tobias.columbus: seo

{{#seo:
|title=Dynamic Memory Management in C++ vs. C: Understanding new and delete
|description=Explore the mechanisms of dynamic memory management in C++ with `new` and `delete`, and learn how similar functionality is achieved in C.
|keywords=dynamic memory management, transpiling, C++, C programming, new operator, delete operator, constructors, destructors, software development, programming languages
|robots=index, follow
}}

In C++, the <code>new</code> operator is used to dynamically allocate memory and call the object's constructor, while the <code>delete</code> operator is used to call the destructor and subsequently free the memory. These operators significantly simplify memory management in C++ and reduce the likelihood of errors that often occur with manual memory management.

In the equivalent C code, memory is allocated or released via the global <code>operator new</code> and <code>operator delete</code> functions. The implementation of both functions is found in libc++ and uses malloc and free respectively.

{| class="wikitable"
!new
|<pre>
C1* obj = new C1();
</pre>
|<pre>
struct C1* obj = (struct C1*)::operator new(sizeof(C1));
if (obj) {
C1_ctor_complete(obj);
}
</pre>
|-
!delete
|<pre>
delete obj;
</pre>
|<pre>
if (obj) {
C1_dtor_complete(obj);
::operator delete(obj);
}
</pre>
|}
The code generated by new/delete can become quite complex, for instance, when allocating or deallocating an array. In such cases, sometimes intricate loops for constructor and destructor handling are created.
[[Category:Demystifying C++|New_and_Delete_Operators]]

Demystifying C++ - Virtual Classes (Polymorphism)

2024-02-28T07:26:59Z

Tobias.columbus: seo block

{{#seo:
|title=Transpiling Polymorphism in C++ to C
|description=Delve into the concept of polymorphism in C++ and learn how virtual methods can be emulated in C.
|keywords=polymorphism, object-oriented programming, C++, C programming, virtual methods, function pointers, software development, programming languages
|robots=index, follow
}}

Polymorphism, a core concept of object-oriented programming (OOP), allows different objects to be treated uniformly, typically through a common interface. C++ natively supports polymorphism through its class syntax, especially with the use of virtual methods.

C does not support native polymorphism, as it lacks classes or virtual methods. However, polymorphism in C can be emulated using structures, function pointers, and manual initialization of virtual tables, much like a C++ compiler would implement in assembler. The following examples show a simplified C code by changing global variable names and omitting elements from the virtual function table relevant to multiple inheritances.

To implement polymorphism in C, a __vptr is first inserted into the base class. This points to a table of function pointers. Depending on which class is derived from Base and which virtual methods are overridden, this pointer points to different tables. The derived class does not need its own __vptr, as it reuses the __vptr of the base class.

{| class="wikitable"
|-
!Virtual Classes
|<pre>
class Base {
public:
virtual void func1() {}
virtual void func2() {}
};

class Derived : public Base {
public:
void func1() override {}
virtual void func3() {}
};
</pre>
|<pre>
struct Base_vftable1 {
void (*func1)(struct Base *);
void (*func2)(struct Base *);
};

struct Derived_vftable1 {
struct Base_vftable1 base1;
void (*func3)(struct Derived *);
};

struct Base {
const struct Base_vftable1 *__vptr;
};

struct Derived {
struct Base __base1;
};
</pre>
|}

If a virtual class does not have a constructor, an implicit constructor is created. The constructor first calls the constructors of the base classes and then sets the __vptr. In this example, Derived_ctor_complete first calls Base_ctor_base. In both functions, the __vptr is sequentially set to different values. Although this may initially seem inefficient and unintuitive, it has a crucial rationale. Thus, code in the Base constructor can call virtual methods without them having already been modified. In practice, this is often unnecessary, and the first __vptr initialization can be optimized away in subsequent compiler phases, resulting in no disadvantages.

{| class="wikitable"
!Constructor
|Implicit
|<pre>
const struct Base_vftable1 Base_vtable = {&Base_func1, &Base_func2};
const struct Derived_vftable1 Derived_vtable = {{&Derived_func1, &Base_func2}, &Derived_func3};

inline void Base_ctor_base(struct Base *this) {
this->__vptr = &Base_vtable;
}

inline void Derived_ctor_complete(struct Derived *this) {
Base_ctor_base((struct Base*)this);
this->__base1.__vptr = &Derived_vtable;
}
</pre>
|}

The call of a virtual method is relatively simple. The respective function pointer in __vptr is used and an indirect function call is executed.

{| class="wikitable"
!Virtual Method Call
|<pre>
void call_virtual_method(Base* base) {
base->func1();
}
</pre>
|<pre>
void call_virtual_method(struct Base *base) {
(*base->__vptr->func1)(base);
}
</pre>
|}

Indirect function calls are not only computationally intensive in the processor but also prevent compiler optimizations like inlining. Therefore, the compiler tries to resolve these in advance whenever possible. This technique is called devirtualization. In C++11, the 'final' keyword was introduced, which can be used for both virtual methods and classes. This keyword is not only a security feature, similar to 'public', 'private', and 'protected', but it also supports the compiler in devirtualization by clarifying that a method or class cannot be changed by a derived class.

{| class="wikitable"
!Devirtualized Method Call
|<pre>
void call_devirtualized_method() {
Derived d;

d.func1();
}
</pre>
|<pre>
void call_devirtualized_method() {
Derived d;

Derived_ctor_complete(&d);
Derived_func1(&d);
}
</pre>
|}

Dynamic casting from base classes to a derived class is enabled in C++ by the dynamic_cast operator. In the background, the compiler uses the helper function __dynamic_cast, which is implemented in libcxx. This receives type information (RTTI) of the two classes, which contain the entire class hierarchy. Within the class hierarchy of the derived class, the base class is then searched for, and if a match is found, the pointer is adjusted by an offset. The RTTI information is represented in the example via global variables typeinfo_*, without going into their content. Interested readers can view the implementation of the __dynamic_cast function from the LLVM libcxx at [https://github.com/llvm/llvm-project/blob/release/16.x/libcxxabi/src/private_typeinfo.cpp#L622].

{| class="wikitable"
!Dynamic Cast
|<pre>
Derived& dynamic_cast_ref(Base& base) {
return dynamic_cast<Derived&>(base);
}
</pre>
|<pre>
struct Derived* dynamic_cast_ref(struct Base* base) {
struct Derived* tmpPtr1 = __dynamic_cast(base, &typeinfo_Base, &typeinfo_Derived, 0);
if (!tmpPtr1) {
cxa_bad_cast();
}
return tmpPtr1;
}
</pre>
|}
[[Category:Demystifying C++|Virtual_Classes_(Polymorphism)]]

Demystifying C++ - Classes

2024-02-28T07:24:21Z

Tobias.columbus: shortened seo blocks

{{#seo:
|title=Translating C++ to C: Methods, Inheritance, Constructors, and Destructors
|description=This guide explores the translation of C++ classes, including methods, inheritance, constructors, and destructors, into C, with a focus on understanding of object-oriented concepts in C.
|keywords=C++, C programming, transpiling, object-oriented programming, procedural programming, classes in C, C++ inheritance, C++ constructors, C++ destructors, software development, programming languages
|robots=index, follow
}}

<languages/>
<translate>

Classes are a cornerstone of C++ programming, embodying the object-oriented paradigm, which is essential for structuring modern, complex software applications. In C++, classes encapsulate data and behavior through attributes and methods. In contrast, Assembler and C primarily rely on data structures and functions.

===Methods=== 
Just as the C++ compiler does, the transpiler translates classes into C structures and functions. The methods of the class are turned into functions that take a "this" pointer to the structure representing the class. When accessing attributes, the this-pointer is used automatically, and when calling other methods, it is simply passed on.
</translate>
{| class="wikitable"
!<translate> Methods</translate>
|<pre>
class C1 {
int attr;
public:
void onChangeAttr();

void setAttr(int v) {
attr = v;
onChangeAttr();
}
};
</pre>
|<pre>
struct C1 {
int attr;
};

void C1_onChangeAttr(struct C1* this);

void C1_setAttr(struct C1* this, int v) {
this->attr = v;
C1_onChangeAttr(this);
}
</pre>
|}

<translate>
===Inheritance=== 


In C++, inheritance is a central principle that allows classes to inherit attributes and methods from base classes. However, C does not naturally support inheritance. Therefore, the C++ to C transpiler uses special techniques to simulate inheritance relationships by embedding each base class as its own field in the derived structure.


A crucial aspect of inheritance is the casting between base classes (Base) and derived classes (Derived):


*'''Derived-to-Base Casts''': In assembler, such a cast corresponds to an addition with a constant value. These are relatively simple to implement in C by accessing the respective field in the derived structure. This happens implicitly in C++ in many places, such as when calling base class methods or accessing attributes.
*'''Static Base-to-Derived Casts''': In assembler, such a cast corresponds to a subtraction with a constant value. This is more complex in C and requires some C casting.
*'''Dynamic Base-to-Derived Casts''': These are produced with the <code>dynamic_cast</code> keyword and are more complex in implementation since they require type checking at runtime. Dynamic casts will be discussed in the chapter on virtual classes.
</translate>


{| class="wikitable"
!<translate> Representation of Base Classes</translate>
|<pre>
class Derived : public Base1, public Base2 {
...
};
</pre>
|<pre>
struct Derived {
struct Base1 base1;
struct Base2 base2;

...
};
</pre>
|-
!<translate> Derived-to-Base Cast</translate>
|<pre>
static_cast<Base2*>(derived)
</pre>
|<pre>
&derived->base2
</pre>
|-
!<translate> Static Base-To-Derived Cast</translate>
|<pre>
static_cast<Derived*>(base2)
</pre>
|<pre>
(Derived*)((char*)base2 - offsetof(Derived, base2))
</pre>
|}

<translate>
===Constructors and Destructors=== 
Constructors and destructors play a pivotal role in C++ programming as they manage automatic initialization and cleanup processes for objects. Constructors are special class methods that are automatically invoked when an object is created. They're often used to define initial values for object attributes and perform other initialization tasks. Destructors are the opposite of constructors; they're invoked when an object is destroyed and are ideal for cleanup tasks like releasing memory and other resources.


In C, there's no direct counterpart for constructors and destructors. Instead, they are replaced by regular functions that are called upon object creation or destruction. For completeness, it should be mentioned that for the Itanium ABI, at least two constructor functions (<code>ctor_complete</code>, <code>ctor_base</code>) and destructor functions (<code>dtor_complete</code>, <code>dtor_base</code>, <code>dtor_delete</code>) are generated. The complete variants are typically used, base variants are required for base classes in the constructor/destructor, and <code>dtor_delete</code> is used when applying delete to a class with a virtual destructor.
</translate>


{| class="wikitable"
|-
!<translate> Constructors and Destructors</translate>
|<pre>
class C1 {
int a = 10;
public:
C1() {
// Initialization code
}

~C1() {
// Cleanup code
}
};
</pre>
|<pre>
struct C1 {
int a;
};

void C1_ctor_complete(struct C1* this) {
this->a = 10;
// Initialization code
}

void C1_dtor_complete(struct C1* this) {
// Cleanup code
}
</pre>
|-
!<translate> Constructors and Destructors of Base Classes</translate>
|<pre>
class C1 : public Base1 {
int a = 10;
public:

C1() {
// Initialization code
}

~C1() {
// Cleanup code
}
};

</pre>
|<pre>
struct C1 {
Base1 base1;
int a;
};

void C1_ctor_complete(struct C1* this) {
Base1_ctor_base(&this->base1);
a = 10;
// Initialization code
}

void C1_dtor_complete(struct C1* this) {
// Cleanup code
Base1_dtor_base(&this->base1);
}
</pre>
|-
!<translate> Stack Variables</translate>
|<pre>
{
C1 obj;

...
}
</pre>
|<pre>
{
struct C1 obj;
C1_ctor_complete(&obj);

...

C1_dtor_complete(&obj);
}
</pre>
|}

[[Category:Demystifying C++|Classes]]

Demystifying C++ - Classes

2024-02-28T07:21:51Z

Tobias.columbus: seo block

{{#seo:
|title=Translating C++ Classes to C: Methods, Inheritance, Constructors, and Destructors
|description=This guide explores the translation of C++ classes, including methods, inheritance, constructors, and destructors, into C, highlighting the practical application and understanding of object-oriented concepts in procedural programming.
|keywords=C++, C programming, transpiling, object-oriented programming, procedural programming, classes in C, C++ inheritance, C++ constructors, C++ destructors, software development, programming languages
|robots=index, follow
}}

<languages/>
<translate>

Classes are a cornerstone of C++ programming, embodying the object-oriented paradigm, which is essential for structuring modern, complex software applications. In C++, classes encapsulate data and behavior through attributes and methods. In contrast, Assembler and C primarily rely on data structures and functions.

===Methods=== 
Just as the C++ compiler does, the transpiler translates classes into C structures and functions. The methods of the class are turned into functions that take a "this" pointer to the structure representing the class. When accessing attributes, the this-pointer is used automatically, and when calling other methods, it is simply passed on.
</translate>
{| class="wikitable"
!<translate> Methods</translate>
|<pre>
class C1 {
int attr;
public:
void onChangeAttr();

void setAttr(int v) {
attr = v;
onChangeAttr();
}
};
</pre>
|<pre>
struct C1 {
int attr;
};

void C1_onChangeAttr(struct C1* this);

void C1_setAttr(struct C1* this, int v) {
this->attr = v;
C1_onChangeAttr(this);
}
</pre>
|}

<translate>
===Inheritance=== 


In C++, inheritance is a central principle that allows classes to inherit attributes and methods from base classes. However, C does not naturally support inheritance. Therefore, the C++ to C transpiler uses special techniques to simulate inheritance relationships by embedding each base class as its own field in the derived structure.


A crucial aspect of inheritance is the casting between base classes (Base) and derived classes (Derived):


*'''Derived-to-Base Casts''': In assembler, such a cast corresponds to an addition with a constant value. These are relatively simple to implement in C by accessing the respective field in the derived structure. This happens implicitly in C++ in many places, such as when calling base class methods or accessing attributes.
*'''Static Base-to-Derived Casts''': In assembler, such a cast corresponds to a subtraction with a constant value. This is more complex in C and requires some C casting.
*'''Dynamic Base-to-Derived Casts''': These are produced with the <code>dynamic_cast</code> keyword and are more complex in implementation since they require type checking at runtime. Dynamic casts will be discussed in the chapter on virtual classes.
</translate>


{| class="wikitable"
!<translate> Representation of Base Classes</translate>
|<pre>
class Derived : public Base1, public Base2 {
...
};
</pre>
|<pre>
struct Derived {
struct Base1 base1;
struct Base2 base2;

...
};
</pre>
|-
!<translate> Derived-to-Base Cast</translate>
|<pre>
static_cast<Base2*>(derived)
</pre>
|<pre>
&derived->base2
</pre>
|-
!<translate> Static Base-To-Derived Cast</translate>
|<pre>
static_cast<Derived*>(base2)
</pre>
|<pre>
(Derived*)((char*)base2 - offsetof(Derived, base2))
</pre>
|}

<translate>
===Constructors and Destructors=== 
Constructors and destructors play a pivotal role in C++ programming as they manage automatic initialization and cleanup processes for objects. Constructors are special class methods that are automatically invoked when an object is created. They're often used to define initial values for object attributes and perform other initialization tasks. Destructors are the opposite of constructors; they're invoked when an object is destroyed and are ideal for cleanup tasks like releasing memory and other resources.


In C, there's no direct counterpart for constructors and destructors. Instead, they are replaced by regular functions that are called upon object creation or destruction. For completeness, it should be mentioned that for the Itanium ABI, at least two constructor functions (<code>ctor_complete</code>, <code>ctor_base</code>) and destructor functions (<code>dtor_complete</code>, <code>dtor_base</code>, <code>dtor_delete</code>) are generated. The complete variants are typically used, base variants are required for base classes in the constructor/destructor, and <code>dtor_delete</code> is used when applying delete to a class with a virtual destructor.
</translate>


{| class="wikitable"
|-
!<translate> Constructors and Destructors</translate>
|<pre>
class C1 {
int a = 10;
public:
C1() {
// Initialization code
}

~C1() {
// Cleanup code
}
};
</pre>
|<pre>
struct C1 {
int a;
};

void C1_ctor_complete(struct C1* this) {
this->a = 10;
// Initialization code
}

void C1_dtor_complete(struct C1* this) {
// Cleanup code
}
</pre>
|-
!<translate> Constructors and Destructors of Base Classes</translate>
|<pre>
class C1 : public Base1 {
int a = 10;
public:

C1() {
// Initialization code
}

~C1() {
// Cleanup code
}
};

</pre>
|<pre>
struct C1 {
Base1 base1;
int a;
};

void C1_ctor_complete(struct C1* this) {
Base1_ctor_base(&this->base1);
a = 10;
// Initialization code
}

void C1_dtor_complete(struct C1* this) {
// Cleanup code
Base1_dtor_base(&this->base1);
}
</pre>
|-
!<translate> Stack Variables</translate>
|<pre>
{
C1 obj;

...
}
</pre>
|<pre>
{
struct C1 obj;
C1_ctor_complete(&obj);

...

C1_dtor_complete(&obj);
}
</pre>
|}

[[Category:Demystifying C++|Classes]]

Demystifying C++ - Name Mangling

2024-02-27T15:06:29Z

Tobias.columbus:

<seo title="Demystifying Name Mangling in C++"
description="Explore Name Mangling in C++, a crucial trick for function overloading, namespaces, and templates, enabling core functionalities unique to C++."
keywords="C++ Name Mangling, function overloading, namespaces, C++ templates"
robots="index, follow"
og:title="Understanding Name Mangling in C++"
og:type="article"
og:description="Explore Name Mangling in C++, a crucial trick for function overloading, namespaces, and templates, enabling core functionalities unique to C++."
/>

One of the key features of C++ is "Name Mangling" [https://en.wikipedia.org/wiki/Name_mangling]. Although it may seem like a peripheral detail at first glance, it is a fundamental element that enables several core functionalities of C++. Name Mangling is the process by which the C++ compiler modifies the names of variables, functions, and other entities to ensure uniqueness and specific information about these entities. This concept becomes particularly important when considering function overloading, namespaces, class hierarchies, and templates - features not natively present in C.

The process of Name Mangling ensures that each element is uniquely identifiable, even if it appears identical in C++ source code syntax. This is crucial for the linker, which must allocate the correct functions and variables across different files and libraries. As a result, developers often encounter mangled names within object files. Tools like <code>c++filt</code> or websites can be used to demangle these names back into readable elements.

The C++ standard does not prescribe a specific method for Name Mangling. This means that the implementation of Name Mangling is left to the discretion of the compiler manufacturer, leading to differences in Mangling conventions between different compilers. The Itanium C++ ABI, for instance, establishes Name Mangling conventions and is commonly used on Unix-based systems.

The keyword <code>extern "C"</code> can be used to disable Name Mangling for functions in C++. This facilitates interoperability between C++ and C, among other things.

Examples of Name Mangling:
{| class="wikitable"
!Feature
!C++ Code
!C Code
|-
!Overloading
|<pre>
void func1(char, short, int, long)
void func2(int, int&, int&&, int*);
</pre>
|<pre>
void _Z5func1csil(char, short, int, long);
void _Z5func2iRiOiPi(int, int *, int *, int *);
</pre>
|-
!Namespace
|<pre>
namespace ns1 {
void func1();
}
</pre>
|<pre>
void _ZN3ns15func1Ev(void);
</pre>
|-
!Class
|<pre>
class c1 {
static void func1();
};
</pre>
|<pre>
static void _ZN2c15func1Ev(void);
</pre>
|-
!Special Functions
|<pre>
void* operator new(size_t s);
void operator delete(void*);
bool operator < (c1, c1);
</pre>
|<pre>
void * _Znwm(size_t s);
void _ZdlPv(void *ptr);
bool _Zlt2c1S_(struct c1, struct c1);
</pre>
|-
!External Statements
|<pre>
extern "C" void func1();
void func2();
</pre>
|<pre>
void func1(void);
void _Z5func2v(void);
</pre>
|-
!Template Functions
|<pre>
template<typename T>
void func() { /* ... */ }

template void func<int>();
template void func<float>();
</pre>
|<pre>
void _Z4funcIiEvv(void);
void _Z4funcIfEvv(void);
</pre>
|}

For simplicity, the C++ names of the functions will be used throughout the following paper, even if it results in technically incorrect C code.

[[Category:Demystifying C++|Demystifying_C++]]

Loop Transformations

2024-02-27T11:05:32Z

Tobias.columbus:

<seo title="Loop Transformations"
description="A comprehensive overview of loop transformations with examples."
keywords="loop transformation, parallelization, locality"
robots="index, follow"
og:title="Loop Transformations"
og:type="website"
og:description="A comprehensive overview of loop transformations with examples."
/>
'''Loop transformation''' is a pivotal technique in optimizing the performance of computer programs, particularly those that heavily rely on loop structures. It plays a crucial role in enhancing the efficiency, speed, and parallelization of software applications, allowing developers to maximize hardware utilization and minimize execution time.

=== Definition of Loop Transformation ===
Loop transformation, in the realm of computer science, refers to the process of modifying the structure, order, or execution of loops in a program, with the objective of optimizing performance. This can involve alterations to the loop's iteration space, data access patterns, or overall structure, to achieve improvements in runtime, energy consumption, or other performance metrics.

=== Importance of Loop Transformation ===
The significance of loop transformation extends across various domains, including high-performance computing, embedded systems, and scientific computing. By optimizing loop structures, developers can ensure that applications run more efficiently, exploiting the capabilities of modern hardware architectures and parallel processing units. This is particularly crucial in domains where computational resources are a limiting factor, and optimal performance is paramount.

=== Objective of the Article ===
This article aims to provide a comprehensive overview of loop transformation, exploring its principles, techniques, applications, and impact on the field of computing. It will delve into the various types of loop transformations, their implementation through compilers and manual techniques, and their application in real-world scenarios. The article will also discuss the challenges and future trends in loop transformation, offering insights into the evolving landscape of this essential optimization technique.

== Background and Basics ==

Before delving into the intricacies of loop transformation, it is essential to understand the foundational concepts of loops and why transforming them is necessary.

=== Understanding Loops ===

==== Definition and Structure ====
A '''loop''' in computer programming is a control flow statement that allows code to be executed repeatedly based on a given Boolean condition. The loop can be thought of as a repeating if statement. The basic types of loops include for loops, while loops, and do-while loops, each with its unique structure and use case.

==== Types of Loops ====
* '''For Loop:''' Typically used when the number of iterations is known beforehand.
* '''While Loop:''' Used when the number of iterations is unknown, and continuation is based on a condition.
* '''Do-While Loop:''' Similar to the while loop but guarantees at least one execution of the loop body.

=== The Need for Transformation ===

==== Performance Optimization ====
Loop transformations are crucial for optimizing the performance of programs. By restructuring loops, developers can minimize the number of instructions executed, reduce cache misses, and improve the overall efficiency of the program.

==== Parallelization ====
In the era of multi-core processors, loop transformation is vital for exploiting parallelism in code. It enables the concurrent execution of loop iterations, reducing the overall execution time and making optimal use of available processing units.

==== Energy Efficiency ====
Optimized loops consume less energy, a critical consideration in battery-powered devices and large-scale computing environments. Through loop transformation, developers can achieve more energy-efficient code, prolonging battery life and reducing operational costs.

In the subsequent sections, we will explore the principles, types, and techniques of loop transformation, shedding light on its applications, challenges, and future trends in the field of computing.

== Principles of Loop Transformation ==

Loop transformation is governed by a set of principles aimed at optimizing various aspects of program execution. Understanding these principles is crucial for implementing effective loop transformations.

=== Data Locality Enhancement ===
Improving '''data locality''' is one of the primary goals of loop transformation. By optimizing the way data is accessed and utilized within loops, developers can reduce cache misses and improve cache utilization, leading to enhanced performance.

=== Loop Nesting and Reordering ===
'''Loop nesting''' and '''reordering''' involve changing the order of nested loops and the sequence of statements within loops. These transformations can optimize the execution order of loop bodies, minimizing overhead and improving data access patterns.

=== Reduction in Control Overhead ===
Minimizing the control overhead associated with loop structures is another essential principle of loop transformation. By reducing the number of branch instructions and loop control operations, developers can achieve more streamlined and efficient loop execution.

In the following sections, we will delve deeper into the various types of loop transformations and explore how these principles are applied to optimize loop structures in different computing environments.
== Loop Transformation Types ==

{| class="wikitable"
! Transformation Type !! Example Before Transformation !! Example After Transformation
|-
| '''Loop Fusion''' Combines two or more adjacent loops that have the same iteration space, reducing the overhead of loop control and improving data locality.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * i;
for (int i = 0; i < n; i++)
b[i] = a[i] + i;
</pre>
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++) {
a[i] = i * i;
b[i] = a[i] + i;
}
</pre>
|-
| '''Loop Fission or Distribution''' Divides a loop with multiple statements into several smaller loops, each handling a subset of the statements, which can improve parallelism and cache utilization.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++) {
a[i] = i * i;
b[i] = a[i] + i;
}
</pre>
| <pre style="white-space: pre;">
for(int i = 0; i < n; i++)
a[i] = i * i;
for(int i = 0; i < n; i++)
b[i] = a[i] + i;
</pre>
|-
| '''Loop Interchange''' Swaps the order of nested loops, which can optimize data locality and access patterns.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
for (int j = 0; j < m; j++)
a[i][j] = i + j;
</pre>
| <pre style="white-space: pre;">
for (int j = 0; j < m; j++)
for (int i = 0; i < n; i++)
a[i][j] = i + j;
</pre>
|-
| '''Loop Skewing''' Changes the iteration space of nested loops to optimize data access patterns, particularly useful for optimizing stencil computations.
| <pre style="white-space: pre;">
for (int i = 1; i < n; i++)
for (int j = 1; j < m; j++)
a[i][j] = a[i-1][j] + a[i][j-1];
</pre>
| <pre style="white-space: pre;">
for (int k = 2; k < m + n; k++) {
for (int j = max(1, k - n + 1); j < min(k, m); j++) {
int i = k - j;
a[i][j] = a[i-1][j] + a[i][j-1];
}
}
</pre>
|-
| '''Loop Tiling''' Breaks the iteration space of a loop into smaller chunks or tiles, improving cache locality and enabling parallel execution of tiles.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
for (int j = 0; j < m; j++)
a[i][j] = i + j;
</pre>
| <pre style="white-space: pre;">
int tileSize = 10;
for (int ii = 0; ii < n; ii += tileSize)
for (int jj = 0; jj < m; jj += tileSize)
for (int i = ii; i < min(ii + tileSize, n); i++)
for (int j = jj; j < min(jj + tileSize, m); j++)
a[i][j] = i + j;
</pre>
|-
| '''Loop Unrolling''' Increases the number of operations in the loop body and decreases the control overhead by executing multiple iterations in a single loop iteration.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * i;
</pre>
| <pre style="white-space: pre;">
int i;
for (i = 0; i + 3 < n; i+=4) {
a[i ] = i * i;
a[i + 1] = (i + 1) * (i + 1);
a[i + 2] = (i + 2) * (i + 2);
a[i + 3] = (i + 3) * (i + 3);
}
for ( ; i < n; i++)
a[i] = i * i;
</pre>
|-
| '''Loop Inversion''' Converts a while loop into a do-while loop inside an if statement, which can reduce the overhead of the loop control.
| <pre style="white-space: pre;">
while (condition) {
// Loop Body
}
</pre>
| <pre style="white-space: pre;">
if (condition) {
do {
// Loop Body
} while(condition);
}
</pre>
|-
| '''Loop Peeling''' Separates the first or last iteration(s) from the loop, which can help in resolving dependencies and optimizing specific iterations.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = b[i] + c[i];
</pre>
| <pre style="white-space: pre;">
if (n > 0) {
a[0] = b[0] + c[0];
for (int i = 1; i < n; i++)
a[i] = b[i] + c[i];
}
</pre>
|-
| '''Loop Fusion''' Combines two or more adjacent loops that have the same iteration space, reducing the overhead of loop control and improving data locality.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * i;
for (int i = 0; i < n; i++)
b[i] = a[i] + i;
</pre>
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++) {
a[i] = i * i;
b[i] = a[i] + i;
}
</pre>
|-
| '''Loop Reversal''' Reverses the order in which the loop iterates over its iteration space.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * i;
</pre>
| <pre style="white-space: pre;">
for (int i = n-1; i >= 0; i--)
a[i] = i * i;
</pre>
|-
| '''Loop Jamming''' Combines two or more loops that have the same iteration space but are not adjacent, potentially improving data locality.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * i;
// Some code in between
for (int i = 0; i < n; i++)
b[i] = a[i] + i;
</pre>
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++) {
a[i] = i * i;
b[i] = a[i] + i;
}
</pre>
|-
| '''Loop Shifting''' Alters the start and end of the loop iteration space, which can help in optimizing specific iterations.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * i;
</pre>
| <pre style="white-space: pre;">
for (int i = 1; i <= n; i++)
a[i-1] = (i-1) * (i-1);
</pre>
|-
| '''Loop Unswitching''' Moves a conditional statement outside of the loop, reducing the overhead of evaluating the condition in each iteration.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++) {
if (condition)
a[i] = i * i;
else
b[i] = i + i;
}
</pre>
| <pre style="white-space: pre;">
if (condition) {
for (int i = 0; i < n; i++)
a[i] = i * i;
} else {
for (int i = 0; i < n; i++)
b[i] = i + i;
}
</pre>
|-
| '''Loop Splitting''' Divides the loop into segments, allowing for different optimizations in each segment.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
// Some operations
</pre>
| <pre style="white-space: pre;">
for (int i = 0; i < k; i++)
// Some operations
for (int i = k; i < n; i++)
// Some operations
</pre>
|-
| '''Software Pipelining''' Reorders instructions to optimize the utilization of processing units and improve the overall execution time.
| <pre style="white-space: pre;">
// n is a big number
for (i = 0; i < n; i++) {
A(i);
B(i);
C(i);
}
</pre>
| <pre style="white-space: pre;">
A(0);
A(1); B(0);
for (i = 0; i < n - 2; i++) {
A(i+2);
B(i+1);
C(i);
}
B(i+1); C(i);
C(i+1);
</pre>
|-
| '''Induction Variable Substitution''' Replaces the loop induction variable with another variable, which can simplify the loop body and improve performance.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * i + i;
</pre>
| <pre style="white-space: pre;">
int j = 0;
for (int i = 0; i < n; i++, j+=i)
a[i] = j;
</pre>
|-
| '''Loop Rerolling''' Transforms a loop with a small body and a large number of iterations into a loop with a larger body and fewer iterations, potentially reducing the overhead of loop control operations.
| <pre style="white-space: pre;">
for (int i = 0; i < 4*n; i++)
a[i] = i * i;
</pre>
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++) {
a[4*i ] = (4*i ) * (4*i );
a[4*i + 1] = (4*i + 1) * (4*i + 1);
a[4*i + 2] = (4*i + 2) * (4*i + 2);
a[4*i + 3] = (4*i + 3) * (4*i + 3);
}
</pre>
|-
| '''Array Contraction''' Converts a temporary array used in a loop into a scalar variable, reducing memory usage.
| <pre style="white-space: pre;">
float temp[10];
for (int i = 0; i < 10; i++)
temp[i] = i * i;
float sum = 0;
for (int i = 0; i < 10; i++)
sum += temp[i];
</pre>
| <pre style="white-space: pre;">
float sum = 0;
for (int i = 0; i < 10; i++)
sum += i * i;
</pre>
|-
| '''Loop Coalescing''' Combines multiple loops with the same body but different iteration spaces into a single loop, reducing loop control overhead.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * i;
for (int i = n; i < 2*n; i++)
a[i] = i * i;
</pre>
| <pre style="white-space: pre;">
for (int i = 0; i < 2*n; i++)
a[i] = i * i;
</pre>
|-
| '''Loop Hoisting''' Moves invariant computations outside of the loop, reducing the computational overhead within the loop.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = log(2);
</pre>
| <pre style="white-space: pre;">
float temp = log(2);
for (int i = 0; i < n; i++)
a[i] = temp;
</pre>
|-
| '''Loop Strengthening Reduction''' Simplifies the computations within the loop, potentially improving performance.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = i * (i + 1);
</pre>
| <pre style="white-space: pre;">
int sum = 0;
for (int i = 0; i < n; i++) {
a[i] = sum;
sum += i + 1;
}
</pre>
|-
| '''Loop Normalization''' Transforms the loop variable and bounds to a canonical form, usually starting the loop variable from 0 and incrementing it by 1 in each iteration.
| <pre style="white-space: pre;">
for (int i = 1; i <= n; i++)
a[i] = i * i;
</pre>
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i+1] = (i+1) * (i+1);
</pre>
|-
| '''Loop Vectorization''' Converts scalar operations to vector operations, allowing multiple data points to be processed in a single instruction.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = b[i] + c[i];
</pre>
| Assuming vectorization support and appropriate data alignment:<pre style="white-space: pre;">
for (int i = 0; i < n; i+=4)
a[i:i+3] = b[i:i+3] + c[i:i+3];
</pre>
|-
| '''Loop Parallelization''' Modifies the loop to run its iterations in parallel, allowing for improved performance on multi-core systems.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
a[i] = b[i] + c[i];
</pre>
| <pre style="white-space: pre;">
#pragma omp parallel for
for (int i = 0; i < n; i++)
a[i] = b[i] + c[i];
</pre>
|-
| '''Loop Blocking''' Breaks the loop's iteration space into blocks, allowing for improved cache utilization.
| <pre style="white-space: pre;">
for (int i = 0; i < n; i++)
for (int j = 0; j < m; j++)
a[i][j] = b[i][j] + c[i][j];
</pre>
| <pre style="white-space: pre;">
int blockSize = 10;
for (int ii = 0; ii < n; ii += blockSize)
for (int jj = 0; jj < m; jj += blockSize)
for (int i = ii; i < min(ii + blockSize, n); i++)
for (int j = jj; j < min(jj + blockSize, m); j++)
a[i][j] = b[i][j] + c[i][j];
</pre>
|}

== Categories of Loop Transformations ==

Loop transformations are crucial optimization techniques used to enhance the performance of programs by modifying the structure of loops. The table below provides a comprehensive overview of various loop transformations and their impact on different aspects of program execution. Each transformation is evaluated based on its effect on Data Locality, Control Overhead, Parallelization, Computations, Memory Usage, and Code Size.

* '''Data Locality:''' Represents whether a transformation improves or decreases the efficiency of data access by optimizing the usage of cache memory.
* '''Control Overhead:''' Indicates whether a transformation increases or reduces the overhead associated with the control flow of loops, such as condition checks and branching.
* '''Parallelization:''' Denotes whether a transformation enables or improves the division of work among multiple processors to execute simultaneously.
* '''Computations:''' Specifies whether a transformation simplifies the computations inside the loop, reducing the computational load.
* '''Memory Usage:''' Represents whether a transformation optimizes or increases the memory footprint of the loop.
* '''Code Size:''' Indicates whether a transformation increases or reduces the amount of code.

In the table:
* '''Improved''' denotes that the transformation generally improves the respective category.
* '''Reduced''' denotes that the transformation generally reduces the respective category.
* '''Increased''' denotes that the transformation generally increases the respective category.
* '''Can Decrease''' denotes that the transformation can potentially decrease the respective category depending on the specific characteristics of the code and the hardware it runs on.
* '''Can Increase''' denotes that the transformation can potentially increase the respective category depending on the specific characteristics of the code and the hardware it runs on.
* An empty cell denotes that the transformation typically does not have a direct impact on the respective category.

{| class="wikitable"
!Transformation!!Data Locality!!Control Overhead!!Parallelization!!Computations!!Memory Usage!!Code Size
|-
|'''Loop Fusion'''||Improved||Reduced || || || ||Increased
|-
|'''Loop Fission or Distribution'''||Can Decrease||Increased||Improved|| || ||Increased
|-
|'''Loop Interchange'''|| Can Decrease|| || || || ||
|-
|'''Loop Skewing'''||Improved|| || || || ||
|-
|'''Loop Tiling (Blocking)'''|| Can Decrease||Increased||Improved|| ||Can Increase||
|-
|'''Loop Unrolling'''|| ||Increased|| ||Simplified||Increased||Increased
|-
|'''Loop Inversion'''|| ||Reduced|| || || ||
|-
|'''Loop Peeling'''|| ||Reduced|| || || ||
|-
|'''Loop Reversal'''|| ||Reduced|| || || ||
|-
|'''Loop Jamming'''||Improved||Increased|| || || ||Increased
|-
|'''Loop Shifting'''||Improved|| || || || ||
|-
|'''Loop Unswitching'''|| ||Reduced|| || || ||
|-
|'''Software Pipelining'''|| ||Reduced||Improved|| || ||
|-
| '''Induction Variable Substitution'''|| || || ||Simplified|| ||
|-
|'''Loop Rerolling'''|| ||Increased|| || || || Increased
|-
|'''Array Contraction'''|| || || || ||Reduced ||Reduced
|-
|'''Loop Coalescing'''||Can Decrease||Increased|| || || ||
|-
|'''Loop Hoisting'''|| || Reduced|| ||Simplified|| ||
|-
|'''Loop Strengthening Reduction'''|| || || ||Simplified|| ||
|-
|'''Loop Normalization'''|| ||Reduced|| ||Simplified|| ||
|-
|'''Loop Vectorization'''||Improved|| ||Improved|| || ||
|-
|'''Loop Parallelization'''|| || ||Improved|| || ||
|}
[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-02-27T10:50:56Z

Tobias.columbus: seo

The alias Attribute - Some things I learned about the alias attribute

2024-02-26T16:58:04Z

Tobias.columbus: typo

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.
== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer]. Just make sure that you don't omit the flag <code>-std=c23</code> when invoking clang.

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some address in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.
The columns are also explained in <code>objdump</code>'s [https://man7.org/linux/man-pages/man1/objdump.1.html manpage] and reading through <code>nm</code> 's [https://man7.org/linux/man-pages/man1/nm.1.html manpage] might give some further information if you're really curious.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are highly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute from a slightly different perspective.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

-----

<references />

[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-02-26T16:56:29Z

Tobias.columbus:

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.
== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer]. Just make sure that you don't omit the flag <code>-std=c23</code> when invoking clang.

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.
The columns are also explained in <code>objdump</code>'s [https://man7.org/linux/man-pages/man1/objdump.1.html manpage] and reading through <code>nm</code> 's [https://man7.org/linux/man-pages/man1/nm.1.html manpage] might give some further information if you're really curious.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are highly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute from a slightly different perspective.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

-----

<references />

[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-02-26T16:49:04Z

Tobias.columbus:

{{DISPLAYTITLE:Some things I learned about the alias attribute}}

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.
== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer]. Just make sure that you don't omit the flag <code>-std=c23</code> when invoking clang.

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.
The columns are also explained in <code>objdump</code>'s [https://man7.org/linux/man-pages/man1/objdump.1.html manpage] and reading through <code>nm</code> 's [https://man7.org/linux/man-pages/man1/nm.1.html manpage] might give some further information if you're really curious.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are highly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute from a slightly different perspective.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

-----

<references />

[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-02-23T09:23:53Z

Tobias.columbus:

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.
== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer]. Just make sure that you don't omit the flag <code>-std=c23</code> when invoking clang.

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.
The columns are also explained in <code>objdump</code>'s [https://man7.org/linux/man-pages/man1/objdump.1.html manpage] and reading through <code>nm</code> 's [https://man7.org/linux/man-pages/man1/nm.1.html manpage] might give some further information if you're really curious.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are highly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute from a slightly different perspective.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

-----

<references />

[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-02-22T17:11:46Z

Tobias.columbus: fixed typo and inserted links to nm/objdump manpage

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.
== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.
The columns are also explained in <code>objdump</code>'s [https://man7.org/linux/man-pages/man1/objdump.1.html manpage] and reading through <code>nm</code> 's [https://man7.org/linux/man-pages/man1/nm.1.html manpage] might give some further information if you're really curious.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are highly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

-----

<references />

[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-02-21T12:56:14Z

Tobias.columbus:

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

-----

<references />

[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-02-21T12:55:44Z

Tobias.columbus:

The alias Attribute - Some things I learned about the alias attribute

2024-02-21T12:54:58Z

Tobias.columbus:

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>, respectively.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions and some tentative definitions such as

<syntaxhighlight lang="c">int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt]. Funny enough, turning the tentative definition <code>int alias_var</code> into a definition with external linkage (in the standard’s sense, see §6.9.2 in the latest [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf working draft]) as in

<syntaxhighlight lang="c">extern int alias_var;

[[gnu::alias("alias_tgt")]]
extern int alias_var;</syntaxhighlight>
reconciles clang with the code snippet. As already mentioned above, GCC is more forgiving and accepts both variants.

So, what’s the upshot? I guess there are two points:

* GCC and clang don’t necessarily agree on what an <code>alias</code> actually is.
* If you’re using clang, an <code>alias</code> attribute on some declaration is very close to a usual definition. Just make sure that either the <code>alias</code> is the first declaration or all other declarations are explicitly extern.


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>

=== Links ===

* [https://developers.redhat.com/blog/2020/06/02/the-joys-and-perils-of-c-and-c-aliasing-part-1 Series of very well-written articles] by Martin Sebor for RedHat Developer. The [https://developers.redhat.com/blog/2020/06/03/the-joys-and-perils-of-aliasing-in-c-and-c-part-2# second article] also deals with the <code>alias</code> attribute.
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html GCC's documentation on common variable attributes]
* [https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html GCC's documentation on common function attributes]

====== Footnotes ======
<references />
[[Category:Compiler Background]]

The alias Attribute - Some things I learned about the alias attribute

2024-02-21T12:52:48Z

Tobias.columbus: added some relevant links

The alias Attribute - Some things I learned about the alias attribute

2024-02-19T16:49:05Z

Tobias.columbus:

The alias Attribute - Some things I learned about the alias attribute

2024-02-19T14:56:40Z

Tobias.columbus:

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt].


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>
<references />

The alias Attribute - Some things I learned about the alias attribute

2024-02-19T14:56:07Z

Tobias.columbus:

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use the address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memeory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt].


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>
<references />

The alias Attribute - Some things I learned about the alias attribute

2024-02-19T14:55:02Z

Tobias.columbus:

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.data</code> and <code>.bss</code>.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memeory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt].


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>
<references />

The alias Attribute - Some things I learned about the alias attribute

2024-02-19T14:48:32Z

Tobias.columbus:

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you’ve got some familiarity with C and are simply looking to use the <code>alias</code> attribute, it’s advisable to skim through the [[#syntax|syntax]] and [[#semantics|semantics]] sections before diving into some more complicated [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll probably find some engaging content in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].

Before delving in, it’s crucial to acknowledge (yet again) the portability issues associated with the alias attribute. While it offers some quite powerful capabilities, its usage should be approached with caution, especially in cross-platform projects.


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.bss</code> and <code>.data</code>.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memeory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt].


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her<ref>Actually, having an <code>alias</code> on a static symbol leads to that symbol being exposed in the corresponding object file’s symbol table, see [https://developer.arm.com/documentation/dui0491/i/Compiler-specific-Features/--attribute----alias---variable-attribute ARM’s documentation] for instance. However, I did not find a way to modify the value through that entry in the symbol table as it is a non-global object.</ref>.

* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>
<references />

The alias Attribute - Some things I learned about the alias attribute

2024-02-19T13:14:36Z

Tobias.columbus:

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you just want to use the <code>alias</code> attribute in some real world code and are aware of the portability issues, you’ll probably want to skim the sections on <code>alias</code>’s [[#syntax|syntax]] and [[#semantics|semantics]]. After that, I’d concentrate on the first two [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll almost certainly want to have a look at some bits in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.bss</code> and <code>.data</code>.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memeory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt].


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own and keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance espressif’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS].


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;

[[gnu::alias("essentially_const")]]
extern const int const_view;

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her.
* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;

[[gnu::alias("a")]]
extern uint64_t b;

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]]
extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;

[[gnu::alias("s")]]
extern uint64_t c;

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>
<references />

The alias Attribute - Some things I learned about the alias attribute

2024-02-19T12:17:35Z

Tobias.columbus: fixed lists

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes:

* If you just want to use the <code>alias</code> attribute in some real world code and are aware of the portability issues, you’ll probably want to skim the sections on <code>alias</code>’s [[#syntax|syntax]] and [[#semantics|semantics]]. After that, I’d concentrate on the first two [[#examples|examples]].
* If you enjoy torturing your compiler, you’ll almost certainly want to have a look at some bits in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.bss</code> and <code>.data</code>.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memeory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that

* the first column contains the address of a symbol in its segment,
* the fourth column contains the segment that contains the symbol,
* the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt].


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own. Keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules:

* An <code>alias</code> declaration should consist of a single declarator to avoid any confusion.
* If you can, stick to the syntax introduced in C2x.
* The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance <code>espressif</code>’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS] for instance.


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;
extern const int const_view [[gnu::alias("essentially_const")]];

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her.
* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;
extern uint64_t b [[gnu::alias("a")]];

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;
extern uint64_t b [[gnu::alias("a")]];

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]] extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;
extern uint64_t c [[gnu::alias("s")]];

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>
<references />

The alias Attribute - Some things I learned about the alias attribute

2024-02-19T12:07:46Z

Tobias.columbus: initial version

= Some things I learned about the alias attribute =

Recently, I had to read and modify some code that was responsible for handling <code>alias</code> attributes in C sources. Although I knew the <code>alias</code> attribute existed, I never had a closer look and thus needed to do some research. This escalated quite a bit and as documentation on attributes in general is rather scarce and the <code>alias</code> attribute [https://clang.llvm.org/docs/AttributeReference.html#alias poses no exception], I’d like to share my findings with you.

These notes begin with some probably rather dull remarks on the syntax of <code>alias</code> attributes and a subsequent explanation of how the compiler handles these. After having the basics up our sleeve, we have a closer look at some syntactic and semantic peculiarities. The remainder of these notes is then concerned with some cool or fun examples of what one might actually do with aliases. Readers who are easily bored or prefer to learn by example are well-advised to jump directly to these examples and return to the earlier paragraphs only when needed.

So, who’s the intended target audience? To be honest, I don’t exactly know. Obviously, these notes apply to C only and involve some rather low level hackery. Moreover, if you’re not using GCC or clang on some more or less common platform like <code>x86_64</code>, <code>ARM</code> or <code>RISCV</code>, the probabilities are high that your toolchain does not support the <code>alias</code> attribute at all. Now, if that didn’t put you off already, I can think of two possible ways of reading these notes: * If you just want to use the <code>alias</code> attribute in some real world code and are aware of the portability issues, you’ll probably want to skim the sections on <code>alias</code>’s [[#syntax|syntax]] and [[#semantics|semantics]]. After that, I’d concentrate on the first two [[#examples|examples]]. * If you enjoy torturing your compiler, you’ll almost certainly want to have a look at some bits in the [[#testing-out-the-limits|section on testing the limits]] and some of the later [[#examples|examples]].


== Syntax ==

Owing to the fact that attributes like the <code>alias</code> attribute have their origin in vendor-specific extensions to the C language, there are several ways to actually define an alias. We’ll only deal with two variants but the interested reader may find a third variant by looking [https://releases.llvm.org/7.0.1/tools/clang/docs/LanguageExtensions.html?highlight=apply_to#specifying-an-attribute-for-multiple-declarations-pragma-clang-attribute here]. Moreover, not every syntax is compatible with every compiler or even compiler settings, and different compilers do not necessarily agree upon the way in which certain attributes interoperate with standard C features. We’ll see examples below, so stay tuned.


=== GNU C ===

The GCC compiler originally introduced the <code>alias</code> attribute in GNU C using its <code>__attribute__</code> syntax. According to [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation], an attribute specifier is of the form

<pre>__attribute__(( attribute specifier list ))</pre>
where the attribute specifier list is going to consist of the single attribute <code>alias("alias_tgt")</code> for the greater part of these notes. In principle, such attributes could be attached to anything in your sources. However, the <code>alias</code> attribute applies only to variable and function declarations. In the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt1")))
extern int alias_var;

__attribute__((alias("alias_tgt2")))
extern void alias_fun();</syntaxhighlight>
the attribute <code>alias("alias_tgt1")</code> applies to the declaration of <code>alias_var</code> whereas the attribute <code>alias("alias_tgt2")</code> applies to the declaration of <code>alias_fun()</code>.

We’ll look into what exactly these <code>alias</code> attributes mean, but for the moment it suffices to think of these declarations as introducing an additional name <code>alias_var</code> for the previously defined variable <code>alias_tgt1</code> and an additional name <code>alias_fun</code> for the previously defined function <code>alias_tgt2</code>.


=== C2x ===

Now, the reader might know very well that the attribute syntax

<syntaxhighlight lang="c">[[ namespace::attribute ]]</syntaxhighlight>
introduced in C++11 is to be included in the upcoming C2x standard. If you want to have a look, the draft on attributes can be found [https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2335.pdf here].

As the <code>alias</code> attribute originated in GNU C, the <code>namespace</code> is going to be <code>gnu</code> in our case of interest. Hence, in C2x our first example of aliases from above could also be written as

<syntaxhighlight lang="c">[[ gnu::alias("alias_tgt1") ]]
extern int alias_var;

[[ gnu::alias("alias_tgt2") ]]
extern void alias_fun();</syntaxhighlight>
and both clang and GCC happily accept this syntax, as witnessed by [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJ0hwBk8DTAA5dwAjTGIQAHZSAAdUBUJbBmc3Dy9Y%2BMSBPwDgljCI6MtMayShAiZiAhT3TykLTCsbAXLKghyg0PCoiwqqmrT6hT72/0787siASgtUV2Jkdg5/AgBqMTwmBWMCYAIuAFIAZgAhA40AQQA3VDx0ddpN7d2CACYIKdWDyLPIgBFzhdAQcAKxnMGrYAMVwgEAbLYQA6vV7w557Q7Iz6ggEggGXTCqAjhBirFYPJ7GK6VY5nS7AsGgk6Q6Gw1GI5GonZ7V5I15Y3HYwEEonEEk3O7krbGKiuBgfGkcGa0Tgg3ieDhaUioTiOVYKOYLTBfV5HHikAiaRUzADWICORwAdAAOABsGi4GkirxdTq4TqdkRd%2Bk4kjVlq1nF4ChAGnNlpmcFgMEQKFQLBidHC5EoaHTmYiyGQBiMO2IsutfDoIujEBC4ZC/kqAE9OGaG8xiE2APIhbQlC3cXi5tiCLsMWgtjW8LAhVzARxiWjRwekLAsQzAcRT1d4Yj9vBXTDLzUEkquImt3grRrhx4hYjN5xYcMEYh4FiXmZUAzABQANTwTAAHcuxiRhLxkQQRDEdh6n4QRFBUdRt10Lh9A3EBTGMcw72jSAZlQGJmgYZcAFpkFWUjhnQY4/mQE1eFQQ9iDfLA8I%2BBomiSewGCcFxaj0XwxjyAo9DiBJiIGOoMgkpIOhE7o0OKUoWhGKS9GU4jWiqeSugiJS1P4wZejaXSJn0mZ9XmRYJCVFUw23bUOFWVRXVIl1JFWIsN1WCBX3LT4IFwQgSGNU0pl4ActCmG07VeZ0NBdEEQQATiOFKnUkSJIhS15gw4UNSA/JKHS4P0Uq4V4cq9J08vVTUnKjGM4ynBNkwgJA5gIGJz2zCBcwzehiECVgllcl13M87yjFWLhIgdDRSt4TB8CIVi9Hg4RRHEODZEQtRw1Q0ggIfGJP3y1VSHqxjOC7c8erWVAqBctyPK84tgF8/yGGtQLnDzIawq4CKWuimYEEwJgsAiDjlQK3gPyOSRnV9DQA1eDQqr9d0rvDRqLGaqKrVIW0jnip1EuStKMqynK8rho4HIayNQcVUhEygdqkAG/M%2Bp5oaUGALgycrWhq0oOtt3bZsIOlzsez7awIOHRgCDHCdwxnOcF1oJcILXDct01fA91KQ9j2W1QzwvFdrzhzU7wfTsnyWTVX3fc7vyYX8AOA0DwJXTboJ26RNv25DNV0emMKwnC8BCdiCKIpIyOQRjmNYo94Esxp9zsCAHHUtChNyPSxMySSjOk8SsgYMzRKU3OVIYbTqirjSm60kZ68Ukz%2BnbgzTOEsvgdmazYLsjhLuuiNnPGybIULWbHVeXzgrWoGQaJmKSbtR17QPw%2Bj/ywriq4B0vSkDRJCODQjhBD1stxxyWejWNt/ZrmQC6h6%2BbTQbwgjTYJweeb1gBL2Fg6V4y1VokDuBtWQwdYKhz2koA6KEQB5ROkwM6g5J7Tzxrde655VhPRehNMBECV6%2BX%2BgA4gYU%2BSRXjODSG0NKCT1PnaJ0UDIhOlSiCF0KUPJOlykcZ%2BzMOBNXfsw3e9oHRHwUQffKjNxE3UkazHecNoGqNnkw1qMxmIJDsJIIAA compiler explorer].

What is more, the proposal comes with clear and precise rules, where attributes can appear. It tells us that C2x will

<pre>[...] allow an attribute specifier to appear to the left of a
declaration so that the attributes appertain to all of the declarators in
the declaration list, or to appear to the right of all declaration
specifiers so that the attributes appertain to the type determined by the
specifier sequence.

[...]

Similarly, an attribute specifier can appear to the right of a type in a
declarator to appertain to the type, or to the right of an identifier in a
declarator to appertain to the identifier declared.</pre>
So, our above example might have also been written as

<syntaxhighlight lang="c">extern int alias_var [[ gnu::alias("alias_tgt1") ]];

extern void alias_fun [[ gnu::alias("alias_tgt2") ]] ();</syntaxhighlight>
and, again, both clang and GCC happily accept this syntax. This can also be checked on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQAVgDspBwAyeAyYAHLuAEaYxCAAbKQADqgKhLYMzm4e3n5JKTYCQSHhLFEx8ZaY1mlCBEzEBBnunr4WmFb5DDV1BIVhkdFxFrX1jVktCsM9wX0lA7EAlBaorsTI7BzBBADUYnhMCsYEwARcAKQAzABCpxoAggBuqHjoO7R7B0cEAEwQ81unPmuPgAIjdbmDMKoCNEGFtNq93sZ7nV/l5rmitsAGK4QCBdvsIKcvl98R9jmdiX9Tl5QTSLtc7hCoTCto9ngj9sYqK5YdT0ZdMdjcaTCcTSYdjl8iV8qXSaVtfvSOItaJwvLxPBwtKRUJxHFsFMtVph/l9zjxSARNMrFgBrEDnc4AOgAHLENFwND4vrEXVwXS6fPFVRxJBrrTrOLwFCANJbrYs4LAYIgUKgWAk6NFyJQ0BmszFkMgDEZDsQeba%2BHRocQYxAIhGIsE6gBPTgWpvMYgtgDyEW0lSt3F4ebYgh7DFoba1vCwEVcwEcYloMeHpCwLEMwHEM/XeGIg7w90wq%2B1kMqrmh7d4mzaEbeEWIrecWAjBGIeBY18WVAMwAUABqeCYAA7j2CSMNeMiCCIYjsFI0HyEoagRroXD6FuICmMY5gPjGkCLKgCQdKuAC0yBbKREzoBcwLIGavCoMexAflg%2BG/K07RpPYDBOC4TR6IE0zFKUei5KkAijJ46HiR0vQiQM6EVFUAhdCM/FZEpbSHqpkzyf0MRKZMUl6BM3T6bMhmLIaKxrBIKpquGu66hwWyqG6pGxJIWzFluCrvhWfwQLghAkKa5rzLwQ5aPMdoOl8roaLEXheAAnOcqUupIPg%2BKlXz6JwYakF%2ByVOlw/qpVwXy5d6Lr5Zq2oudGsbxjOiYphASDLAQCSXjmEB5pm9DEKErDrO5sSed5vlGFsXA%2BE6GhlbwmD4EQrF6PwMGiOICFbUhKjqLuaGkCBT4JN%2BBUcOqpANYxnA9pevXbKgVBuR5Xk%2BSWwD%2BeWDC2kFzj5sN4VcJFrUxYsCCYEwWAxBxIZFV%2B5ySK6foaIGXwaNV/oerdEZNRYLXRTapD2ucCUuklKXpZl2W5flIbnE5jVRhDyqkEmUAdUgg0Fv1fPDSgwBcBTVa0DWdYNrunatlBsvdn2A7WFBo6MAQE5ThGc4LkutArlBG5bju2r4AeVTHqeK2qBeV5rreIbag%2BT7di%2B6zau%2Bn6Xb%2BTD/kBoHgZBa77bBu3SPtiiHahICM5h2G4XgETsYRxFpGRyCMcxrEnvA1naSpngQA4JnoUJRQGWJyQSekGnSYkVdycJFdaVxundCXnE6Z0elN5ZpnGbX/fmb3olg0stnwQ510s/drkTVNmJFnNzpfAqIXraD4Mk7FZMOs6joH4fR9XUjcRcE63pSBokjnBo5xeJ6OX485bMxnG2%2BczzIDdc9AvpkN0RRpsE4PPT6wAl6iydF8Faa0SDPE2rIUO8Fw6yEjihY6MdTrnUuiGG6d1IwcEej1S8WxXrvUmmAiBK8FRAwAcQcKMoooJihjDOGlAp6n3OC6KBPgXRpS8LEVKXkXR5XOM/VmHBmrv2YbvR0Toj4KIPldZm4jZ5MLalPaBqiCHqMhqQZiKQ7CSCAA%3D%3D compiler explorer].


== Semantics ==

In this section, we explain what the compiler makes of an <code>alias</code> attribute and give some first working examples. However, in order to explain how the <code>alias</code> attribute really works, we first need to recall some simple facts about symbol tables in object files.


=== Symbol tables ===

'''Disclaimer''': While preparing these notes, the author was working on a GNU/Linux machine and while the specifics given below do not necessarily apply verbatim to your toolchain, the underlying mechanisms are almost certainly the same.

Whenever you declare a global variable or a function in one of your C sources, it ends up as an entry in the corresponding object file’s symbol tables, so that other parts of your program may use it. There is a symbol table for executable code, i.e. functions, called <code>.text</code> and there are symbol tables for initialized and uninitialized data called <code>.bss</code> and <code>.data</code>.

An entry in the symbol table simply tells the linker what a specific name in your program means. That is, an entry in the symbol tables either maps an identifier to a specific address in one of the segments of your object file, or is marked as <code>UNDEFINED</code> to tell the linker that this symbol must be defined in some other object file or library.

If you have one module <code>a.c</code> defining a global variable <code>global</code> and another module <code>b.c</code> using that global variable like in the example

<syntaxhighlight lang="c">// a.c
int global = 23;

// b.c
extern int global;</syntaxhighlight>
then the symbol table of <code>a.o</code> will contain an entry mapping <code>global</code> to some adress in the <code>.data</code> segment and the symbol table of <code>b.o</code> will contain an <code>UNDEFINED</code> entry for <code>global</code>. The linker is then responsible for merging the symbol tables and making the code in <code>b.c</code> actually use address of <code>global</code> in the <code>.data</code> segment of <code>a.o</code>.

The main point I want to make here is that names of functions and global variables are merely entries in some symbol tables that eventually map to specific addresses in memeory. This means in particular that two names mapping to the same address will be indistinguishable after compilation and linking because a processor does not know of any names but works with memory addresses only.

Actually, this last paragraph fully explains how the <code>alias</code> attribute works.


=== A simple example with variables ===

Let’s get our hands dirty and try to understand the <code>alias</code>-attributes by investigating the following simple example:

<syntaxhighlight lang="c">// simple.c
int alias_tgt;
extern int alias_var [[gnu::alias("alias_tgt")]];</syntaxhighlight>
Compiling these two lines and looking at the symbol table of the resulting object file by invoking <code>objdump</code> or <code>nm</code>, reveals what happens inside your compiler:

<pre>> objdump --syms simple.o

simple.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 simple.c
0000000000000000 g O .bss 0000000000000004 alias_tgt
0000000000000000 g O .bss 0000000000000004 alias_var</pre>
Don’t worry, if you don’t know how to read the output of <code>objdump</code>. For our purposes, you only need to know that * the first column contains the address of a symbol in its segment, * the fourth column contains the segment that contains the symbol, * the last column contains the name of the symbol.

In our simple example, we thus find two symbols <code>alias_tgt</code> and <code>alias_var</code> at address <code>0</code> of the segment <code>.bss</code> for uninitialized data. Once loaded into memory by your operating system or a boot loader, the variables <code>alias_tgt</code> and <code>alias_var</code> from <code>simple.c</code> will hence refer to the same actual address in memory and are indistinguishable from your computer’s point of view.


=== A simple example with functions ===

The alias attribute does not only apply to variable symbols but also to function symbols. Compiling the example

<syntaxhighlight lang="c">// fun.c

int fn(int a) {
return a + a;
}

[[gnu::alias("fn")]] int twice(int);</syntaxhighlight>
and investigating the resulting object file with <code>objdump</code>, we get the result

<pre>> objdump --syms fun.o
fun.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 fun.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e fn
0000000000000000 g F .text 000000000000000e twice</pre>
Again, we have two symbols <code>fn</code> and <code>twice</code> in the <code>.text</code> section of our object file that share the single address <code>0</code>.


== Testing out the limits ==


=== What exactly is an <code>alias</code>? ===

We now know more or less what the compiler does when it encounters an <code>alias</code> attribute. However, it is not so clear what an <code>alias</code> attribute means in terms of the C language. Essentially the only official documentation on the <code>alias</code> attribute is GCC’s [https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html documentation] of which I’ll quote the relevant first half:

<pre>The alias variable attribute causes the declaration to be emitted as an alias for another symbol known as an alias target. Except for top-level qualifiers the alias target must have the same type as the alias. For instance, the following

int var_target;
extern int __attribute__ ((alias ("var_target"))) var_alias;

defines var_alias to be an alias for the var_target variable.

It is an error if the alias target is not defined in the same translation unit as the alias. </pre>
One question that remains unanswered by this explanation is the question whether an alias is a definition in the standard committee’s sense. In fact, this is the question that originally initiated my investigations into the <code>alias</code> attribute.

Without further ado, let’s see what GCC and clang have to say. The snippet

<syntaxhighlight lang="c">int target;

[[ gnu::alias("target")]]
extern int alias_var;

int alias_var;</syntaxhighlight>
is happily accepted by both GCC and clang. However, if we turn the second declaration of <code>alias_var</code> from a tentative definition into a certain definition by changing the second declaration to

<syntaxhighlight lang="c">int alias_var = 0;</syntaxhighlight>
the two compilers start to disagree. In fact, clang complains about a redefinition of symbol <code>alias_var</code> while GCC tells us nothing. See for [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMJAVlIOAMngMmABy7gBGmMQgAOykAA6oCoS2DM5uHt7xickCAUGhLBFRsZaY1ilCBEzEBGnunlw%2BpeUCldUEeSHhkTEWVTV1GY197Z0FRTEAlBaorsTI7BwApBoAgoEEANT9wJgESwDMAEIrq6dLXieXm8AMriAgYnhMChBLAEzvO3sf75MXABFAadMKoCJEGJsNpsni9Dic1qdobCFJtDgDNhp4RxprROF5eJ4OFpSKhOI5NgpZvNMGj3gceKQCJocdMANYgA4HAB0AA4AGwaLgaaLvfm8ri83nRfn6TiSQks0mcXgKEAaJks6ZwWAwRAoVAsOJ0SLkShoI0mqLIZAGIzGAjEVwMNl8Ojg4hqiBhJVhQLVACenEZfuYxADAHkwtoyszuLwLWxBBGGLQg8TeFgwq5gI4xLQ1fHSFgWIZgOIM8W8MRY3gAG6YQsk0FlVzg4O8DaYPGV2h4MLEQPOLBKx14Fgd6ZUAzABQANTwmAA7hG4owOzJBCIxOwpJv5Eo1ErdFx9GWQKZjOY%2B2E1ZBpqg4jYBIWALTITavhQEdDo5D03hUAbYhiDwLA7wgaZmmfTwIAcQYGl8Bh0DGboolPBIkhghC9EwnIGFQwoelPaCKn6WoXHqPRSNacjCImEjyJwxjRkCLoiPQqDqQWCRcXxRVKzJDhNlUAVX35SRNltMtNggR1nTZSZZNwQgSDpBlJl4OMtEmdlOXePkNH5LwvAATgOUzeUkaJolM945Q4BVSAnYzuS4SVTK4d5bNFXl7KJEkhNVdVNQzbU9QgJBZgIOI2zNCALWNehiGCVhFlE/lxMk6SjE2Lhom5DQ3N4TB8CIUD0D0fgt1EcQ92qg8VHUSsT1IJdBziScHIJUgAsAzgIzbWKtlQKgRLEiSpLtYBZPkl0lIgZxLWS9SuE00KdOmBBMCYLAokghynInA5JD5CUNGld4NG8yUhV6pUgosELtNZUgOQOAzeSMkzzMs6zbPsnsDgEwKVQ2nFSB1KAIqQRKrXiuHkpQYAuA%2Bt1aA9L0fUrUNAw3XHwyjGNrA3RNGAIFM0yVLMczzWgCw3EsywrEl8BrcoGybErVFbdsiy7HsSRvQdw2HRYSTHCd4ynGd50XFc1yJRkGu3OrpAaxQmuPEBAfPS9r37CCHyfFI32QQDgIqxt4Cg7tazsODkOYpCULY8ZiKyLCUmdvCYPoj2aIYNoBkooYLDtlog7ot20OopjQ8Q79WPyWO1pmOYeLTnser65VhIyrKbhtPKeXeZSyrUj4NK0rU9K5bkuUbpvm8O3gXK4blRSkDRJAODQDi8YUbPuwSwbVDUXvC%2BBIpAaLhoRw0ksiVK2E4AvJuAYvUe5d4SoriqqtkVXd3V2RNaPFqdbajquuzkH%2Bo4QaYrbTZRvGzKN630vZKWpfiHUv4NcwpbR2ntSgfFHJt05LyHe0ReRmS8PyUyEleR2QOCPUGHBgoT1rm9TkPJm6EMbg5YGGCH5AM2g5XeZC84UNesBJIdhJBAA%3D%3D yourself]. When you’re at it, you may check that GCC also accepts the alias after a definition of <code>alias_var</code>.

Now, it seems that clang treats the <code>alias</code> as a symbol definition and thus rightly complains about a symbol redefinition. But what does GCC do? Well, a quick inspection of the symbol table tells us that the alias seems to override any other variable definition that exists. There’s also this old [https://gcc.gnu.org/bugzilla/show_bug.cgi?id=91765 bug report] for GCC that seems related but never got any activity.

By the way, when it comes to functions, both clang and GCC seem to treat an <code>alias</code> attribute as a function definition and therefore complain about redefinitions.

Returning to variables, there’s one last surprise. Above, we noted that it ''seems'' that clang treats the <code>alias</code> as a symbol definition. However, that’s not completely true. Whereas a definition may appear after any number of tentative definitions, clang does not allow this for <code>alias</code> definitions as can also be seen on [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYM9DgDJ4GmADl3ACNMYhAAVlIAB1QFQlsGZzcPPVj4mwFffyCWUPCoy0xrRKECJmICZPdPLgtMK0yGMoqCbMCQsMiLcsrq1LqFXra/DryuiIBKC1RXYmR2DgBSDQBBPwIAal7gTAIlgGYAIRXV043NsTwmBWMANwrDk7XTpYiT983gBlcQECubhAlgAmYE7PYg4GTN4AEVhp0wqgIYQYmwuANuD2ITw401onAivE8HC0pFQnEcmwUs3mmE2IIOPFIBE0uOmAGsQAcDgA6CIATgAbAB2YEaA4aDTCwVcDRRfEcSRE1lkzi8BQgDTM1nTOCwGCIFCoFjROhhciUNAms3hZDIAxGYwEYiuBjsvh0ZHEDUQYIq4J%2BCoAT04TIDzGIQYA8sFtMUWdxeFa2IIowxaCGSbwsMFXMBHGJaBrE6QsCxDMBxFnS3hiPG8HdMMXSYjiq5kaHeBsGiraHhgsRg84sCrnXgWJ3plQDMAFAA1PCYADuUeijE7MkEIjE7Ckm/kSjUKt0dQdJjM%2Bn7Gsg01Q0SaxYAtMhNo%2BhuhDjDkMCDrxUI3iGIPAsGvCBpiKEo7AgBx%2BlqUgfFGXJ8jSOIEgEWCUIyRJ2iQrpBgaesBBaPoXBqPQIKaYiRhyTpwkGYYMPo1ocNoiRwJpBY2P0AllWrckOE2VQAA5BUfQVJE2e0K02CBnVddlJhk3BCBIekfy4SZeATLRJg5LlgR5ISNEFCIBQOfkhMkYVhX5YFuMVXgJwiQUeSkSQImFITGQOYEIglPdiVJfj1U1bUs11A0ICQWYCGidsLQgK1TXoYgAlYRZhNE8TJLPTYuGFHkNFc3hMHwIggPQPR%2BC3URxD3aqDxUdRqxPUgl0HaJJ3swlSECv9OCjds4q2VAqEEkSxIkqSjBkuS3UUiBnGtFK1MZTSwp06YEEwJgsHCMD7KVUgJ0kXkhNMyRgS4QUROFSRBQswVepVYKLFC7S2VITluUKh7%2BXug4TP5OVBUB%2Bzf2evi1Q23FSD1KBIqQJKbQS5GUpQYAuB8j1aC9H0/WrcNgw3InIxjONrA3ZNGAINMMxVHM8wLWgiw3MsKyrUl8DrEpG2bErVDbDsS27BVST7AchwwRZSTHCdEynGd50XFc12JJkGu3OrpAaxQmuPEA7LPEBTGMcwJdA2970SYs/wAiqm3gcCCMgzxoIYJxSIGIT4I9ljxnCOz0jQpIvdqH3g6af3kLsijSgYsOJB9uOiOGaOuljhOUnDnpmMQ1ioRmOZOI07reKCzhxqyiTgDtPLeWBJSytUhkNK0nU9J%2B7lu573vDscyItT61UOBCrUPoi%2BAopAGLhtR41krCNK2E4TLJq%2BOusZ5YESubiqqtkLXdx12Q9aPFrDbajquoVHrh/4wbYvbTZRqr9fa5fLfG8WhebVWqF27hS2jtPalA8ScCOk5IeL1oYanHh3L6XJeS9xQd3cG5d%2BqjxhrpeyO9IYVywRPaYAF4h2EkEAA godbolt].


=== Syntactic limits ===

The reader may have observed that while the clear rules for the attribute syntax in C2x were [[#c2x|highlighted above]], there was no mention of any rules in the case of GCC’s original syntax. There’s a reason for that and in order to set the stage, let me quote from [https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html GCC’s documentation] on its attribute syntax:

<pre>For compatibility with existing code written for compiler versions that did not implement attributes on nested declarators, some laxity is allowed in the placing of attributes.</pre>
Even though we’re not dealing with any nested declarators here, let’s see what GCC and clang are able to swallow. In fact, all four declarations in the example

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern int alias_var1;
extern __attribute__((alias("alias_tgt"))) int alias_var2;
extern int __attribute__((alias("alias_tgt"))) alias_var3;
extern int alias_var4 __attribute__((alias("alias_tgt")));</syntaxhighlight>
are happily accepted by both GCC and clang and turn out to be semantically equivalent. For function aliases there are even more positions where one could place the <code>__attribute__</code>. Of these, the correct C2x variant

<syntaxhighlight lang="c">extern void alias_fun __attribute__((alias("alias_tgt"))) ();</syntaxhighlight>
is rejected by both GCC and clang, and the variant

<syntaxhighlight lang="c">extern void alias_fun (__attribute__((alias("alias_tgt"))));</syntaxhighlight>
is of course interpreted as an attribute for parameter declarations. Thus, just as in the variable case, we are left with four valid and semantically equivalent variants to define a function alias:

<syntaxhighlight lang="c">__attribute__((alias("alias_tgt"))) extern void alias_fun1();
extern __attribute__((alias("alias_tgt"))) void alias_fun2();
extern void __attribute__((alias("alias_tgt"))) alias_fun3();
extern void alias_fun4() __attribute__((alias("alias_tgt")));</syntaxhighlight>
Note that for functions like <code>int* fn()</code> returning a pointer, there are even more variations of a function <code>alias</code> definition. Rest assured that in this case, too, GCC and clang swallow whatever you may come up with except for the two cases already excluded above.

However, one step further, GCC and clang start to disagree on what monstrosities are still acceptable. The alias <code>inbetween</code> in the example

<syntaxhighlight lang="c">int** ptr = 0;
int** target() {
return ptr;
}

extern int * __attribute__((alias("target"))) * inbetween();</syntaxhighlight>
is still accepted by clang while GCC has problems parsing the corresponding line and consequently does not export a function called <code>inbetween</code>. You can see the warning in [https://godbolt.org/#z:OYLghAFBqd5QCxAYwPYBMCmBRdBLAF1QCcAaPECAMzwBtMA7AQwFtMQByARg9KtQYEAysib0QXACx8BBAKoBnTAAUAHpwAMvAFYTStJg1AB9U8lJL6yAngGVG6AMKpaAVxYMQANi6kHAGTwGTAA5dwAjTGIQAHZSAAdUBUJbBmc3D29fROSbAUDgsJZI6LjLTGtUoQImYgJ0908fC0wrPIZq2oIC0Iio2IsauobM5oUh7qDe4v6YgEoLVFdiZHYOIIIAKk2AaniCYh2AUgBmABEdjVOAISONAEE7%2B43tnaHgTAIIOeOY24edjtiJ9lgw9gcbk8jjEzlCHphVAQomCNjtdqYmAQDnhwq4kaYoGI8EwFBAjgAmcnvT4U8lzelonZBSIEADumEY3xuHAWtE4AFZeJ4OFpSKhOI4dgolitMMdySceKQCJoeQsANYgE4nAB0AA4vBouBoYuSvHquHq9TEvPpOJIhaqxZxeAoQBplaqFnBYDBEChUCx4nQouRKGggyHoshkAYjMYDq4GOq%2BHQkcQ3RBwk7wkFagBPThK3PMYj5gDy4W0FRV3F4EbYgnLDFohZFvCwuOAjjEtDdddIWBYhmA4nbg7wwMqADdMP3RQiKni1kqNq0nbQccQC84sE7sSwizy%2BAZgAoAGp4TCs8vxRhHmSCERidhSR/yJRqJ26XxxkxmfQcTdSAFlQfZUn7ABaZAdkg8Z0FOM5kAVXhUFnYhiDwLBgO%2BFo2lSewGCcFxGj0AIpiKEo9ByFIBBGTxsiSWiGB6Sj%2Bl8cpKgETphhIzIONaGsqgmVi%2BmiDiJnovRxi6USZnEhZpWWVYJF5AVHXHcUOB2VQDUgrxJB2WMRx2CBE2TH4IFwQgSHlRU5l4WstHpUhNROcl9Q0Lx%2BX5ABOE5fL1SQYhiXzyTtDgHVIQ9vJ1LhLV8rhyVC009XC4VRS0113U9dtvT9CAkCWAh4jxMMIAjYN6GIEJWDWXSvH0wzjKMHYuBiHUNDi3hMHwIhMPQPR%2BCfURxDfYaPxUdRxx/UhWW3eIjzUjhBVIDLUM4cs8VKggdlQKgdL0gyjL/UzzPVSznEjaq7K4BzcuchYEEwJgsGiXC%2BUi3hDxOSR9QtDRrXJDRkstI01qdLKLBypy1VcrUPL1LyfP8wLgtC8LPpODTMpdB7jx9KACqQSqo3K0nqpQYAuHc1NaHTTNs3HEsCwfFmy0ratrAfBtGAIZtWydTtXG7Xt%2ByVIcRzHUV8CnGxZ3nHrVCXJEHzXT7RU3cJtzLXc1lFA8lpPJgz0va9b3vAcJufMbpAmxQpu/EBMZHEBTGMcwtZw0DwIEKDkFQ9CBrneBFMErjPAgBwpN8cjCjE6imPaGOEiT1I5KogT8O4yS%2BIYvChJz2SKITiSuhTmS6gz9jFJlFS7oi1b1udbSGqanZgBjNrdXJUzrP6277thly3N1bVx4nyeIqimKuB1U0pA0SQTg0E5%2BWNEKIc0vG3Q9YfSEJwqQGKnbycDKqolqthODb47O5gmmdXJHq%2BpILChtkG3Xzt2QHa/GbnZzQWkbT6TdIabW2niPaB1b6GXvt3J%2BpkroX0OBSdyQ8vRPRem9Sgy0Z5aj1E/GIeo/L8i8L5AyeowonC3rjDg2U96YPhtqHUk82HjwitjWhG16H4xcp9Z%2B3CW6OSYehZIdhJBAA%3D%3D compiler explorer] and either investigate the symbol tables on your own or have a look at the output on my machine:

<pre>> clang -c -std=c2x between.c
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g F .text 000000000000000e target
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000e inbetween</pre>
and

<pre>> gcc -c -std=c2x between.c
between.c:6:1: warning: ‘alias’ attribute does not apply to types [-Wattributes]
6 | extern int * __attribute__((alias("target"))) * inbetween();
| ^~~~~~
> objdump --syms between.o
between.o: file format elf64-x86-64
SYMBOL TABLE:
0000000000000000 l df *ABS* 0000000000000000 between.c
0000000000000000 l d .text 0000000000000000 .text
0000000000000000 g O .bss 0000000000000008 ptr
0000000000000000 g F .text 000000000000000d target</pre>

=== A Word of Warning ===

Even though the beginning of the preceding paragraph might have left you with the impression that we may place <code>__attribute__((alias="target"))</code> essentially wherever we want, the placement does matter for a declaration list. In

<syntaxhighlight lang="c">extern int a, b __attribute__((alias("target"))) ;</syntaxhighlight>
only <code>b</code> is an <code>alias</code> for <code>target</code> while in

<syntaxhighlight lang="c">__attribute__((alias("target")))
extern int a, b;</syntaxhighlight>
both <code>a</code> and <code>b</code> are <code>alias</code>es for <code>target</code>. If you don’t believe me, just have a look at the symbol tables on your own. Keep in mind that this remark applies to the new C2x syntax, too.

So, if I’d be pressed to write guidelines for <code>alias</code> attributes, I’d suggest the following simple rules: * An <code>alias</code> declaration should consist of a single declarator to avoid any confusion. * If you can, stick to the syntax introduced in C2x. * The attribute annotations have to be placed in front of the declaration like in our very first examples for the [[#gnu-c|GNU]] and [[#c2x|C2x syntax]] as this syntax seems to reliably work with both GCC and clang.


== Examples ==

We’ll give several slightly more involved examples of the <code>alias</code> attribute. The first two of these examples are real-world examples. The other examples again more or less classify as ''testing the limits''.


=== Aliases as portability and linking hacks ===

One problem where aliases might come handy is offering a specific API without renaming all your functions or offering different implementations of an API and switching between these implementations by changing aliases, e.g. with guarding <code>#ifdef</code>s. Among other examples for this use case, searching on github for <code>__attribute__((alias</code> yields for instance <code>espressif</code>’s [https://github.com/espressif/esp-idf/blob/f68c131e5603feca21659e92ad85f0c3369692fe/components/vfs/vfs.c#L1316 implementation of VFS] for instance.


=== Software engineering with aliases ===

Another nice trick that crucially employs aliases is more related to software engineering than to linking problems: Imagine a situation, where one module of your software owns a global variable <code>essentially_const</code> that is computed once during startup but constant afterwards. If <code>essentially_const</code> is exposed as a global variable, then - rather sooner than later - some rogue developer on your team will introduce a function that modifies <code>essentially_const</code> and thereby introduce a hard-to-find bug<ref>With some non-negligible probablity that rogue developer is you!</ref>. After all, <code>essentially_const</code> is a non-constant global variable and modifying it should be OK, right?

Let us indicate a neat solution for this problem that makes good use of aliases:

<syntaxhighlight lang="c">// a.c
static int essentially_const;
extern const int const_view [[gnu::alias("essentially_const")]];

void init() {
essentially_const = 42;
}

// a.h
extern const int const_view;

void init();</syntaxhighlight>
Let’s see what’s happening here:

* The variable <code>essentially_const</code> in <code>a.c</code> is declared non-constant and the function <code>init()</code> at the bottom of <code>a.c</code> may consequently modify it as its author pleases. Moreover, <code>essentially_const</code> is declared <code>static</code> and it therefore has internal linkage. That means in particular that our rogue developer cannot modify <code>essentially_const</code> as the symbol is not exposed to her.
* In addition to <code>essentially_const</code>, the module <code>a.c</code> also defines a variable <code>const_view</code> of type <code>const int</code> as an alias of <code>essentially_const</code>. This global symbol is then exposed in <code>a.h</code> to all other modules of the project. What have we gained? The interface <code>a.h</code> of the module <code>a.c</code> now clearly states that <code>const_view</code> is constant and any compiler will complain if said rogue developer tries to modify its value.

In fact, trying to compile

<syntaxhighlight lang="c">// rogue.c
#include "a.h"

void fn() {
init();
const_view = 13;
}</syntaxhighlight>
results in an error message such as

<pre>rogue.c: In function ‘fn’:
rogue.c:6:14: error: assignment of read-only variable ‘const_view’
6 | const_view = 13;
| ^ </pre>
That clearly tells our rogue developer that modifying <code>const_view</code> is an evil thing to do.

Actually, this trick is not something the author came up with by himself. Rather, while doing some preliminary research for these notes, the author learned this technique from a [https://github.com/simbricks/qemu/blob/c247fb0c7c5fd4e24b5f08f65857b7bf08ce20fe/exec-vary.c#L28 source file in the qemu repositories], where the reader may also find some complementary explanations.


=== Doing weird stuff with aliases ===

As mentioned earlier, aliases are essentially just a way to have distinct names for the same memory address. As already exploited in the previous example, this means in particular that the aliasing mechanism bypasses C’s already quite weak type system and we might very well have symbols of different types sharing a single memory address.

In the example

<syntaxhighlight lang="c">// double1.c
#include <stdio.h>
#include <stdint.h>

double a;
extern uint64_t b [[gnu::alias("a")]];

#define SIGN_MASK 0x8000000000000000UL

int main(int argc, char **argv) {
a = 0.5;
b |= SIGN_MASK;

printf("%f\n", a);

return 0;
}</syntaxhighlight>
we have a symbol <code>a</code> of type <code>double</code> and a symbol <code>b</code> of type <code>uint64_t</code> sharing the same memory address. Running this example on a computer, where a <code>double</code> occupies 64 bits and where the sign of doubles is stored in the most significant bit, will result in an output like

<pre>> ./double1
-0.500000 </pre>
The reason is that the line

<syntaxhighlight lang="c"> b |= SIGN_MASK;</syntaxhighlight>
sets the most significant bit of the value stored at the address referred to by <code>b</code>, i.e. the very same address that <code>a</code> refers to. This most significant bit of <code>b</code> thus happens to be the sign bit of our double <code>a</code>.

As the reader might guess and as witnessed by the following example, one is of course not confined to messing around with the sign bit of floating point numbers. If you know the format of your floating point types, you might freely modify the exponent or the mantissa:

<syntaxhighlight lang="c">// double2.c
#include <stdio.h>

double a;
extern uint64_t b [[gnu::alias("a")]];

#define EXPONENT_MASK 0x7FF0000000000000UL
#define EXPONENT_SHIFT 52

int main() {
// messing with the exponent
a = 1;
b = (b ^ EXPONENT_MASK) | ((b & EXPONENT_MASK) + (2UL << EXPONENT_SHIFT));
printf("%f\n", a);

// messing with the mantissa
a = 1;
b = b | (1UL << (EXPONENT_SHIFT - 2));
printf("%f\n", a);

return 0;
}</syntaxhighlight>
On common consumer hardware, the output of the program looks as follows:

<pre>> ./double2
4.000000
1.250000</pre>
If you don’t know why, the Wikipedia article on [https://en.wikipedia.org/wiki/Double-precision_floating-point_format double precision floating point numbers] might be a good starting point for finding an explanation on your own.


=== Doing more weird stuff with aliases ===

As you might have guessed by now, there are very few safeguards in place to prevent us from defining function aliases with different signatures. In combination with other attributes like <code>gnu::packed</code> or <code>gnu::aligned</code> this may be used for tricks like the following:

<syntaxhighlight lang="c">// signatures.c
#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

void f(S s) {
printf("a = %u, b = %u\n", s.a, s.b);
}

[[gnu::alias("f")]] extern void g(uint64_t ab);

int main(int argc, char **argv) {
S s = {2,3};

printf("Calling f: ");
f(s);

printf("Calling g: ");
g(0x0000000200000001UL);

return 0;
}
</syntaxhighlight>
Before showing you what this program does, let us examine it a bit more closely:

* The file begins with the declaration of a struct type <code>S</code> with two members <code>a</code> and <code>b</code> of type <code>uint32_t</code>. The attribute <code>gnu::packed</code> tells the compiler to not insert any padding bytes, so that the layout of any instance of the struct <code>S</code> in memory is exactly as we as C programmers see it: 4 bytes of memory occupied by the member <code>a</code> followed by 4 bytes of memory occupied by the member <code>b</code>.
* The function <code>f</code> takes an instance <code>s</code> of the struct type <code>S</code> and simply prints its members to the standard output.
* What follows is an alias <code>g</code> of <code>f</code> with a different signature. The function <code>g</code> takes a single argument <code>ab</code> of type <code>uint64_t</code>. Being an alias of <code>f</code>, however, any call of <code>g</code> will execute the exact same code that <code>f</code> compiles to. Luckily, values of type <code>uint64_t</code> occupy 8 bytes of memory, which is the exact same amount of memory occupied by instances of the struct type <code>S</code>. The machine code that <code>f</code> compiles to will thus interpret the lower and higher 4 bytes of <code>g</code>’s argument <code>ab</code> as members <code>a</code> and <code>b</code> of <code>f</code>’s argument <code>s</code>, respectively.

Now, let’s see what this program does:

<pre>> ./signatures
Calling f: a = 2, b = 3
Calling g: a = 1, b = 2</pre>
As explained above, the function <code>f</code> indeed interprets the 8 bytes <code>0x0000000200000001UL</code> given as argument to <code>g</code> as an instance of type <code>S</code> with member <code>a</code> being the lower four bytes <code>0x00000001</code> and member <code>b</code> being the upper four bytes <code>0x00000002</code>.

Let me finish this example with a word of warning: Although being great fun, tricks like this one are hightly non-portable as they depend among other things on memory alignment, padding, calling conventions and the concrete hardware that your binary is going to be deployed on. So, <s>if you don’t know exactly what you’re doing</s>, they should never be used in any production code.


=== An invitation ===

If you’ve come this far, there’s not much more I want to tell you for now. Get a cup of coffee, fire up your favourite editor and have some fun with aliases. If you don’t know where to start, let me give you one last hint: One may use the alias attribute for variables of <code>struct</code> type, too. This can be seen in the following program that is merely a slight variation of our previous example of function aliases:

<syntaxhighlight lang="c">#include <stdio.h>
#include <stdint.h>

typedef struct [[gnu::packed]] {
uint32_t a;
uint32_t b;
} S;

S s;
extern uint64_t c [[gnu::alias("s")]];

int main(int argc, char **argv) {
s.b = 0x42;
printf("%lx\n", c);

return 0;
}</syntaxhighlight>
<references />

Main Page

2024-02-19T11:53:11Z

Tobias.columbus: /* Compiler Background */

<languages/>
<translate>


Welcome to the emmtrix Technologies Wiki. As a company with a deep-rooted passion for compilers, we specialize in source-to-source compilers designed to analyze, optimize and transform your code. This Wiki aims to offer detailed, technical background information that complements the tools and resources available on our official website. Here, you'll find in-depth explanations, usage guidelines, and insights into the engineering behind our specialized software solutions. Whether you're a developer or a technically-inclined enthusiast, this space is designed to deepen your understanding of what makes our tools essential for your projects.


=== emmtrix Products ===


* [[emmtrix Studio Release Notes]]
* emmtrix Parallel Studio
* [[emmtrix C++ to C Compiler]]
** [https://online-ecpp2c.emmtrix.com Live C++ to C compiler demo]

</translate>

=== Compiler Background ===

* [[Loop Transformations]]
*[[Demystifying C++]]
*[[The alias Attribute|The alias attribute]]