6.34.1 Общие атрибуты переменных

Следующие атрибуты поддерживаются на большинстве целевых платформ.

alias ("target")

Атрибут переменной alias заставляет объявление быть выведенным как псевдоним для другого символа, известного как цель псевдонима. За исключением квалификаторов верхнего уровня, цель псевдонима должна иметь тот же тип, что и псевдоним. Например, следующее

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

определяет var_alias как псевдоним для переменной var_target.

Ошибка возникает, если цель псевдонима не определена в том же модуле трансляции, что и псевдоним.

Обратите внимание, что в отсутствие атрибута GCC предполагает, что различные объявления с внешней ссылкой обозначают разные объекты. Использование как псевдонима, так и цели псевдонима для доступа к одному объекту неопределено в модуле трансляции без объявления псевдонима с атрибутом.

Данный атрибут требует поддержки ассемблера и объектных файлов, и может быть недоступен на всех целевых платформах.

aligned

aligned (alignment)

Атрибут aligned задаёт минимальное выравнивание для переменной или поля структуры, измеряемое в байтах. При указании alignment должно быть целое число, являющееся степенью двойки. Отсутствие аргумента alignment подразумевает максимальное выравнивание для целевой платформы, которое часто, но не всегда, составляет 8 или 16 байтов.

Например, объявление:

int x __attribute__ ((aligned (16))) = 0;

приводит к тому, что компилятор выделяет глобальную переменную x на границе 16 байт. На 68040 это можно использовать в сочетании с выражением asm, чтобы получить доступ к инструкции move16, которая требует 16-байтового выравнивания операндов.

Вы также можете указать выравнивание полей структуры. Например, для создания пары с выравниванием в два слова int, можно записать:

struct foo { int x[2] __attribute__ ((aligned (8))); };

Это альтернатива созданию объединения с членом double, что принудительно выравнивает объединение к двойному слову.

Как и в предыдущих примерах, вы можете явно указать выравнивание (в байтах), которое вы хотите использовать для данной переменной или поля структуры. В качестве альтернативы, вы можете опустить множитель выравнивания и просто попросить компилятор выровнять переменную или поле до значения по умолчанию для целевой архитектуры, для которой вы компилируете. Выравнивание по умолчанию достаточно для всех скалярных типов, но может быть недостаточным для всех векторных типов на целевой платформе, которая поддерживает векторные операции. Выравнивание по умолчанию фиксировано для конкретной целевой ABI.

GCC также предоставляет специфичную для платформы макрос __BIGGEST_ALIGNMENT__, который представляет собой наибольшее выравнивание, когда-либо используемое для любого типа данных на целевой машине, для которой вы компилируете. Например, вы можете записать:

short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__)));

Компилятор автоматически устанавливает выравнивание объявленной переменной или поля до __BIGGEST_ALIGNMENT__. Это часто повышает эффективность операций копирования, так как компилятор может использовать инструкции, копирующие большие блоки памяти при копировании в или из переменных или полей, которые вы выровняли таким образом. Обратите внимание, что значение __BIGGEST_ALIGNMENT__ может меняться в зависимости от параметров командной строки.

При использовании на структуре или члене структуры, атрибут aligned может только увеличить выравнивание; для уменьшения его необходимо указать атрибут packed. При использовании в составе typedef атрибут aligned может как увеличивать, так и уменьшать выравнивание, а указание атрибута packed генерирует предупреждение.

Обратите внимание, что эффективность атрибутов aligned для статических переменных может быть ограничена внутренними ограничениями системного линковщика и/или формата объектных файлов. На некоторых системах линковщик может только организовать выравнивание переменных до определенного максимального выравнивания. (Для некоторых линковщиков максимальное поддерживаемое выравнивание может быть очень маленьким.) Если ваш линковщик может выравнивать переменные только до максимального выравнивания в 8 байт, то указание aligned(16) в __attribute__ всё ещё обеспечит только 8-байтовое выравнивание. Для получения дополнительной информации см. документацию вашего линковщика.

Переменные стека не затрагиваются ограничениями линковщика; GCC может правильно выровнять их на любой целевой платформе.

Атрибут aligned также может использоваться для функций (см. Общие атрибуты функций).

alloc_size (position)

alloc_size (position-1, position-2)

Атрибут переменной alloc_size может применяться к объявлению указателя на функцию, возвращающую указатель и принимающую по крайней мере один аргумент целого типа. Он указывает, что возвращаемый указатель указывает на объект, размер которого задаётся аргументом функции в позиции position, или произведением аргументов в позициях position-1 и position-2. Значимые размеры – положительные значения, меньшие PTRDIFF_MAX. Другие размеры будут диагностированы при обнаружении. GCC использует эту информацию для улучшения результатов __builtin_object_size.

Например, следующие объявления

typedef __attribute__ ((alloc_size (1, 2))) void*
  (*calloc_ptr) (size_t, size_t);
typedef __attribute__ ((alloc_size (1))) void*
  (*malloc_ptr) (size_t);

указывают, что calloc_ptr является указателем на функцию, которая, подобно стандартной C-функции calloc, возвращает объект, размер которого задаётся произведением аргументов 1 и 2, и аналогично, что malloc_ptr, подобно стандартной C-функции malloc, возвращает объект, размер которого задаётся первым аргументом функции.

cleanup (cleanup_function)

Атрибут cleanup запускает функцию, когда переменная выходит из области видимости. Этот атрибут может применяться только к переменным в области видимости автофункций; он не может применяться к параметрам или переменным со статическим сроком хранения. Функция должна принимать один параметр, указатель на тип, совместимый с переменной. Значение возврата функции (если таковое имеется) игнорируется.

Когда несколько переменных в одной области видимости имеют атрибуты cleanup, при выходе из области видимости их связанные функции очистки выполняются в обратном порядке определения (последняя определённая, первая очистка).

Если включен -fexceptions, то cleanup_function выполняется во время разворачивания стека, происходящего во время обработки исключения. Обратите внимание, что атрибут cleanup не позволяет перехватить исключение, только выполнить действие. Неопределено, что произойдёт, если cleanup_function не вернётся нормально.

common

nocommon

Атрибут common просит GCC поместить переменную в «общую» область памяти. Атрибут nocommon просит сделать обратное — выделить для неё место непосредственно.

Эти атрибуты переопределяют значение, выбранное по умолчанию флагами -fno-common и -fcommon соответственно.

copy

copy (variable)

Атрибут copy применяет набор атрибутов, с которыми была объявлена переменная, к объявлению переменной, к которой применяется атрибут. Атрибут предназначен для библиотек, которые определяют псевдонимы, которые ожидаются для указания того же набора атрибутов, что и алиасированные символы. Атрибут copy может использоваться с переменными, функциями или типами. Однако, вид символа, к которому применяется атрибут (переменная или функция), должен совпадать с видом символа, на который ссылается аргумент. Атрибут copy копирует только синтаксические и семантические атрибуты, но не атрибуты, которые влияют на связь или видимость символа, такие как alias, visibility, или weak. Атрибут deprecated также не копируется. См. Общие атрибуты функций. См. Общие атрибуты типов.

deprecated

deprecated (msg)

Атрибут deprecated приводит к появлению предупреждения, если переменная используется где-либо в исходном файле. Это полезно для выявления переменных, которые предполагается удалить в будущей версии программы. Предупреждение также содержит расположение объявления устаревшей переменной, чтобы пользователи могли легко найти дополнительную информацию о причинах устаревания переменной или о том, что следует делать вместо этого. Обратите внимание, что предупреждение появляется только при использовании:

extern int old_var __attribute__ ((deprecated));
extern int old_var;
int new_fn () { return old_var; }

приводит к появлению предупреждения на строке 3, но не на строке 2. Необязательный аргумент msg, который должен быть строкой, выводится в предупреждении, если он присутствует.

Атрибут deprecated также может использоваться для функций и типов (см. Общие атрибуты функций, см. Общие атрибуты типов).

Сообщение, прикрепленное к атрибуту, зависит от настроек опции -fmessage-length.

mode (mode)

Этот атрибут задаёт тип данных для объявления — любой тип, соответствующий режиму mode. Это позволяет запросить целочисленный или с плавающей запятой тип в соответствии с его шириной.

См. Режимы машины в GNU Compiler Collection (GCC) Internals для списка возможных ключевых слов для mode. Вы также можете указать режим byte или __byte__ для указания режима, соответствующего целому числу в один байт, word или __word__ для режима целого числа в одно слово, и pointer или __pointer__ для режима, используемого для представления указателей.

no_icf

Этот атрибут переменной предотвращает объединение переменной с другой эквивалентной переменной.

noinit

Любые данные с атрибутом noinit не будут инициализированы кодом запуска C-времени выполнения или загрузчиком программы. Инициализация данных таким образом может сократить время запуска программы.

Этот атрибут специфичен для целевых платформ ELF и зависит от скрипта линковщика для размещения разделов с префиксом .noinit в нужном месте.

nonstring

Атрибут переменной nonstring указывает, что объявление объекта или члена типа массив из char, signed char, или unsigned char, или указатель на такой тип, предназначен для хранения массивов символов, которые не обязательно содержат завершающий символ NUL. Это полезно для обнаружения использования таких массивов или указателей с функциями, которые ожидают NUL-завершённые строки и для предотвращения предупреждений, когда такой массив или указатель используется в качестве аргумента функции обработки ограниченных строк, такой как strncpy. Например, без атрибута GCC выдаст предупреждение для вызова strncpy ниже, потому что он может обрезать копирование без добавления завершающего символа NUL. Использование атрибута позволяет подавить предупреждение. Однако, когда массив объявлен с атрибутом, вызов strlen диагностируется, потому что, когда массив не содержит NUL-завершённую строку, вызов является неопределённым. Для копирования, сравнения или поиска нестроковых массивов символов используйте функции memcpy, memcmp, memchr и другие функции, которые работают с массивами байтов. Кроме того, вызов strnlen и strndup с такими массивами безопасен при условии указания соответствующего ограничения и не диагностируется.

struct Data
{
  char name [32] __attribute__ ((nonstring));
};

int f (struct Data *pd, const char *s)
{
  strncpy (pd->name, s, sizeof pd->name);
  …
  return strlen (pd->name);   // unsafe, gets a warning
}

objc_nullability (nullability kind) (Objective-C and Objective-C++ only)

Этот атрибут применяется только к указателям переменных. Он позволяет помечать указатель одним из четырёх возможных значений, описывающих условия, при которых указатель может иметь nil значение. В большинстве случаев атрибут предназначен для внутреннего представления для нуллирования свойств и методов (указанных ключевыми словами языка); использование его непосредственно не рекомендуется.

Когда вид нуллирования — "unspecified" или 0, ничего не известно о условиях, при которых указатель может быть nil. Детализация этого состояния служит для предотвращения ложных срабатываний в диагностике.

Когда вид нуллирования — "nonnull" или 1, указатель не имеет смысла, если он nil, и, следовательно, компилятор свободен выдать диагностику, если можно определить, что значение будет nil.

Когда вид нуллирования — "nullable" или 2, указатель может быть nil и иметь смысл как таковой.

Когда вид нуллирования — "resettable" или 3 (используется только в контексте списков атрибутов свойств), это описывает случай, когда установщик свойства может принять значение nil (что, возможно, приводит к сбросу свойства каким-либо образом к значению по умолчанию), но при этом получатель свойства никогда не вернёт nil значение.

packed

Атрибут packed указывает, что член структуры должен иметь наименьший возможный выравнивание — один бит для побитового поля и один байт в противном случае, если с помощью атрибута aligned не указано большее значение. Атрибут не применяется к объектам, не являющимся членами.

Например, в структуре ниже, массив членов x упакован так, что он сразу следует за a без промежуточного заполнения:

struct foo
{
  char a;
  int x[2] __attribute__ ((packed));
};

Примечание: Серии GCC 4.1, 4.2 и 4.3 игнорируют атрибут packed в побитовых полях типа char. Это было исправлено в GCC 4.4, но изменение может привести к различиям в структуре расположения. См. документацию по -Wpacked-bitfield-compat для получения дополнительной информации.

persistent

Любые данные с атрибутом persistent не будут инициализированы кодом запуска C-среды выполнения, а будут инициализированы загрузчиком программы. Это позволяет значению переменной «сохраняться» между сбросами процессора.

Этот атрибут специфичен для целей ELF и зависит от скрипта компоновщика для размещения разделов с префиксом .persistent в нужном месте. В частности, требуется какой-либо вид энергонезависимой, записываемой памяти.

section ("section-name")

Обычно компилятор помещает сгенерированные им объекты в разделы, такие как data и bss. Однако иногда вам нужны дополнительные разделы или вам нужно, чтобы определённые переменные появлялись в специальных разделах, например, для отображения на специальном оборудовании. Атрибут section указывает, что переменная (или функция) находится в определённом разделе. Например, эта небольшая программа использует несколько определённых имён разделов:

struct duart a __attribute__ ((section ("DUART_A"))) = { 0 };
struct duart b __attribute__ ((section ("DUART_B"))) = { 0 };
char stack[10000] __attribute__ ((section ("STACK"))) = { 0 };
int init_data __attribute__ ((section ("INITDATA")));

main()
{
  /* Initialize stack pointer */
  init_sp (stack + sizeof (stack));

  /* Initialize initialized data */
  memcpy (&init_data, &data, &edata - &data);

  /* Turn on the serial ports */
  init_duart (&a);
  init_duart (&b);
}

Используйте атрибут section со глобальными переменными, а не локальными, как показано в примере.

Вы можете использовать атрибут section с инициализированными или неинициализированными глобальными переменными, но компоновщик требует, чтобы каждый объект был определён один раз, за исключением того, что неинициализированные переменные временно помещаются в раздел common (или bss) и могут быть многократно «определены». Использование атрибута section изменяет раздел, в который попадает переменная, и может привести к ошибке компоновщика, если у неинициализированной переменной есть несколько определений. Вы можете принудительно инициализировать переменную с помощью флага -fno-common или атрибута nocommon.

Некоторые форматы файлов не поддерживают произвольные разделы, поэтому атрибут section недоступен на всех платформах. Если вам нужно отобразить всё содержимое модуля в определённый раздел, рассмотрите использование возможностей компоновщика вместо этого.

strict_flex_array (level)

Атрибут strict_flex_array должен быть присоединён к последнему полю массива структуры. Он контролирует, когда следует рассматривать последнюю поле массива структуры как гибкий член массива для доступа к элементам такого массива. уровень должен быть целым числом от 0 до 3.

уровень=0 — наименее строгий уровень, все последующие массивы структур рассматриваются как гибкие члены массивов. уровень=3 — самый строгий уровень, только когда конечный массив объявлен как гибкий член массива по стандарту C99 и далее (‘[]’), он рассматривается как гибкий член массива.

Между 0 и 3 есть ещё два уровня, которые предоставляются для поддержки старых кодов, использующих расширение нулевой длины массива GCC (‘[0]’) или одномерный массив как гибкий член массива (‘[1]’). Когда уровень равен 1, конечный массив рассматривается как гибкий член массива, когда он объявлен как ‘[]’, ‘[0]’ или ‘[1]’; когда уровень равен 2, конечный массив рассматривается как гибкий член массива, когда он объявлен как ‘[]’ или ‘[0]’.

Этот атрибут может использоваться с опцией командной строки -fstrict-flex-arrays или без неё. Когда атрибут и опция присутствуют одновременно, уровень строгости для конкретного поля конечного массива определяется атрибутом.

Атрибут strict_flex_array взаимодействует с опцией -Wstrict-flex-arrays. См. Опции запроса или подавления предупреждений для получения дополнительной информации.

tls_model ("tls_model")

Атрибут tls_model устанавливает модель локального хранения потока (см. Локальное хранилище потоков) для определённой __thread переменной, переопределяя переключатель опции командной строки -ftls-model= на уровне каждой переменной. Аргумент tls_model должен быть одним из global-dynamic, local-dynamic, initial-exec или local-exec.

Не все цели поддерживают этот атрибут.

unavailable

unavailable (msg)

Атрибут unavailable указывает, что переменная, помеченная таким образом, недоступна, если она используется где-либо в файле исходного кода. Он работает аналогично атрибуту deprecated, за исключением того, что компилятор выдает ошибку вместо предупреждения.

Ожидается, что элементы, помеченные как deprecated, в конечном итоге будут удалены из интерфейсов, а затем станут недоступными. Этот атрибут позволяет соответствующим образом помечать их.

Атрибут unavailable также может использоваться для функций и типов (см. Общие атрибуты функций, см. Общие атрибуты типов).

unused

Этот атрибут, прикреплённый к переменной или члену структуры, означает, что переменная или член, возможно, не используется. GCC не выводит предупреждение для этой переменной или члена.

used

Этот атрибут, прикреплённый к переменной со статическим хранением, означает, что переменная должна быть выведена даже если кажется, что на неё нет ссылок.

При применении к статическому члену данных шаблона C++, атрибут также означает, что член экземпляризуется, если сам класс экземпляризуется.

retain

Для целей ELF, которые поддерживают GNU или FreeBSD OSABIs, этот атрибут сохранит переменную от сбора мусора компоновщиком. Для поддержки этого поведения переменные, которые не были размещены в определённых разделах (например, с помощью атрибута section, или опции -fdata-sections), будут размещены в новых, уникальных разделах.

Эта дополнительная функция требует Binutils версии 2.36 или более поздней.

uninitialized

Этот атрибут, прикреплённый к переменной с автоматическим хранением, означает, что компилятор не должен автоматически инициализировать переменную, когда присутствует опция -ftrivial-auto-var-init.

С опцией -ftrivial-auto-var-init, все автоматические переменные, которые не имеют явных инициализаторов, будут инициализированы компилятором. Эти дополнительные инициализации компилятора могут привести к накладным расходам во время выполнения, иногда значительно. Этот атрибут может использоваться для маркировки некоторых переменных, чтобы исключить их из такой автоматической инициализации, чтобы уменьшить накладные расходы во время выполнения.

Этот атрибут не оказывает никакого влияния, когда опция -ftrivial-auto-var-init отсутствует.

vector_size (bytes)

Этот атрибут задаёт размер вектора для типа объявленной переменной, измеряемый в байтах. Тип, к которому он применяется, известен как базовый тип. Аргумент bytes должен быть положительной степенью двойки, кратной размеру базового типа. Например, объявление:

int foo __attribute__ ((vector_size (16)));

приводит к тому, что компилятор устанавливает режим для foo, равный 16 байтам, разделённым на блоки размером int. Предполагая 32-битный int, тип foo представляет собой вектор из четырёх блоков по четыре байта каждый, и соответствующий режим foo равен V4SI. Подробности работы с векторами через встроенные функции см. в разделе Использование векторных инструкций через встроенные функции.

Этот атрибут применим только к целочисленным и плавающим скалярам, хотя массивы, указатели и значения возвращаемых функций допускаются в сочетании с этим конструктом.

Агрегаты с этим атрибутом недопустимы, даже если они имеют тот же размер, что и соответствующий скаляр. Например, объявление:

struct S { int a; };
struct S  __attribute__ ((vector_size (16))) foo;

является недопустимым, даже если размер структуры совпадает с размером int.

visibility ("visibility_type")

Этот атрибут влияет на связь объявления, к которому он прикреплён. Атрибут visibility описан в Общие атрибуты функций.

warn_if_not_aligned (alignment)

Этот атрибут задаёт порог для поля структуры, измеряемый в байтах. Если выравнивание поля структуры ниже порога, будет выведено предупреждение. Например, объявление:

struct foo
{
  int i1;
  int i2;
  unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
};

приводит к тому, что компилятор выдаёт предупреждение о struct foo, например, «предупреждение: выравнивание 8 для 'struct foo' меньше 16». Компилятор также выдает предупреждение, например, «предупреждение: смещение 'x' 8 в 'struct foo' не выровнено по 16», когда поле структуры имеет невыровненное смещение:

struct __attribute__ ((aligned (16))) foo
{
  int i1;
  int i2;
  unsigned long long x __attribute__ ((warn_if_not_aligned (16)));
};

Это предупреждение можно отключить с помощью -Wno-if-not-aligned. Атрибут warn_if_not_aligned также можно использовать для типов (см. Общие атрибуты типов.)

weak

Атрибут weak описан в Общие атрибуты функций.