https://github.com/awl-s/builtin-documentation

builtin documentation. This project showcases the usage of GCC/Clang built-in functions (__builtin_*) for performing low-level operations such as bit counting, memory manipulation, and overflow checking. Examples of function calls with explanations are provided. // Этот проект демонстрирует использование встроенных функций GCC/Clang (__builtin_*)
https://github.com/awl-s/builtin-documentation

arithmetic-overflow bit-manipulation built-in-functions c c-programming clang compiler-optimizations cpp cpp-programming gcc low-level-programming memory-management

Last synced: 3 months ago
JSON representation

builtin documentation. This project showcases the usage of GCC/Clang built-in functions (__builtin_*) for performing low-level operations such as bit counting, memory manipulation, and overflow checking. Examples of function calls with explanations are provided. // Этот проект демонстрирует использование встроенных функций GCC/Clang (__builtin_*)

• Host: GitHub
• URL: https://github.com/awl-s/builtin-documentation
• Owner: Awl-S
• Created: 2024-12-22T04:15:11.000Z (5 months ago)
• Default Branch: main
• Last Pushed: 2024-12-22T04:36:45.000Z (5 months ago)
• Last Synced: 2025-02-21T05:15:41.470Z (3 months ago)
• Topics: arithmetic-overflow, bit-manipulation, built-in-functions, c, c-programming, clang, compiler-optimizations, cpp, cpp-programming, gcc, low-level-programming, memory-management
• Language: C
• Homepage: https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html
• Size: 16.6 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
#### Перевод на русский [README_RU.md](README_RU.md)

# GCC/Clang Built-in Functions Documentation

## Introduction

GCC and Clang compilers provide a set of built-in functions (`__builtin_*`) that allow programmers to directly utilize low-level operations, optimize code, and access processor-specific features. These functions are often mapped to hardware instructions or implemented in an efficient manner by the compiler.

---

## 1. Bit Manipulation Functions

These functions operate on bit-level representations of integers.

### `__builtin_popcount`

- **Description**: Counts the number of set bits (1s) in the binary representation of an `unsigned int`.

- **Parameters**:

  - `unsigned int x`: The input number.

- **Return Value**: The number of 1s in the binary representation of `x`.

### `__builtin_popcountl`

- **Description**: Counts the number of set bits in an `unsigned long`.

- **Parameters**:

  - `unsigned long x`: The input number.

- **Return Value**: The number of 1s in the binary representation of `x`.

### `__builtin_popcountll`

- **Description**: Counts the number of set bits in an `unsigned long long`.

- **Parameters**:

  - `unsigned long long x`: The input number.

- **Return Value**: The number of 1s in the binary representation of `x`.

### `__builtin_ctz`

- **Description**: Counts the number of trailing zeros in an `unsigned int`.

- **Parameters**:

  - `unsigned int x`: The input number.

- **Return Value**: The number of trailing zeros in the binary representation of `x`. Returns undefined if `x` is 0.

### `__builtin_ctzl`

- **Description**: Counts the number of trailing zeros in an `unsigned long`.

- **Parameters**:

  - `unsigned long x`: The input number.

- **Return Value**: The number of trailing zeros in the binary representation of `x`. Returns undefined if `x` is 0.

### `__builtin_ctzll`

- **Description**: Counts the number of trailing zeros in an `unsigned long long`.

- **Parameters**:

  - `unsigned long long x`: The input number.

- **Return Value**: The number of trailing zeros in the binary representation of `x`. Returns undefined if `x` is 0.

### `__builtin_clz`

- **Description**: Counts the number of leading zeros in an `unsigned int`.

- **Parameters**:

  - `unsigned int x`: The input number.

- **Return Value**: The number of leading zeros in the binary representation of `x`. Returns undefined if `x` is 0.

### `__builtin_clzl`

- **Description**: Counts the number of leading zeros in an `unsigned long`.

- **Parameters**:

  - `unsigned long x`: The input number.

- **Return Value**: The number of leading zeros in the binary representation of `x`. Returns undefined if `x` is 0.

### `__builtin_clzll`

- **Description**: Counts the number of leading zeros in an `unsigned long long`.

- **Parameters**:

  - `unsigned long long x`: The input number.

- **Return Value**: The number of leading zeros in the binary representation of `x`. Returns undefined if `x` is 0.

### `__builtin_parity`

- **Description**: Returns the parity of the number of 1s in an `unsigned int`. Returns 1 if the number of 1s is odd, otherwise 0.

- **Parameters**:

  - `unsigned int x`: The input number.

- **Return Value**: `1` if the number of 1s is odd, `0` otherwise.

### `__builtin_parityl`

- **Description**: Returns the parity of the number of 1s in an `unsigned long`.

- **Parameters**:

  - `unsigned long x`: The input number.

- **Return Value**: `1` if the number of 1s is odd, `0` otherwise.

### `__builtin_parityll`

- **Description**: Returns the parity of the number of 1s in an `unsigned long long`.

- **Parameters**:

  - `unsigned long long x`: The input number.

- **Return Value**: `1` if the number of 1s is odd, `0` otherwise.

---

## 2. Arithmetic Overflow Functions

These functions detect overflow conditions during arithmetic operations.

### `__builtin_add_overflow`

- **Description**: Performs addition and checks for overflow.

- **Parameters**:

  - `T x`: The first operand.

  - `T y`: The second operand.

  - `T* result`: Pointer to store the result.

- **Return Value**: Returns `1` if overflow occurred, `0` otherwise.

### `__builtin_sub_overflow`

- **Description**: Performs subtraction and checks for overflow.

- **Parameters**:

  - `T x`: The first operand.

  - `T y`: The second operand.

  - `T* result`: Pointer to store the result.

- **Return Value**: Returns `1` if overflow occurred, `0` otherwise.

### `__builtin_mul_overflow`

- **Description**: Performs multiplication and checks for overflow.

- **Parameters**:

  - `T x`: The first operand.

  - `T y`: The second operand.

  - `T* result`: Pointer to store the result.

- **Return Value**: Returns `1` if overflow occurred, `0` otherwise.

---

## 3. Memory Manipulation Functions

These functions provide efficient ways to manipulate memory blocks.

### `__builtin_memcpy`

- **Description**: Copies a block of memory from the source to the destination.

- **Parameters**:

  - `void* dest`: Destination pointer.

  - `const void* src`: Source pointer.

  - `size_t n`: Number of bytes to copy.

- **Return Value**: Returns a pointer to the destination (`dest`).

### `__builtin_memset`

- **Description**: Fills a block of memory with a specific value.

- **Parameters**:

  - `void* dest`: Pointer to the memory block to fill.

  - `int c`: The value to fill.

  - `size_t n`: Number of bytes to fill.

- **Return Value**: Returns a pointer to the destination (`dest`).

### `__builtin_memmove`

- **Description**: Moves a block of memory from the source to the destination. Handles overlapping memory safely.

- **Parameters**:

  - `void* dest`: Destination pointer.

  - `const void* src`: Source pointer.

  - `size_t n`: Number of bytes to move.

- **Return Value**: Returns a pointer to the destination (`dest`).

---

## 4. Control Flow Optimization

These functions provide hints to the compiler for optimizing control flow.

### `__builtin_expect`

- **Description**: Provides the compiler with branch prediction information.

- **Parameters**:

  - `long exp`: The expression to evaluate.

  - `long c`: The expected value of the expression.

- **Return Value**: Returns the value of `exp`. The compiler optimizes for the assumption that `exp == c`.

---

## 5. Type Checking and Constants

These functions help in type checking and constant evaluation.

### `__builtin_types_compatible_p`

- **Description**: Checks whether two types are compatible.

- **Parameters**:

  - `T1`: The first type.

  - `T2`: The second type.

- **Return Value**: Returns `1` if the types are compatible, otherwise `0`.

### `__builtin_constant_p`

- **Description**: Checks if a value is a compile-time constant.

- **Parameters**:

  - `exp`: The expression to check.

- **Return Value**: Returns `1` if the expression is a compile-time constant, otherwise `0`.

---

## 6. Math and Utility Functions

These functions provide basic mathematical and utility operations.

### `__builtin_abs`

- **Description**: Returns the absolute value of an integer.

- **Parameters**:

  - `int x`: The input integer.

- **Return Value**: The absolute value of `x`.

### `__builtin_labs`

- **Description**: Returns the absolute value of a `long` integer.

- **Parameters**:

  - `long x`: The input integer.

- **Return Value**: The absolute value of `x`.

### `__builtin_llabs`

- **Description**: Returns the absolute value of a `long long` integer.

- **Parameters**:

  - `long long x`: The input integer.

- **Return Value**: The absolute value of `x`.

---

## Notes

1. These built-in functions are platform-specific and optimized by the compiler.

2. Some functions, such as `__builtin_expect`, may not provide runtime benefits on all platforms but assist in compiler optimization.

3. Functions like `__builtin_popcount` may leverage hardware instructions (e.g., POPCNT) if supported by the CPU.