title: posix_spawn(3)

summary: порождает процесс

text:
# posix_spawn(3)

## ИМЯ
posix_spawn, posix_spawnp - порождает процесс

## ОБЗОР

```
#include <spawn.h>
```

```
int posix_spawn(pid_t *pid, const char *path,
                const posix_spawn_file_actions_t *file_actions,
                const posix_spawnattr_t *attrp,
                char *const argv[], char *const envp[]);
```

```
int posix_spawnp(pid_t *pid, const char *file,
                const posix_spawn_file_actions_t *file_actions,
                const posix_spawnattr_t *attrp,
                char *const argv[], char *const envp[]);
```

## ОПИСАНИЕ
Функции posix_spawn() и posix_spawnp() используются для создания новых дочерних процессов, которые выполняют указываемый файл. Эти функции были определены в POSIX для стандартизации метода создания новых процессов на машинах, у которых нет возможности поддержки системного вызова fork(2). К таким машинах, обычно, относятся встраиваемые системы без поддержки MMU.

Функции posix_spawn() и posix_spawnp() предоставляют комбинацию возможностей fork(2) и exec(3) с некоторыми необязательными обслуживающими действиями в дочернем процессе перед exec(3). Эти функции не служат заменой системных вызовов fork(2) и execve(2). Фактически, они предоставляют только часть функций системных вызовов.

Единственным отличием между posix_spawnp() и posix_spawnp() является способ, которым в них указывается исполняемый дочерним процессом файл. В posix_spawn() исполняемый файл задаётся в виде пути (которое может быть абсолютным или относительным). В posix_spawnp() исполняемый файл задаётся в виде имени файла; система ищет этот файл в списке каталогов, указанных в PATH (также, как это делает execvp(3)). Кроме данного отличия далее на этой странице всё описание posix_spawn() также относится и к posix_spawnp().

Остальные аргументы функций:

- Аргумент pid указывает на буфер, в котором возвращается ID нового дочернего процесса.

- Аргумент file_actions указывает на объект файловых действий при создании, в котором задаются действия с файлом, выполняемые в потомке между шагами fork(2) и exec(3). Данный объект инициализируется и заполняется перед вызовом posix_spawn() с помощью функций posix_spawn_file_actions_init(3) и posix_spawn_file_actions_*().

- Аргумент attrp указывает на объект атрибутов, в котором задаются различные атрибуты создаваемого дочернего процесса. Данный объект инициализируется и заполняется перед вызовом posix_spawn() с помощью функций posix_spawnattr_init(3) и posix_spawnattr_*().

- В аргументах argv и envp задаётся список аргументов и окружения для программы, выполняемой в дочернем процессе, как для execve(2).

Далее функции описаны в виде трёх ступенчатого процесса: шаг fork(), шаг перед exec() (выполняется в потомке) и шаг exec() (выполняется в потомке).

### Шаг fork()
Функция posix_spawn() начинает работу с вызова fork(2) или, возможно, vfork(2) (смотрите ниже).

PID нового дочернего процесса помещается в *pid. После этого функция posix_spawn() возвращает управление родительскому процессу.

Соответственно, родитель может использовать один из системных вызовов, описанных в wait(2), для проверки состояния дочернего процесса. Если потомок завершится с ошибкой в любом из служебных шагов, описанных далее, или возникнет ошибка при выполнении желаемого файла, то он завершит работу с кодом состояния 127.

Дочерний процесс создаётся с помощью vfork(2), а не fork(2) в любом из следующих случаев:

- элемент spawn-flags объекта атрибутов, на который указывает attrp, содержит определённый в GNU флаг POSIX_SPAWN_USEVFORK; или

- file_actions равно NULL и элемент spawn-flags объекта атрибутов, на который указывает attrp, не содержит POSIX_SPAWN_SETSIGMASK, POSIX_SPAWN_SETSIGDEF, POSIX_SPAWN_SETSCHEDPARAM, POSIX_SPAWN_SETSCHEDULER, POSIX_SPAWN_SETPGROUP или POSIX_SPAWN_RESETIDS.

Иначе говоря, vfork(2) используется, если это запросил вызывающий или не нужна очистка в потомке перед выполнением exec(3) запрашиваемого файла.

### Шаг перед exec(): служебные действия
Между fork(2) и exec(3) дочерний процесс может выполнить набор служебных действий. Функции posix_spawn() и posix_spawnp() поддерживают маленький, хорошо спроектированный набор системных задач, которые дочерний процесс может выполнить перед запуском исполняемого файла. Эти операции управляются объектом атрибутов, на который указывает attrp и объект файловых действий, на который указывает file_actions. В потомке обработка выполняются в следующей последовательности:

1.

Действия с атрибутами процесса: маска сигналов, обработчики сигналов по умолчанию, алгоритм планирования и параметры, ID группы процесса, эффективного пользователя и группы изменяются согласно объекту атрибутов, на который указывает attrp.

2.

Файловые действия, указываемые в аргументе file_actions, выполняются в порядке их определения вызовами функций posix_spawn_file_actions_add*().

3.

Закрываются файловые дескрипторы, имеющие флаг FD_CLOEXEC.

Все атрибуты процесса-потомка, отличные от атрибутов в объекте, на который указывает attrp и файловые действия в объекте, на который указывает file_actions, будут изменены как если бы потомок создавался с помощью fork(2) и выполнял программу с помощью execve(2).

Действия атрибутов процесса определяются атрибутами объекта, на который указывает attrp. Атрибут spawn-flags (устанавливается с помощью posix_spawnattr_setflags(3)) управляет общими действиями, а остальные атрибуты объекта хранят значения, которые будут использованы в этих действиях.

Влияние флагов, которые могут быть указаны в spawn-flags:

POSIX_SPAWN_SETSIGMASK

Назначить маску сигналов равной набору сигналов, определённой в атрибуте spawn-sigmask объекта, на который указывает attrp. Если не установлен флаг POSIX_SPAWN_SETSIGMASK, то потомок наследует маску сигналов родителя.

POSIX_SPAWN_SETSIGDEF

Сбрасывает обработчики всех сигналов в наборе, заданном в атрибуте spawn-sigdefault объекта, на который указывает attrp, в значения по умолчанию. О том, что происходит с обработчиками сигналов не указанных в атрибуте spawn-sigdefault или когда не указан POSIX_SPAWN_SETSIGDEF, смотрите execve(2).

POSIX_SPAWN_SETSCHEDPARAM

Если этот флаг установлен, а POSIX_SPAWN_SETSCHEDULER нет, то изменяет параметры планирования на значения, указанные в атрибуте spawn-schedparam объекта, на который указывает attrp.

POSIX_SPAWN_SETSCHEDULER

Назначает алгоритм планирования и параметры потомка:

- Алгоритму планирования присваивается значение, указанное в атрибуте spawn-schedpolicy объекта, на который указывает attrp.

- Параметрам планирования присваивается значение, указанное в атрибуте spawn-schedparam объекта, на который указывает attrp (но смотрите ДЕФЕКТЫ).

Если не указаны флаги POSIX_SPAWN_SETSCHEDPARAM и POSIX_SPAWN_SETSCHEDPOLICY, то потомок наследует соответствующие атрибуты планирования от родителя.

POSIX_SPAWN_RESETIDS

Если этот флаг установлен, то сбрасываются эффективный UID и GID в реальный UID и GID родительского процесса. Если флаг не установлен, то потомок сохраняет эффективный UID и GID родителя. В любом случае, если биты прав set-user-ID и set-group-ID включены на исполняемом файле, то это заменяет значения эффективного UID и GID (смотрите execve(2)).

POSIX_SPAWN_SETPGROUP

Назначает группе процесса значение, указанное в атрибуте spawn-pgroup объекта, на который указывает attrp. Если атрибут spawn-pgroup равен 0, то ID группы потомка становится равным его ID процесса. Если флаг POSIX_SPAWN_SETPGROUP не установлен, то потомок наследует ID группы процесса родителя.

Если attrp равно NULL, то выполняются действия по умолчанию, которые описаны выше по каждому флагу.

Аргумент file_actions задаёт последовательность файловых операций, которые выполняются в дочернем процессе после общей обработки, описанной выше, и перед выполнением exec(3). Если file_actions равно NULL, то никаких специальных действий не производится и выполняются стандартные действия exec(3) — файловые дескрипторы, открытые до выполнения exec, остаются открытыми и в новом процессе, за исключением тех, у которых установлен флаг FD_CLOEXEC. Файловые блокировки остаются как были.

Если file_actions не равно NULL, то в нём содержится упорядоченный набор запросов open(2), close(2) и dup2(2) на файлы. Эти запросы добавляются в file_actions с помощью posix_spawn_file_actions_addopen(3), posix_spawn_file_actions_addclose(3) и posix_spawn_file_actions_adddup2(3). Запрашиваемые операции выполняются в порядке их добавления в file_actions.

Если какая-либо обслуживающая операция завершается с ошибкой, (из-за переданных некорректных значений или по другим причинам, из-за которых обработка сигналов, планирование процесса, функции изменения ID группы процесса и операции с файловыми дескрипторами завершается с ошибкой), дочерний процесс завершается с кодом выхода 127.

### Шаг exec()
После того как потомок создан (fork) и выполнены все запрошенные шаги до exec, потомок выполняет запуск запрошенного исполняемого файла.

Дочерний процесс берёт своё окружение из аргумента envp, которое рассматривается также как если бы оно передавалось в execve(2). Аргументы созданного процесса выбираются из аргумента argv, который обрабатывается также как для execve(2).

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном завершении posix_spawn() и posix_spawnp() помещают PID дочернего процесса в pid и возвращают 0. Если перед или во время fork(2) возникла ошибка, то потомок не создаётся, содержимое *pid неопределенно и функции возвращают номер ошибки (описано далее).

Даже когда эти функции выполняются без ошибок, дочерний процесс всё ещё может завершиться с ошибкой по многим причинам, касающимся инициализации до exec(). Также, может завершиться ошибкой и exec(3). Во всех этих случаях дочерний процесс завершается с кодом ошибки 127.

## ОШИБКИ
Функции posix_spawn() и posix_spawnp() завершаются с ошибкой, только из-за ошибок в используемых вызовах fork(2) и vfork(2); в этих случаях эти функции возвращают номер ошибки, который может быть одним из описанных в fork(2) или vfork(2).

Также, эти функции завершаются с ошибкой если:

ENOSYS

Функции не поддерживаются в этой системе.

## ВЕРСИИ
Функции posix_spawn() и posix_spawnp() доступны в glibc начиная с версии 2.2.

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Обслуживающие действия в потомке управляются объектами, на который указывает attrp (для не файловых действий) и file_actions. В описании POSIX типы данных posix_spawnattr_t и posix_spawn_file_actions_t указываются как объекты, а их элементам не даны имена. Переносимые программы должны инициализировать эти объекты с только помощью функций, определённых в POSIX (другими словами, хотя эти объекты могут быть реализованы как структуры с полями, в переносимых программах нельзя привязываться к такой реализации).

В POSIX не определено вызывать ли обработчики fork, установленные с помощью pthread_atfork(3), при вызове posix_spawn(). В glibc обработчики fork вызываются только, если потомок создан с помощью fork(2).

Не существует функции «posix_fspawn» (т. е., функции типа posix_spawn(), которая вызывала бы fexecve(3) вместо execve(2)). Однако, подобное поведение можно получить указав аргумент path как один из файлов в каталоге /proc/self/fd вызывающего.

## ДЕФЕКТЫ
В POSIX.1 указано, что когда в spawn-flags определён POSIX_SPAWN_SETSCHEDULER, флаг POSIX_SPAWN_SETSCHEDPARAM (если есть) игнорируется. Однако до glibc 2.14 вызов posix_spawn() завершался с ошибкой, если POSIX_SPAWN_SETSCHEDULER был указан, а POSIX_SPAWN_SETSCHEDPARAM отсутствовал.

## ПРИМЕР
Представленная далее программа показывает использование различных функций программного интерфейса POSIX для создания процессов. Она принимает атрибуты из командной строки, которые позволяют задать файловые действия и атрибуты объектов при создании. В остальных аргументах командной строки задаются имя исполняемого файла и аргументы командной строки для программы, исполняемой в потомке.

Здесь для исполнения в потомке указана команда date(1) и вызов posix_spawn() не использует каких-либо файловых действий и атрибутов объекта.

```
$ ./a.out date
PID потомка: 7634
Tue Feb  1 19:47:50 CEST 2011
Состояние потомка: завершился, состояние=0
```

Здесь параметром командной строки -c передаётся объект файловых действий, которые закрывают стандартный вывод в потомке. В результате этого date(1) завершается с ошибкой, когда пытается выполнить вывод данных и завершается с кодом состояния 1.

```
$ ./a.out -c date
PID потомка: 7636
date: write error: Bad file descriptor
Состояние потомка: завершился, состояние=1
```

Здесь используется параметр командной строки -s для создания объекта атрибутов, который используется для блокировки всех сигналов (блокируемых) в потомке. В результате этого попытка убить потомка сигналом по умолчанию (т. е., SIGTERM) с помощью kill(1) завершается ошибкой, так как этот сигнал заблокирован. Теперь, чтобы убить потомка, требуется сигнал SIGKILL (SIGKILL невозможно заблокировать).

```
$ ./a.out -s sleep 60 &
[1] 7637
$ PID потомка: 7638
$ kill 7638
$ kill -KILL 7638
$ Состояние потомка: убит по сигналу 9
[1]+  Done                    ./a.out -s sleep 60
```

Когда мы пытаемся выполнить в потомке несуществующую команду, exec(3) завершается с ошибкой и потомок завершается с кодом 127.

```
$ ./a.out xxxxx
PID потомка: 10190
Состояние потомка: завершился, состояние=127
```

### Исходный код программы

```
#include <spawn.h>
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <string.h>
#include <wait.h>
#include <errno.h>
#define errExit(msg)    do { perror(msg); \

                             exit(EXIT_FAILURE); } while (0)
#define errExitEN(en, msg) \

                        do { errno = en; perror(msg); \

                             exit(EXIT_FAILURE); } while (0)
char **environ;
int
main(int argc, char *argv[])
{

    pid_t child_pid;

    int s, opt, status;

    sigset_t mask;

    posix_spawnattr_t attr;

    posix_spawnattr_t *attrp;

    posix_spawn_file_actions_t file_actions;

    posix_spawn_file_actions_t *file_actionsp;

    /* разбор параметров командной строки, которые можно использовать

       в потомке в качестве объекта атрибутов и файловых действий */

    attrp = NULL;

    file_actionsp = NULL;

    while ((opt = getopt(argc, argv, "sc")) != -1) {

        switch (opt) {

        case 'c':       /* -c: закрыть стандартный вывод в потомке */

            /* создаём объект файловых действий и добавляем в него

               действие «закрыть» */

            s = posix_spawn_file_actions_init(&file_actions);

            if (s != 0)

                errExitEN(s, "posix_spawn_file_actions_init");

            s = posix_spawn_file_actions_addclose(&file_actions,

                                                  STDOUT_FILENO);

            if (s != 0)

                errExitEN(s, "posix_spawn_file_actions_addclose");

            file_actionsp = &file_actions;

            break;

        case 's':       /* -s: блокировать все сигналы в потомке */

            /* создаём объект атрибутов и добавляем в него действие

               «назначения сигнальной маски» */

            s = posix_spawnattr_init(&attr);

            if (s != 0)

                errExitEN(s, "posix_spawnattr_init");

            s = posix_spawnattr_setflags(&attr, POSIX_SPAWN_SETSIGMASK);

            if (s != 0)

                errExitEN(s, "posix_spawnattr_setflags");

            sigfillset(&mask);

            s = posix_spawnattr_setsigmask(&attr, &mask);

            if (s != 0)

                errExitEN(s, "posix_spawnattr_setsigmask");

            attrp = &attr;

            break;

        }

    }

    /* Порождение потомка. Имя исполняемой программы и аргументы

       командной строки берутся из аргументов командной строки

       этой программы. Окружение исполняемой программы в потомке

       делается таким же как у родителя. */

    s = posix_spawnp(&child_pid, argv[optind], file_actionsp, attrp,

                     &argv[optind], environ);

    if (s != 0)

        errExitEN(s, "posix_spawn");

    /* уничтожаем все объекты, которые мы создали ранее */

    if (attrp != NULL) {

        s = posix_spawnattr_destroy(attrp);

        if (s != 0)

            errExitEN(s, "posix_spawnattr_destroy");

    }

    if (file_actionsp != NULL) {

        s = posix_spawn_file_actions_destroy(file_actionsp);

        if (s != 0)

            errExitEN(s, "posix_spawn_file_actions_destroy");

    }

    printf("PID потомка: %ld\n", (long) child_pid);

    /* отслеживаем состояние потомка до его завершения */

    do {

        s = waitpid(child_pid, &status, WUNTRACED | WCONTINUED);

        if (s == -1)

            errExit("waitpid");

        printf("Состояние потомка: ");

        if (WIFEXITED(status)) {

            printf("завершился, состояние=%d\n", WEXITSTATUS(status));

        } else if (WIFSIGNALED(status)) {

            printf("убит по сигналу %d\n", WTERMSIG(status));

        } else if (WIFSTOPPED(status)) {

            printf("остановлен по сигналу %d\n", WSTOPSIG(status));

        } else if (WIFCONTINUED(status)) {

            printf("выполняется\n");

        }

    } while (!WIFEXITED(status) && !WIFSIGNALED(status));

    exit(EXIT_SUCCESS);
}
```

## СМОТРИТЕ ТАКЖЕ
close(2), dup2(2), execl(2), execlp(2), fork(2), open(2), sched_setparam(2), sched_setscheduler(2), setpgid(2), setuid(2), sigaction(2), sigprocmask(2), posix_spawn_file_actions_addclose(3), posix_spawn_file_actions_adddup2(3), posix_spawn_file_actions_addopen(3), posix_spawn_file_actions_destroy(3), posix_spawn_file_actions_init(3), posix_spawnattr_destroy(3), posix_spawnattr_getflags(3), posix_spawnattr_getpgroup(3), posix_spawnattr_getschedparam(3), posix_spawnattr_getschedpolicy(3), posix_spawnattr_getsigdefault(3), posix_spawnattr_getsigmask(3), posix_spawnattr_init(3), posix_spawnattr_setflags(3), posix_spawnattr_setpgroup(3), posix_spawnattr_setschedparam(3), posix_spawnattr_setschedpolicy(3), posix_spawnattr_setsigdefault(3), posix_spawnattr_setsigmask(3), pthread_atfork(3), <spawn.h>, Base Definitions volume of POSIX.1-2001, http://www.opengroup.org/unix/online.html


pow

package: man-pages-ru

title: pow(3)

summary: функции возведения в степень

text:
# pow(3)

## ИМЯ
pow, powf, powl - функции возведения в степень

## ОБЗОР

```
#include <math.h>
```

```
double pow(double x, double y);
float powf(float x, float y);
long double powl(long double x, long double y);
```

Компонуется при указании параметра -lm.

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

powf(), powl():

_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

|| /* начиная с glibc 2.19: */ _DEFAULT_SOURCE

|| /* версии glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE

## ОПИСАНИЕ
Данные функции возвращают значение x, возведённое в степень y.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении данные функции возвращают значение x, возведённое в степень y.

Если x — конечное значение меньшее 0 и y — конечное не целое, то будет сгенерирована ошибка выхода за пределы области, а в качестве результата будет возвращено NaN.

Если происходит переполнение результата, возникает ошибка диапазона, а функция возвращает HUGE_VAL, HUGE_VALF или HUGE_VALL, соответственно, с математически правильным знаком.

Если в результате исчерпана степень числа и оно не представимо, то возникает ошибка диапазона и возвращается 0.0.

За исключениями, указанными далее, если значение x или y равно NaN, то результат равен NaN.

Если x равно +1, то результат равен 1.0 (даже если y равно NaN).

Если y равно 0, то результат равен 1.0 (даже если x равно NaN).

Если x равно +0 (-0) и y — нечётное целое большее 0, то результат равен +0 (-0).

Если x равно 0 и y больше 0 и не чётное целое, то результат равен +0.

Если x равно -1 и y стремится к плюс или минус бесконечности, то результат равен 1.0.

Если абсолютное значение x меньше 1 и y стремится к минус бесконечности, то результат стремится к плюс бесконечности.

Если абсолютное значение x больше 1 и y стремится к минус бесконечности, то результат равен +0.

Если абсолютное значение x меньше 1 и y стремится к плюс бесконечности, то результат равен +0.

Если абсолютное значение x больше 1 и y стремится к плюс бесконечности, то результат стремится к плюс бесконечности.

Если x стремится к минус бесконечности и y — нечётное целое меньшее 0, то результат равен -0.

Если x стремится к минус бесконечности и y — меньше 0 и чётное целое, то результат равен +0.

Если x стремится к минус бесконечности и y — нечётное целое большее 0, то результат стремится к минус бесконечности.

Если x стремится к минус бесконечности и y — больше 0 и чётное целое, то результат стремится к плюс бесконечности.

Если x стремится к плюс бесконечности и y — меньше 0, то результат равен +0.

Если x стремится к плюс бесконечности и y — больше 0, то результат стремится к плюс бесконечности.

Если x равно +0 или -0 и y — нечётное целое меньшее 0, то генерируется ошибка особой точки и возвращается HUGE_VAL, HUGE_VALF или HUGE_VALLс тем же знаком что и у x.

Если x равно + или -0 и y — меньше 0 и чётное целое, то генерируется ошибка особой точки и возвращается +HUGE_VAL, +HUGE_VALF или +HUGE_VALL.

## ОШИБКИ
Смотрите math_error(7), чтобы определить, где возникла ошибка при вызове этих функций.

Могут возникать следующие ошибки:

Ошибка области: x является отрицательным и y конечное нецелое

errno устанавливается в EDOM. Возникает исключение неправильной плавающей запятой (FE_INVALID).

Ошибка особой точки: x равно нулю и y отрицательно

errno устанавливается в ERANGE (но смотрите ДЕФЕКТЫ). Возникает исключение деления плавающей запятой на ноль (FE_DIVBYZERO).

Ошибка диапазона: результат превысил разрядность

Значение errno устанавливается в ERANGE. Возникает исключение переполнения плавающей запятой (FE_OVERFLOW).

Ошибка диапазона: результат исчерпал степень

Значение errno устанавливается в ERANGE. Возникает исключение исчерпания степени чисел с плавающей запятой (FE_UNDERFLOW).

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pow(), powf(), powl()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
C99, POSIX.1-2001, POSIX.1-2008.

Вариант, возвращающий значение типа double, также соответствует SVr4, 4.3BSD, C89.

## ДЕФЕКТЫ
На 64-битных архитектурах pow() может быть медленнее более чем в 10000 раз для некоторых значений (очень редких). Это происходит только с pow(), и отсутствует у powf() и powl().

В glibc 2.9 и ранее при возникновении ошибки особой точки, значению errno присваивается EDOM вместо ERANGE согласно POSIX. Начиная с версии 2.10, в glibc это исправлено.

Если x отрицательно, то большие отрицательные или положительные значения y приводят к результату NaN, с присвоением errno значения EDOM или исключению неправильной плавающей запятой (FE_INVALID). Например для pow() такое случает когда абсолютное значение y больше 9.223373e18.

В glibc версии 2.3.2 или старее при возникновении ошибки переполнения или исчерпания, функция pow() в дополнение к исключениям переполнения и исчерпания генерирует необоснованное исключение неправильной плавающей запятой (FE_INVALID)

## СМОТРИТЕ ТАКЖЕ
cbrt(3), cpow(3), sqrt(3)


title: pow10(3)

summary: функция возведения числа 10 в степень

text:
# pow10(3)

## ИМЯ
pow10, pow10f, pow10l - функция возведения числа 10 в степень

## ОБЗОР

```
#define _GNU_SOURCE         /* см. feature_test_macros(7) */
#include <math.h>
```

```
double pow10(double x);
float pow10f(float x);
long double pow10l(long double x);
```

Компонуется при указании параметра -lm.

## ОПИСАНИЕ
Данные функции возвращают значение 10, возведённое в степень x.

Примечание: Эти функции выполняют те же задачи, что и функции, описанные в exp10(3), с той разницей, что последние описаны в TS 18661-4:2015. Рекомендуется использовать последние функции, а не описанные в этой странице.

## ВЕРСИИ
Эти функции впервые появились в glibc 2.1. Начиная с glibc 2.27, использование данных функций в новых программах больше не поддерживается.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pow10(), pow10f(), pow10l()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Эти функции являются расширениями GNU.

## СМОТРИТЕ ТАКЖЕ
exp10(3), pow(3)


printf

title: printf(3)

summary: преобразование форматированного вывода

text:
# printf(3)

## ИМЯ
printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, vsprintf, vsnprintf - преобразование форматированного вывода

## ОБЗОР

```
#include <stdio.h>
```

```
int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);
int dprintf(int fd, const char *format, ...);
int sprintf(char *str, const char *format, ...);
int snprintf(char *str, size_t size, const char *format, ...);
#include <stdarg.h>
```

```
int vprintf(const char *format, va_list ap);
int vfprintf(FILE *stream, const char *format, va_list ap);
int vdprintf(int fd, const char *format, va_list ap);
int vsprintf(char *str, const char *format, va_list ap);
int vsnprintf(char *str, size_t size, const char *format, va_list ap);
```

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

snprintf(), vsnprintf():

_XOPEN_SOURCE >= 500 || _ISOC99_SOURCE ||

|| /* версии glibc <= 2.19: */ _BSD_SOURCE

dprintf(), vdprintf():

Начиная с glibc 2.10:

_POSIX_C_SOURCE >= 200809L

До glibc 2.10:

_GNU_SOURCE

## ОПИСАНИЕ
Функции семейства printf() выводят данные в соответствии с параметром format, описанным ниже. Функции printf() и vprintf() направляют данные в стандартный поток вывода stdout; функции fprintf() и vfprintf() направляют данные в заданный поток вывода stream; функции sprintf(), snprintf(), vsprintf() и vsnprintf() направляют данные в символьную строку str.

Функция dprintf() подобна fprintf() за исключением того, что выводит данные в файловый дескриптор fd, а не в поток stdio.

Функции snprintf() и vsnprintf() записывают не более size байт (включая конечный байт null ('\0')) в str.

Функции vprintf(), vfprintf(), vdprintf(), vsprintf(), vsnprintf() эквивалентны printf(), fprintf(), dprintf(), sprintf(), snprintf(), соответственно, за исключением того, что они вызываются с va_list, а не переменным числом аргументов. Эти функции не вызывают макрос va_end. Так как они вызывают макрос va_arg, значение ap не определено после вызова. Смотрите stdarg(3).

Все эти функции выводят данные в соответствии со строкой format, которая определяет, каким образом последующие параметры (или доступные параметры переменной длины из stdarg(3)) преобразуют поток вывода.

В C99 и POSIX.1-2001 указано, что результат не определён, если вызов sprintf(), snprintf(), vsprintf() или vsnprintf() привёл бы копированию между перекрывающимися объектами (например, если массив строк назначения и один из указанных входных аргументов ссылаются на один буфер). Смотрите ЗАМЕЧАНИЯ.

### Структура строки параметров
Строка параметров — это строка символов, начинающаяся и заканчивающаяся в своём начальном состоянии сдвига, если оно есть. Строка может состоять из нуля или более директив: обычных символов (кроме %), которые неизменно копируются в поток выхода; и спецификаторов преобразования, по каждому из которых выбирается ноль или более последующих параметров. Каждый спецификатор преобразований начинается с символа % и заканчивается спецификатором преобразования. Между ними могут находиться (в определённом порядке) ноль или более флагов, необязательная минимальная ширина поля, необязательная точность и необязательный модификатор длины.

Параметры должны точно соответствовать (после преобразования типа) спецификаторам преобразований. По умолчанию параметры используются в порядке поступления, где каждая «*» (смотрите Ширина поля и Точность ниже) и каждый спецификатор преобразования требуют последующего параметра (если указано недостаточно параметров, то это приведёт к ошибке). Возможно явное указание на то, какой параметр будет следующим, с помощью записи «%m$» вместо «%» и «*m$» вместо «*ю, где десятичная цифра m означает позицию нужного параметра в их списке; список начинается с единицы. Таким образом,

```
printf("%*d", width, num);
```

и

```
printf("%2$*1$d", width, num);
```

означают одно и то же. Вторая форма записи позволяет производить указание на тот же параметр несколько раз. Стандарт C99 не поддерживает использование «$», который пришёл из Single UNIX Specification. Если используется «$», то он должен использоваться для всех преобразований аргументов и во всех аргументах ширины и точности, но он может быть смешан с форматами «%%», которые не поглощают аргументы. Там может не быть пробелов между числами аргументов, обусловленные использованием «$». Например, если аргументы 1 и 3 определены, то аргумент 2 должен также быть определён где-то в строке параметров.

В некоторых цифровых преобразованиях используется символ разделения целой и дробной частей или символ разделения тысяч. Текущий символ зависит от локали, а именно от значения переменной LC_NUMERIC (смотрите setlocale(3)).В локали POSIX по умолчанию используется символ «.» и не отсутствует символ разделения. Таким образом,

```
    printf("%'.2f", 1234567.89);
```

выводит «1234567.89» при локали POSIX, «1234567,89» при локали nl_NL и «1.234.567,89» при локали da_DK.

### Флаги
За символом % может быть указано ноль или несколько следующих флагов:

\#

Значение преобразуется в «альтернативную форму». Для преобразования типа o первый символ выходного потока будет нуль (префикс 0, если до этого его не было указано). Для преобразований типа x и X к ненулевому результату добавляется «0x» (или «0X» для преобразования типа X). При преобразованиях типа a, A, e, E, f, F, g и G результат всегда будет содержать десятичную точку, даже если за ней не следует цифр (обычно десятичная точка присутствует в результате таких преобразований только, если за ними следуют цифры). Для преобразований g и G завершающие нули не удаляются из результата, как это обычно случается. Результат для других преобразований не определён.

0

В значение добавляются нули. При преобразованиях типа d, i, o, u, x, X, a, A, e, E, f, F, g и G преобразуемое значение слева дополняется нулями (вместо пробелов). Если присутствуют флаги 0 и -, то флаг 0 игнорируется. Если в числовом преобразовании указана точность (d, i, o, u, x, и X), то флаг 0 игнорируется. Поведение флага при других преобразованиях не определено.

-

Выравнивает результат преобразования по левой границе поля (по умолчанию выравнивание выполняется справа). Преобразованное значение дополняется справа пробелами, а не пробелами или нулями слева. Флаг - отменяет флаг «0», если было указано оба флага.

' '

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

+

Знак + или - всегда помещается перед преобразованным числом со знаком. По умолчанию знак используется только для отрицательных чисел. Флаг + отменяет действие пробела, если указаны оба флага.

Пять флагов, описанных выше, определены в стандарте C99. В стандарте Single UNIX Specification определён ещё один дополнительный флаг.

'

При десятичных преобразованиях (i, d, u, f, F, g, G) результат группируется символом разделителя тысяч, если информация локализации указывает на это (смотрите setlocale(3)). Заметим, что многие версии gcc(1) не могут распознать этот флаг и выводят соответствующее предупреждение (SUSv2 не содержи %'F, но в SUSv3 его добавили).

В glibc 2.2 добавлен ещё один флаг.

I

При преобразовании целых десятичных чисел (i, d, u) в результате используется альтернативное представление цифр согласно локали. Например, начиная с glibc 2.2.3 это даёт арабско-индийские цифры для персидской локали («fa_IR»).

### Ширина поля
Необязательная строка из десятичных цифр (с первой цифрой, отличной от нуля) определяет минимальную ширину поля. Если преобразованное значение имеет меньшее количество знаков, чем ширина поля, то оно слева дополняется пробелами (или справа, если указан флаг выравнивания по левому краю). Вместо строки десятичных цифр можно указать «*» или «*m$» (для некоторого десятичного числа m), чтобы определить ширину поля по ширине следующего аргумента или аргумента с номером m (должен быть типа int), соответственно. Отрицательная ширина поля принимается как флаг «-», устанавливающий положительную ширину поля. Несуществующая или небольшая ширина поля не делает его усечённым; если результат преобразования больше ширины поля, то поле расширяется, чтобы вместить в себя преобразованное значение.

### Точность
Необязательный параметр точности в виде знака точки («.») сопровождается необязательной строкой десятичных цифр. Вместо строки десятичных цифр можно указать «*» или «*m$» (для некоторого десятичного числа m), чтобы определить значение точности по следующему аргументу или аргументу с номером m (должен быть типа int), соответственно. Если точность указана как «.», то она обрабатывается как нулевая. Отрицательная точность обрабатывается как если не указывалась совсем. Это позволяет ограничивать количество выводимых символов для преобразований d, i, o, u, x и X; показывать определённое количество цифр после десятичной точки для преобразований a, A, e, E, f и F; показывать максимальное количество значащих цифр для преобразований g и G или максимальное количество символов для печати строк при преобразованиях s и S.

### Модификатор длины
Устанавливаются для следующих «преобразований целого» d, i, o, u, x или X.

hh

Преобразование целого числа соответствует аргументам signed char или unsigned char, а также тип преобразования n соответствует указателю на аргумент signed char.

h

Преобразование целого числа соответствует аргументам short int или unsigned short int, а также тип преобразования n соответствует указателю на аргумент short int.

l

(эль) Преобразование целого числа соответствует аргументам long int или unsigned long int; тип преобразования n соответствует указателю на аргумент long int; тип преобразования c соответствует аргументу wint_t; тип преобразования s соответствует указателю на аргумент wchar_t.

ll

(эль-эль) Преобразование целого числа соответствует аргументам long long int или unsigned long long int, а также тип преобразования n соответствует указателю на аргумент long long int.

q

Синоним ll. Является нестандартным расширением, унаследовано от BSD; не используйте в новом коде.

L

Типы преобразования a, A, e, E, f, F, g или G соответствуют аргументу long double (в C99 допускается %LF, но в SUSv2 нет).

j

Преобразование целого числа соответствует аргументам intmax_t или uintmax_t, а также тип преобразования n соответствует указателю на аргумент intmax_t.

z

Преобразование целого числа соответствует аргументам size_t или ssize_t, а также тип преобразования n соответствует указателю на аргумент size_t.

Z

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

t

Преобразование целого числа соответствует аргументам ptrdiff_t или тип преобразования n соответствует указателю на аргумент ptrdiff_t.

В SUSv3 определено всё вышеперечисленное, за исключением указанных как нестандартное расширение. В SUSv2 определены только модификаторы длины h (в hd, hi, ho, hx, hX, hn) и l (в ld, li, lo, lx, lX, ln, lc, ls) и L (в Le, LE, Lf, Lg, LG).

Не по стандарту реализации GNU считают ll и L синонимами, поэтому, например, можно написать llg (синоним стандартного Lg) и Ld (синоним стандартного lld). Такое использование не переносимо.

### Тип преобразования
Символы, которые определены как типы преобразования. Типы преобразования и их значения:

d, i

Параметр int преобразует символы в их знаковое десятичное отображение. Точность (если указана) задаёт минимальное количество цифр в изображении результата; если результат можно показать с помощью меньшего количества цифр, то слева добавляются незначащие нули. По умолчанию значение точности равно единице. При выводе нуля с нулевой точностью выходной поток будет пуст.

o, u, x, X

Параметр unsigned int преобразуется в беззнаковое восьмеричное число (o), беззнаковое десятичное (u) или беззнаковое шестнадцатеричное (x и X). Буквы abcdef используются в преобразованиях x; буквы ABCDEF используются в преобразованиях X. Точность (если указана) задаёт минимальное количество цифр в изображении результата; если результат можно показать с помощью меньшего количества цифр, то слева добавляются незначащие нули. По умолчанию значение точности равно единице. При выводе нуля с нулевой точностью выходной поток будет пуст.

e, E

Параметр double округляется и преобразуется в вид [-]d.ddde±dd, в котором есть одна цифра (не равная нулю, если аргумент не равен нулю) до символа десятичной точки и количество цифр после, указывающих на требуемую точность. Если точность отсутствует, она принимается равной 6; если точность равна нулю, десятичная точка не показывается. В преобразовании для представление экспоненты E используется буква E (а не e). В экспоненте всегда не менее двух цифр; если значение ноль, то экспонента выводится как 00.

f, F

Параметр double округляется и преобразуется в десятичное выражение в виде [-]ddd.ddd, где количество цифр после десятичной точки указывает на требуемую точность. Если точность отсутствует, она принимается равной 6-и; если точность равна нулю, десятичная точка не показывается. Если десятичная точка есть, перед ней должна быть минимум одна цифра

(в SUSv2 отсутствует информация о F и указано, что этот символ предназначен для отображения символов бесконечности и NaN. В SUSv3 добавлен тип F. В стандарте C99 определены «[-]inf» или «[-]infinity» для указания бесконечности, и строка начинающаяся с «nan» для NaN в случае, если тип преобразования равен f, а начинающаяся с «[-]INF», «[-]INFINITY» или «NAN» в случае, если тип преобразования равен F).

g, G

Параметр double преобразуется в стиле f или e (или F или E, для преобразования G). Точность определяется количеством значащих цифр. Если точность отсутствует, то она определяется равной 6-и цифрам; если точность равна нулю, то она трактуется как 1. Стиль e используется, если экспонента преобразования меньше -4, или больше или равна ей. Завершающие нули удаляются из дробной части результата; десятичная точка стоит, только если за ней следует, по крайней мере, одна цифра.

a, A

(C99; отсутствует в SUSv2, до добавлено в SUSv3) Для преобразования типа a параметр double отображается в шестнадцатеричной форме (с помощью букв abcdef) вида [-]0xh.hhhhp±; для преобразований типа A используется префикс 0X, буквы ABCDEF и и разделитель экспоненты P. Точность равна шестнадцатеричному разряду перед десятичной точкой и количеству цифр после неё. По умолчанию точность принимается равной точному значению разряда, если оно соответствует ему по основанию 2, и в противном случае размер её является достаточным для определения значения типа double. Разряд перед десятичной точкой не определён для ненормализованных чисел и не равен нулю, но не определён для нормализованных чисел.

c

Если модификатор l не указан, то параметр int преобразуется в unsigned char и выводится как результирующее значение. Если l указан, то параметр wint_t (широкий символ) преобразуется в многобайтовую последовательность вызовом функции wcrtomb(3); первое его значение преобразуется в начальное значение и выводится в виде многобайтовой строки.

s

Если модификатор l не указан: параметр const char * преобразуется в указатель на массив символьного типа (строковый указатель). Символы из массива выводятся до конечного байта null ('\0', не включая его); если указана точность, то выводится не более установленного количества символов. Если точность указана, то байт null не нужен. Если точность не указана или она больше, чем размер массива, то массив должен содержать конечный байт null.

Если модификатор l указан: параметр const wchar_t * должен быть указателем на массив широких символов. Широкие символы из массива преобразуются в многобайтовые символы (каждый вызовом функции wcrtomb(3), при этом первое значение преобразуется в начальное значение первого широкого символа) и так до конечного широкого символа null. Результирующие многобайтовые символы выводятся до конечного байта null (не включая его). Если указана точность, то выводится количество байтов, не превышающее это значение, а оставшаяся часть многобайтовых символов не выводится. Заметим, что точность определяется количеством выведенных байт, не широких символов или положением на экране. Массив должен содержать конечный широкий символ null, если точность не указана, и содержать количество байт, меньше размера массива.

C

(отсутствует в C99 или C11, но есть в SUSv2, SUSv3 и SUSv4) Синоним lc. Не используйте.

S

(отсутствует в C99 или C11, но есть в SUSv2, SUSv3 и SUSv4) Синоним ls. Не используйте.

p

Параметр указателя void *, выводящийся в шестнадцатеричном виде (также как при %#x или %#lx).

n

Количество символов, выводящихся в целом типе int * (или других) без преобразующих параметров. Данный параметр должен быть int * или его вариантом, размер которого совпадает с (необязательно) указываемым целым модификатором длины. Параметр не преобразуется (данный тип не поддерживается библиотекой bionic C). Поведение не определено, если тип преобразования содержит флаги, ширину поля или точность.

m

(расширение glibc; поддерживается uClibc и musl) Выводит содержимое strerror(errno). Параметр не требуется.

%

Выводит символ '%'. Параметр не требуется. Полный спецификатор преобразования — '%%'.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении данные функции возвращают количество напечатанных символов (не включая байт null, используемый в конце выводимых строк).

Функции snprintf() и vsnprintf() записывают не более size байт (включая конечный байт null ('\0')). Если вывод был обрезан из-за данного ограничения, то возвращаемое значение это количество символов (не включая конечный байт null), которое было бы записано в результирующую строку, если бы было достаточно места. Таким образом, если возвращённое значение больше или равно size, то вывод был обрезан (также смотрите ЗАМЕЧАНИЯ ниже).

Если возникла ошибка, то возвращается отрицательное значение.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

printf(), fprintf(), sprintf(), snprintf(), vprintf(), vfprintf(), vsprintf(), vsnprintf()

Безвредность в нитях

MT-Safe locale

## СООТВЕТСТВИЕ СТАНДАРТАМ
fprintf(), printf(), sprintf(), vprintf(), vfprintf(), vsprintf(): POSIX.1-2001, POSIX.1-2008, C89, C99.

snprintf(), vsnprintf(): POSIX.1-2001, POSIX.1-2008, C99.

Функции dprintf() и vdprintf() изначально являлись расширениями GNU, но позже были стандартизованы в POSIX.1-2008.

Что касается возвращаемого значения snprintf(), то стандарты SUSv2 и C99 противоречат друг другу: когда snprintf() вызывается с size=0, то SUSv2 предусматривает возврат неопределённого значения меньше единицы, а C99 устанавливает в этом случае str равным NULL и возвращает значение (как обычно) в виде количества символов, достаточного для выходной строки. В POSIX.1-2001 и новее поведение snprintf() совпадает с C99.

В glibc 2.1 добавлены модификаторы длины hh, j, t и z и символы преобразования a и A.

В glibc 2.2 добавлен символ преобразования F с семантикой C99, а также флаг I.

## ЗАМЕЧАНИЯ
В некоторых программах неосмотрительно используется код

sprintf(buf, "%s some further text", buf);

для добавления текста в buf. Однако в стандартах явно сказано, что результат не определён, если буферы источника и приёмника перекрываются при вызовах sprintf(), snprintf(), vsprintf() и vsnprintf(). В зависимости о версии gcc(1) и указанных параметрах компилятора, подобные вызовы не приводят к ожидаемым результатам.

Реализация функций snprintf() и vsnprintf() в glibc 2.1 соответствует стандарту C99 как было описано выше. До glibc 2.0.6, они возвращали -1 при обрезанном выводе.

## ДЕФЕКТЫ
Так как sprintf() и vsprintf() работают со строкой произвольной длины, вызывающие должны стараться не переполнить реальное пространство; часто это невозможно гарантировать. Заметим, что длина получаемых строк зависит от локали и её сложно предсказать. Вместо них используйте snprintf() и vsnprintf() (или asprintf(3) и vasprintf(3)).

Код, подобный printf(foo); часто означает ошибку, так как foo может содержать символ %. Если содержимое foo пришло из недоверительного пользовательского ввода, то в нём может содержаться %n, из-за чего вызов printf() сделать запись в память и создаст дыру в безопасности.

## ПРИМЕР
Печать Pi с пятью знаками:

```
#include <math.h>
#include <stdio.h>
fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));
```

Печать даты и времени в виде «Sunday, July 3, 10:02», где weekday и month указатели на строки:

```
#include <stdio.h>
fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",

        weekday, month, day, hour, min);
```

Во многих странах используется порядок день-месяц-год. Вот печать аргументов в формате с учётом интернациональности:

```
#include <stdio.h>
fprintf(stdout, format,

        weekday, month, day, hour, min);
```

где format зависит от локали и может переставлять аргументы. Со значением:

```
"%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
```

получается «Sonntag, 3. Juli, 10:02».

Выделение достаточно большой строки и печать в неё (код работает и с glibc 2.0, и с glibc 2.1):

```
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
char *
make_message(const char *fmt, ...)
{

    int size = 0;

    char *p = NULL;

    va_list ap;

    /* определим требуемый размер */

    va_start(ap, fmt);

    size = vsnprintf(p, size, fmt, ap);

    va_end(ap);

    if (size < 0)

        return NULL;

    size++;             /* для '\0' */

    p = malloc(size);

    if (p == NULL)

        return NULL;

    va_start(ap, fmt);

    size = vsnprintf(p, size, fmt, ap);

    va_end(ap);

    if (size < 0) {

        free(p);

        return NULL;

    }

    return p;
}
```

Если происходит обрезание в версиях glibc до 2.0.6, то это считается ошибкой.

## СМОТРИТЕ ТАКЖЕ
printf(1), asprintf(3), puts(3), scanf(3), setlocale(3), strfromd(3), wcrtomb(3), wprintf(3), locale(5)


profil

title: profil(3)

summary: профилирование времени работы

text:
# profil(3)

## ИМЯ
profil - профилирование времени работы

## ОБЗОР

```
#include <unistd.h>
```

```
int profil(unsigned short *buf, size_t bufsiz,
           size_t offset, unsigned int scale);
```

```

```

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

profil():

```
    Начиная с glibc 2.21:

        _DEFAULT_SOURCE

    В glibc 2.19 и 2.20:

        _DEFAULT_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

    По glibc 2.19 включительно:

        _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
```

## ОПИСАНИЕ
Эта функция позволяет выяснить какие области вашей программы работают больше всего. В аргументе buf указывается bufsiz байт ядра. Каждые 10 виртуальных миллисекунд проверяется пользовательский программный счётчик (PC): из него вычитается offset, умножается на scale и делится на 65536. Если полученное значение меньше bufsiz, то в buf увеличивается соответствующая запись. Если buf равно NULL, профилирование выключено.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Всегда возвращается ноль.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

profil()

Безвредность в нитях

MT-Unsafe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Подобно вызову в SVr4 (но не POSIX.1).

## ДЕФЕКТЫ
Функцию profil() нельзя использовать на программе, которая также использует таймеры интервалов ITIMER_PROF (смотрите setitimer(2)).

При профилировании настоящим ядром получаются более точные результаты. В libc 4.4 есть заплата к ядру, добавляющая системный вызов profil.

## СМОТРИТЕ ТАКЖЕ
gprof(1), sprof(1), setitimer(2), sigaction(2), signal(2)


title: program_invocation_name(3)

summary: имя, использованное

text:
# program_invocation_name(3)

## ИМЯ
program_invocation_name, program_invocation_short_name - имя, использованное для запуска вызвавшей программы

## ОБЗОР

```
#define _GNU_SOURCE         /* см. feature_test_macros(7) */
#include <errno.h>
```

```
extern char *program_invocation_name;
extern char *program_invocation_short_name;
```

## ОПИСАНИЕ
Переменная program_invocation_name содержит имя, которое было использовано для запуска вызвавшей программы. Это значение совпадает с argv[0] в main(); отличие в том, что program_invocation_name — глобальная переменная.

Переменная program_invocation_short_name содержит базовую часть имени, которое было использовано для запуска вызвавшей программы. То есть её значение совпадает с началом program_invocation_name до последней косой черты (/).

Эти переменные автоматически инициализируются glibc при запуске программы.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Эти переменные являются расширениями GNU, и они не должны использоваться в переносимых программах.

## ЗАМЕЧАНИЯ
В Linux файл /proc/[number]/cmdline содержит подобную информацию.

## СМОТРИТЕ ТАКЖЕ
proc(5)


psignal

title: psignal(3)

summary: выводит сообщение о сигнале

text:
# psignal(3)

## ИМЯ
psignal, psiginfo - выводит сообщение о сигнале

## ОБЗОР

```
#include <signal.h>
```

```
void psignal(int sig, const char *s);
void psiginfo(const siginfo_t *pinfo, const char *s);
```

```
extern const char *const sys_siglist[];
```

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

psignal():

начиная с glibc 2.19:

_DEFAULT_SOURCE

в glibc 2.19 и старее:

_BSD_SOURCE || _SVID_SOURCE

psiginfo(): _POSIX_C_SOURCE >= 200809L

sys_siglist():

начиная с glibc 2.19:

_DEFAULT_SOURCE

в glibc 2.19 и старее:

_BSD_SOURCE

## ОПИСАНИЕ
Функция psignal() выводит сообщение в stderr, состоящее из строки s, двоеточия, пробела, строки описания номера сигнала sig и конечного символа новой строки. Если строка s равна NULL или пуста, то двоеточие и пробел не выводятся. Если значение sig некорректно, то выводится сообщение о неизвестном сигнале.

Функция psiginfo() подобна psignal(), но выводит информацию о сигнале, указанном в аргументе pinfo, который должен указывать на корректную структуры siginfo_t. Кроме описания сигнала psiginfo() выводит информацию об источнике сигнала и другую информацию о сигнале (например, соответствующий адрес памяти, в случае аппаратных сигналов, идентификатор процесса-потомка для SIGCHLD и идентификаторы пользователя и процесса отправителя для сигналов, посланных с помощью kill(2) или sigqueue(3)).

В массиве sys_siglist содержатся строки описаний сигналов, упорядоченные по номеру сигнала.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции psignal() и psiginfo() ничего не возвращают.

## ВЕРСИИ
Функция psiginfo() впервые появилась в glibc 2.10.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

psignal(), psiginfo()

Безвредность в нитях

MT-Safe locale

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2008, 4.3BSD.

## ДЕФЕКТЫ
В glibc до версии 2.12, в psiginfo() были следующие дефекты:

- При определённых условиях не выводился символ новой строки.

- Для сигналов реального времени не выводилась дополнительная информация.

## СМОТРИТЕ ТАКЖЕ
sigaction(2), perror(3), strsignal(3), signal(7)


title: pthread_atfork(3)

summary: регистрирует обработчики ветвления

text:
# pthread_atfork(3)

## ИМЯ
pthread_atfork - регистрирует обработчики ветвления

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_atfork(void (*prepare)(void), void (*parent)(void),
                   void (*child)(void));
```

Компонуется при указании параметра -pthread.

## ОПИСАНИЕ
Функция pthread_atfork() регистрирует обработчик ветвления, которые будут запускаться при вызове fork(2) этой нитью. Обработчики запускаются в контексте нити, которая вызвала fork(2).

Можно регистрировать три типа обработчиков:

- Типом prepare задаётся обработчик, который выполняется од начала работы fork(2).

- Типом parent задаётся обработчик, который выполняется в родительском процессе после завершения работы fork(2).

- Типом child задаётся обработчик, который выполняется в потомке после завершения работы fork(2).

Любой из трёх аргументов может быть равен NULL, если обработчик не требуется на соответствующем шаге работы fork(2).

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении pthread_atfork() возвращается ноль. При ошибке возвращается номер ошибки. Функция pthread_atfork() может быть вызвана нитью несколько раз для регистрации нескольких обработчиков каждого шага. Обработчики каждого шага вызываются в определённом порядке: обработчики prepare вызываются в порядке обратном регистрации; обработчики parent и child вызываются в порядке их регистрации.

## ОШИБКИ
ENOMEM

Невозможно выделить память для записи элемента обработчика.

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
При вызове fork(2) в многонитевом процессе в дочернем процессе делается копия только вызвавшей нити. Первоначальной целью pthread_atfork() было позволить возвращаться в вызывающей нити в целостном состоянии. Например, на момент вызова fork(2) другие нити могут заблокировать мьютексы, которые видимы в памяти пользовательского пространства копии в потомке. Такие мьютексы никогда не разблокируются, так как нити, создавшие блокировку, не копируются в потомок. Целью pthread_atfork() было предоставить механизм, позволяющий приложению (или библиотеке) сделать так, чтобы мьютексы, другой процесс и состояние нити восстанавливались бы в целостном состоянии. На практике, эта задача очень сложна для реализации.

В многонитевом процессе fork(2) возвращает управление в потомок; потомок должен вызывать только функции async-signal-safe (смотрите signal-safety(7)) до момента, пока не вызовет execve(2) для выполнения новой программы.

В POSIX.1 указано, что pthread_atfork() не должен завершаться ошибкой EINTR.

## СМОТРИТЕ ТАКЖЕ
fork(2), atexit(3), pthreads(7)


title: pthread_attr_init(3)

summary: инициализирует и уничтожает объект

text:
# pthread_attr_init(3)

## ИМЯ
pthread_attr_init, pthread_attr_destroy - инициализирует и уничтожает объект атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_init(pthread_attr_t *attr);
int pthread_attr_destroy(pthread_attr_t *attr);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_init() инициализирует объект атрибутов нити, на который указывает attr, значениями атрибутов по умолчанию. После этого вызова отдельные атрибуты объекта можно изменять с помощью различных соответствующих функций (перечислены в разделе СМОТРИТЕ ТАКЖЕ, а после этого объект можно использовать в одном или нескольких вызовах pthread_create(3) для создания нитей.

Вызов pthread_attr_init() с уже инициализированным объектом атрибутов нити приводит к непредсказуемому поведению.

Когда объект атрибутов нити больше не нужен, он должен быть уничтожен с помощью функции pthread_attr_destroy(). Уничтожение объекта атрибутов нити не влияет на нить, которая была создана с использованием этого объекта.

После уничтожения объекта атрибутов нити его можно инициализировать с помощью pthread_attr_init() повторно. При использовании уничтоженного объекта атрибутов нити другим способом приводит непредсказуемым результатам.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
В POSIX.1 описана ошибка ENOMEM для pthread_attr_init(); в Linux эти функции всегда выполняются успешно (тем не менее, в переносимых приложениях нужно учитывать возможность возврата ошибки).

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_init(), pthread_attr_destroy()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Тип pthread_attr_t должен считаться со скрытым форматом: любой доступ к объекту помимо функций pthreads является непереносимым и приводит к непредсказуемым результатам.

## ПРИМЕР
В программе, представленной ниже, для создания одной нити используется pthread_attr_init() и другие функции, относящиеся к инициализации объекта атрибутов нити. После создания в нити используется функция pthread_getattr_np(3) (нестандартное расширение GNU) для получения атрибутов нити, а затем показываются эти атрибуты.

Если программа запускается без аргументов командной строки, то аргумент attr функции pthread_create(3) равен NULL, и поэтому нить создаётся с атрибутами по умолчанию. При запуске программы на Linux/x86-32 с реализацией нитей NPTL мы увидим следующее:

```
$ ulimit -s       # стек не ограничен ==> размер стека по умолчанию 2 МБ
unlimited
$ ./a.out
Атрибуты нити:

        Состояние отсоединения     = PTHREAD_CREATE_JOINABLE

        Область                    = PTHREAD_SCOPE_SYSTEM

        Унаследованный планировщик = PTHREAD_INHERIT_SCHED

        Алгоритм планирования      = SCHED_OTHER

        Приоритет планирования     = 0

        Размер защиты              = 4096 байт

        Адрес стека                = 0x40196000

        Размер стека               = 0x201000 байт
```

Если в командной строке мы укажем размер стека, то программа инициализирует объект атрибутов нити, задаёт различные атрибуты в этом объекте и передаёт указатель на объект в вызов pthread_create(3). При запуске программы на Linux/x86-32 с реализацией нитей NPTL мы увидим следующее:

```
$ ./a.out 0x3000000
posix_memalign() выделен по адресу 0x40197000
Атрибуты нити:

        Состояние отсоединения     = PTHREAD_CREATE_DETACHED

        Область                    = PTHREAD_SCOPE_SYSTEM

        Унаследованный планировщик = PTHREAD_EXPLICIT_SCHED

        Алгоритм планирования      = SCHED_OTHER

        Приоритет планирования     = 0

        Размер защиты              = 0 байт

        Адрес стека                = 0x40197000

        Размер стека               = 0x3000000 байт
```

### Исходный код программы

```
#define _GNU_SOURCE     /* для объявления pthread_getattr_np() */
#include <pthread.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <errno.h>
#define handle_error_en(en, msg) \

        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
static void
display_pthread_attr(pthread_attr_t *attr, char *prefix)
{

    int s, i;

    size_t v;

    void *stkaddr;

    struct sched_param sp;

    s = pthread_attr_getdetachstate(attr, &i);

    if (s != 0)

        handle_error_en(s, "pthread_attr_getdetachstate");

    printf("%sСостояние отсоединения     = %s\n", prefix,

            (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" :

            (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" :

            "???");

    s = pthread_attr_getscope(attr, &i);

    if (s != 0)

        handle_error_en(s, "pthread_attr_getscope");

    printf("%sОбласть                    = %s\n", prefix,

            (i == PTHREAD_SCOPE_SYSTEM)  ? "PTHREAD_SCOPE_SYSTEM" :

            (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" :

            "???");

    s = pthread_attr_getinheritsched(attr, &i);

    if (s != 0)

        handle_error_en(s, "pthread_attr_getinheritsched");

    printf("%sУнаследованный планировщик = %s\n", prefix,

            (i == PTHREAD_INHERIT_SCHED)  ? "PTHREAD_INHERIT_SCHED" :

            (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" :

            "???");

    s = pthread_attr_getschedpolicy(attr, &i);

    if (s != 0)

        handle_error_en(s, "pthread_attr_getschedpolicy");

    printf("%sАлгоритм планирования      = %s\n", prefix,

            (i == SCHED_OTHER) ? "SCHED_OTHER" :

            (i == SCHED_FIFO)  ? "SCHED_FIFO" :

            (i == SCHED_RR)    ? "SCHED_RR" :

            "???");

    s = pthread_attr_getschedparam(attr, &sp);

    if (s != 0)

        handle_error_en(s, "pthread_attr_getschedparam");

    printf("%sПриоритет планирования     = %d\n", prefix, sp.sched_priority);

    s = pthread_attr_getguardsize(attr, &v);

    if (s != 0)

        handle_error_en(s, "pthread_attr_getguardsize");

    printf("%sРазмер защиты          = %zu bytes\n", prefix, v);

    s = pthread_attr_getstack(attr, &stkaddr, &v);

    if (s != 0)

        handle_error_en(s, "pthread_attr_getstack");

    printf("%sАдрес стека                = %p\n", prefix, stkaddr);

    printf("%sРазмер стека               = 0x%zx байт\n", prefix, v);
}
static void *
thread_start(void *arg)
{

    int s;

    pthread_attr_t gattr;

    /* pthread_getattr_np() — нестандартное расширение GNU,

       возвращает атрибуты нити, указанной в её

       первом аргументе */

    s = pthread_getattr_np(pthread_self(), &gattr);

    if (s != 0)

        handle_error_en(s, "pthread_getattr_np");

    printf("Атрибуты нити:\n");

    display_pthread_attr(&gattr, "\t");

    exit(EXIT_SUCCESS);         /* Завершить все нити */
}
int
main(int argc, char *argv[])
{

    pthread_t thr;

    pthread_attr_t attr;

    pthread_attr_t *attrp;      /* NULL или &attr */

    int s;

    attrp = NULL;

    /* Если в командной строке есть аргумент, то использовать его

       для задания атрибута размера стека и ещё некоторых других атрибутов

       нити, и attrp будет указывать на объект атрибутов нити */

    if (argc > 1) {

        int stack_size;

        void *sp;

        attrp = &attr;

        s = pthread_attr_init(&attr);

        if (s != 0)

            handle_error_en(s, "pthread_attr_init");

        s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED);

        if (s != 0)

            handle_error_en(s, "pthread_attr_setdetachstate");

        s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED);

        if (s != 0)

            handle_error_en(s, "pthread_attr_setinheritsched");

        stack_size = strtoul(argv[1], NULL, 0);

        s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size);

        if (s != 0)

            handle_error_en(s, "posix_memalign");

        printf("posix_memalign() выделен по адресу %p\n", sp);

        s = pthread_attr_setstack(&attr, sp, stack_size);

        if (s != 0)

            handle_error_en(s, "pthread_attr_setstack");

    }

    s = pthread_create(&thr, attrp, &thread_start, NULL);

    if (s != 0)

        handle_error_en(s, "pthread_create");

    if (attrp != NULL) {

        s = pthread_attr_destroy(attrp);

        if (s != 0)

            handle_error_en(s, "pthread_attr_destroy");

    }

    pause();    /* Завершается, когда другая нить вызывает exit() */
}
```

## СМОТРИТЕ ТАКЖЕ
pthread_attr_setaffinity_np(3), pthread_attr_setdetachstate(3), pthread_attr_setguardsize(3), pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3), pthread_attr_setscope(3), pthread_attr_setstack(3), pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3), pthread_create(3), pthread_getattr_np(3), pthread_setattr_default_np(3), pthreads(7)


title: pthread_attr_setaffinity_np(3)

text:
# pthread_attr_setaffinity_np(3)

## ИМЯ
pthread_attr_setaffinity_np, pthread_attr_getaffinity_np - изменяет/возвращает атрибут увязывания ЦП из объекта атрибутов нити

## ОБЗОР

```
#define _GNU_SOURCE             /* Смотрите feature_test_macros(7) */
#include <pthread.h>
```

```
int pthread_attr_setaffinity_np(pthread_attr_t *attr,
                   size_t cpusetsize, const cpu_set_t *cpuset);
int pthread_attr_getaffinity_np(const pthread_attr_t *attr,
                   size_t cpusetsize, cpu_set_t *cpuset);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_setaffinity_np() изменяет атрибут маски увязывания ЦП в объекте атрибутов нити, на который указывает attr, в значение cpuset. Данным атрибутом определяется маска увязывания ЦП у нити, созданной с учётом объекта атрибутов нити attr.

Функция pthread_attr_getaffinity_np() возвращает атрибут маски увязывания ЦП из объекта атрибутов нити, на который указывает attr, в буфер на который указывает cpuset.

В аргументе cpusetsize указывается длина буфера (в байтах), на который указывает cpuset. Обычно, этот аргумент должен задаваться как sizeof(cpu_set_t).

Дополнительную информацию по маскам увязывания ЦП смотрите в sched_setaffinity(2). Описание набора макросов, которые можно использовать для просмотра и изменения наборов ЦП, смотрите в CPU_SET(3).

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
EINVAL

(pthread_attr_setaffinity_np()) В cpuset указан ЦП, который находится вне набора поддерживаемых ядром (в параметре сборки ядра CONFIG_NR_CPUS определён диапазон для набора, поддерживаемого типом данных ядра, который используется для представления наборов ЦП).

EINVAL

(pthread_attr_getaffinity_np()) ЦП в маске увязывания из объекта атрибутов нити, на который указывает attr, находится вне диапазона, задаваемого cpusetsize (т. е., cpuset/cpusetsize слишком мал).

ENOMEM

(pthread_attr_setaffinity_np()) Невозможно выделить память.

## ВЕРСИИ
Эти функции определены в glibc начиная с версии 2.3.4.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setaffinity_np(), pthread_attr_getaffinity_np()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Данные функции являются не стандартизированными расширениями GNU, о чём свидетельствует наличие суффикса «_np» (nonportable).

## ЗАМЕЧАНИЯ
В glibc 2.3.3 версии этих функций не имеют аргумента cpusetsize. Вместо него размер набора ЦП, передаваемый используемым системным вызовам, всегда равен sizeof(cpu_set_t).

## СМОТРИТЕ ТАКЖЕ
sched_setaffinity(2), pthread_attr_init(3), pthread_setaffinity_np(3), cpuset(7), pthreads(7)


title: pthread_attr_setdetachstate(3)

text:
# pthread_attr_setdetachstate(3)

## ИМЯ
pthread_attr_setdetachstate, pthread_attr_getdetachstate - изменяет/возвращает из объекта атрибутов нити атрибут отключённости

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate);
int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_setdetachstate() изменяет атрибут состояния отключённости у объекта атрибутов нити, на который указывает attr, на значение, заданное в detachstate. Атрибутом состояния отключённости определяется, будет ли нить, созданная с объектом атрибутов нити attr, находиться в присоединяемом или отключённом состоянии.

В detachstate можно указать следующие значения:

PTHREAD_CREATE_DETACHED

Нити, создаваемые с attr, будут созданы в отключённом состоянии.

PTHREAD_CREATE_JOINABLE

Нити, создаваемые с attr, будут созданы в присоединяемом состоянии.

Значением по умолчанию для атрибута состояния отключённости в инициализируемом объекте атрибутов нити является PTHREAD_CREATE_JOINABLE.

Функция pthread_attr_getdetachstate() возвращает атрибут состояния отключённости нити у объекта атрибутов нити, на который указывает attr, в буфер на который указывает detachstate.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
Функция pthread_attr_setdetachstate() может завершиться со следующей ошибкой:

EINVAL

Указано неверное значение в detachstate.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setdetachstate(), pthread_attr_getdetachstate()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Дополнительную информацию об отключённых и присоединяемых нитях смотрите в pthread_create(3).

Нить, созданная в присоединяемом состоянии, должна быть в последствии присоединена с помощью pthread_join(3) или отключена с помощью pthread_detach(3); смотрите pthread_create(3).

Если указать ID нити, которая была создана в отключённом состоянии в вызове pthread_detach(3) или pthread_join(3), то возникает ошибка.

## ПРИМЕР
Смотрите pthread_attr_init(3).

## СМОТРИТЕ ТАКЖЕ
pthread_attr_init(3), pthread_create(3), pthread_detach(3), pthread_join(3), pthreads(7)


title: pthread_attr_setguardsize(3)

summary: изменяет/возвращает

text:
# pthread_attr_setguardsize(3)

## ИМЯ
pthread_attr_setguardsize, pthread_attr_getguardsize - изменяет/возвращает атрибут размера защиты у объекта атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize);
int pthread_attr_getguardsize(const pthread_attr_t *attr, size_t *guardsize);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_setguardsize() изменяет атрибут размера защиты у объекта атрибутов нити, на который указывает attr, в значение guardsize.

Если guardsize больше 0, то для каждой новой нити, созданной с использованием атрибута attr, система выделяет дополнительную область не менее guardsize байт в конце стека нити, которая служит как защитная область стека (но смотрите ДЕФЕКТЫ).

Если guardsize равно 0, то новые нити, создаваемые с использованием attr, не будут иметь защитной области.

Размер защиты по умолчанию совпадает с размером системной страницы.

Если в attr установлен атрибут адреса стека (с помощью pthread_attr_setstack(3) или pthread_attr_setstackaddr(3)), означающий, что вызывающий выделяет стек для нити, то атрибут размера защиты игнорируется (т. е., система не создаёт защитную область): само приложение должно обрабатывать переполнение стека (возможно, с помощью mprotect(2), для задания защитной области в конце выделенного стека).

Функция pthread_attr_getguardsize() возвращает атрибут размера защиты у объекта атрибутов нити, на который указывает attr, в буфер на который указывает guardsize.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
В POSIX.1 описана ошибка EINVAL при некорректном значении attr или guardsize. В Linux эти функции всегда выполняются успешно (тем не менее, в переносимых приложениях нужно учитывать возможность возврата ошибки).

## ВЕРСИИ
Эти функции доступны в glibc начиная с версии 2.1.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setguardsize(), pthread_attr_getguardsize()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Защитная область состоит из страниц виртуальной памяти, которые защищены от чтения и записи. Если нить переполнит свой стек и попадёт в защитную область, то на большинстве аппаратных архитектур она получит сигнал SIGSEGV и таким образом узнает о переполнении. Защитные области начинаются на границах страниц, а размер защиты внутри округляется до размера системной страницы при создании нити (тем не менее, функция pthread_attr_getguardsize() возвращает размер защиты, установленный pthread_attr_setguardsize()).

Установка размера защиты в нулевое значение полезно для экономии памяти в приложениях, которые создают много нитей и знают, что переполнение стека никогда не произойдёт.

Указание размера защиты больше чем размер по умолчанию может потребоваться для обнаружения переполнений стека при выделении в нити больших структур данных в стеке.

## ДЕФЕКТЫ
В glibc 2.8 реализация нитей NPTL добавляет защитную область к размеру выделяемого стека, а не выделяет дополнительное пространство в конце стека как требуется POSIX.1 (это может приводить к ошибке EINVAL в pthread_create(3), если значение размера защиты слишком большое и не оставляет место именно под стек).

Устаревшая реализация LinuxThreads делает это правильно, выделяя дополнительное пространство в конце стека под защитную область.

## ПРИМЕР
См. pthread_getattr_np(3).

## СМОТРИТЕ ТАКЖЕ
mmap(2), mprotect(2), pthread_attr_init(3), pthread_attr_setstack(3), pthread_attr_setstacksize(3), pthread_create(3), pthreads(7)


title: pthread_attr_setinheritsched(3)

text:
# pthread_attr_setinheritsched(3)

## ИМЯ
pthread_attr_setinheritsched, pthread_attr_getinheritsched - изменяет/возвращает атрибут наследования планировщика из объекта атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setinheritsched(pthread_attr_t *attr,
                                 int inheritsched);
int pthread_attr_getinheritsched(const pthread_attr_t *attr,
                                 int *inheritsched);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_setinheritsched() изменяет атрибут наследования планировщика у объекта атрибутов нити, на которую указывает attr, на значение, заданное в inheritsched. Атрибут наследования планировщика определяет будет ли нить, создаваемая с учётом объекта атрибутов нити attr, наследовать свои атрибуты планировщика от вызывающей нити или для этого будут использованы значения из attr.

Атрибуты планирования, на которые влияет атрибут наследования планировщика: алгоритм планирования (pthread_attr_setschedpolicy(3)), приоритет планирования (pthread_attr_setschedparam(3)) и область конкурирования (pthread_attr_setscope(3)).

В inheritsched можно указать следующие значения:

PTHREAD_INHERIT_SCHED

Нити, создаваемые с учётом attr, наследуют атрибуты планирования от создающей нити; атрибуты планирования attr игнорируются.

PTHREAD_EXPLICIT_SCHED

Нити, создаваемые с учётом attr, берут значения атрибутов планирования из указанного объекта атрибутов.

Значением по умолчанию для атрибута наследования планировщика в инициализируемом объекте атрибутов нити является PTHREAD_INHERIT_SCHED.

Функция pthread_attr_getinheritsched() возвращает атрибут наследования планировщика у объекта атрибутов нити, на который указывает attr, в буфер на который указывает inheritsched.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
Функция pthread_attr_setinheritsched() может завершиться со следующей ошибкой:

EINVAL

Некорректное значение inheritsched.

Для pthread_attr_setinheritsched() в POSIX.1 также описана необязательная ошибка ENOTSUP («попытка изменить атрибут на не поддерживаемое значение»).

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setinheritsched(), pthread_attr_getinheritsched()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ДЕФЕКТЫ
По состоянию на glibc 2.8, если объект атрибутов нити инициализирован с помощью pthread_attr_init(3), то алгоритму планирования в объекте атрибутов присваивается SCHED_OTHER, а приоритет планирования равен 0. Однако, если затем атрибут наследования планировщика устанавливается в PTHREAD_EXPLICIT_SCHED, то нить, создаваемая с учётом объекта атрибутов, неправильно наследует свои атрибуты планирования от создающей нити. Этот дефект не проявляется, если значение атрибута алгоритма планирования или приоритета планирования назначается явно в объекте атрибутов нити до вызова pthread_create(3).

## ПРИМЕР
Смотрите pthread_setschedparam(3).

## СМОТРИТЕ ТАКЖЕ
pthread_attr_init(3), pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3), pthread_attr_setscope(3), pthread_create(3), pthread_setschedparam(3), pthread_setschedprio(3), pthreads(7), sched(7)


title: pthread_attr_setschedparam(3)

summary: изменяет/возвращает

text:
# pthread_attr_setschedparam(3)

## ИМЯ
pthread_attr_setschedparam, pthread_attr_getschedparam - изменяет/возвращает атрибуты параметров планирования из объекта атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setschedparam(pthread_attr_t *attr,
                               const struct sched_param *param);
int pthread_attr_getschedparam(const pthread_attr_t *attr,
                               struct sched_param *param);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_setschedparam() изменяет атрибуты параметров планирования в объекте атрибутов нити, на который указывает attr, в значения из буфера, на который указывает param. Данными атрибутами определяются параметры планирования нити, созданной с учётом объекта атрибутов нити attr.

Функция pthread_attr_getschedparam() возвращает атрибуты параметров планирования у объекта атрибутов нити, на который указывает attr, в буфер на который указывает param.

Параметры планирования хранятся в структуре следующего вида:

```
struct sched_param {

    int sched_priority;     /* планируемый приоритет */
};
```

Из той структуры видно, что поддерживается только один параметр. Подробности о разрешённых диапазонах планируемых приоритетов для каждого алгоритма планирования смотрите в sched(7).

Для учёта значения параметра, заданного pthread_attr_setschedparam(), при вызове pthread_create(3), вызывающий должен использовать pthread_attr_setinheritsched(3) для присвоения атрибуту inherit-scheduler объекта атрибутов attr значения PTHREAD_EXPLICIT_SCHED.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
Функция pthread_attr_setschedparam() может завершиться со следующей ошибкой:

EINVAL

Приоритет, указанный в param, не имеет смысла при текущей политике планирования attr.

В POSIX.1 также описана ошибка ENOTSUP для pthread_attr_setschedparam(). Это значение никогда не возвращается Linux (тем не менее, в переносимых и новых приложениях нужно учитывать возможность возврата этого значения ошибки).

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setschedparam(), pthread_attr_getschedparam()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Список алгоритмов планирования для нитей, поддерживаемых в Linux смотрите в pthread_attr_setschedpolicy(3).

## ПРИМЕР
Смотрите pthread_setschedparam(3).

## СМОТРИТЕ ТАКЖЕ
sched_get_priority_min(2), pthread_attr_init(3), pthread_attr_setinheritsched(3), pthread_attr_setschedpolicy(3), pthread_create(3), pthread_setschedparam(3), pthread_setschedprio(3), pthreads(7), sched(7)


title: pthread_attr_setschedpolicy(3)

text:
# pthread_attr_setschedpolicy(3)

## ИМЯ
pthread_attr_setschedpolicy, pthread_attr_getschedpolicy - изменяет/возвращает атрибут политики планирования из объекта атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_setschedpolicy() изменяет атрибут политики планирования в объекте атрибутов нити, на который указывает attr, в значение policy. Данным атрибутом определяется политика планирования у нити, созданной с учётом объекта атрибутов нити attr.

Поддерживаемые значения policy: SCHED_FIFO, SCHED_RR и SCHED_OTHER, с семантикой, описанной в sched(7).

Функция pthread_attr_getschedpolicy() возвращает атрибут планирования нити у объекта атрибутов нити, на который указывает attr, в буфер на который указывает policy.

Для учёта значения политики, заданной pthread_attr_setschedpolicy(), при вызове pthread_create(3), вызывающий должен использовать pthread_attr_setinheritsched(3) для присвоения атрибуту inherit-scheduler объекта атрибутов attr значения PTHREAD_EXPLICIT_SCHED.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
Функция pthread_attr_setschedpolicy() может завершиться со следующей ошибкой:

EINVAL

Некорректное значение policy.

Для pthread_attr_setschedpolicy() в POSIX.1 также описана необязательная ошибка ENOTSUP («попытка изменить атрибут на не поддерживаемое значение»).

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setschedpolicy(), pthread_attr_getschedpolicy()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ПРИМЕР
Смотрите pthread_setschedparam(3).

## СМОТРИТЕ ТАКЖЕ
pthread_attr_init(3), pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3), pthread_create(3), pthread_setschedparam(3), pthread_setschedprio(3), pthreads(7), sched(7)


title: pthread_attr_setscope(3)

summary: изменяет/возвращает атрибут

text:
# pthread_attr_setscope(3)

## ИМЯ
pthread_attr_setscope, pthread_attr_getscope - изменяет/возвращает атрибут области конкурирования из объекта атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setscope(pthread_attr_t *attr, int scope);
int pthread_attr_getscope(const pthread_attr_t *attr, int *scope);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_setscope() изменяет атрибут области конкурирования (contention scope) в объекте атрибутов нити, на который указывает attr, в значение scope. Данным атрибутом определяется набор нитей, с которыми нить конкурирует за ресурсы (например ЦП). В POSIX.1 указаны два возможных значения scope:

PTHREAD_SCOPE_SYSTEM

Нить конкурирует за ресурсы со всеми нитями всех процессов системы, которые находятся в том же домене планирования выделения (группа из одного или нескольких процессоров). Нити с PTHREAD_SCOPE_SYSTEM запланированы друг относительно друга согласно их политике планирования и приоритета.

PTHREAD_SCOPE_PROCESS

Нить конкурирует за ресурсы со всеми нитями процесса, в котором она создана, и которые также созданы с областью конкурирования PTHREAD_SCOPE_PROCESS. Нити с PTHREAD_SCOPE_PROCESS запланированы относительно других нитей процесса согласно их политике планирования и приоритета. В POSIX.1 не указано как эти нити конкурируют с нитями из других процессов системы или с другими нитями того же процесса, которые созданы с областью конкурирования PTHREAD_SCOPE_SYSTEM.

В POSIX.1 от реализации требуется поддерживать, как минимум, одну из этих областей конкурирования. В Linux поддерживается PTHREAD_SCOPE_SYSTEM и не поддерживается PTHREAD_SCOPE_PROCESS.

В системах, где есть поддержка нескольких областей конкурирования, для учёта значения параметра, заданного pthread_attr_setscope(), при вызове pthread_create(3), вызывающий должен использовать pthread_attr_setinheritsched(3) для присвоения атрибуту inherit-scheduler объекта атрибутов attr значения PTHREAD_EXPLICIT_SCHED.

Функция pthread_attr_getscope() возвращает атрибут области конкурирования из объекта атрибутов нити, на который указывает attr, в буфер на который указывает scope.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
Вызов pthread_attr_setscope() может завершиться со следующими ошибками:

EINVAL

Указано неверное значение в scope.

ENOTSUP

Значение scope равно PTHREAD_SCOPE_PROCESS, которое не поддерживается в Linux.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setscope(), pthread_attr_getscope()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Область конкурирования PTHREAD_SCOPE_SYSTEM обычно означает, что нить пространства пользователя явно привязана к одной единице планирования ядра. В Linux это относится как к устаревшей реализации LinuxThreads так и к новой NPTL, в которых используется привязка нитей 1:1.

В POSIX.1 сказано, что значение по умолчанию для области конкурирования оставляется за реализацией.

## СМОТРИТЕ ТАКЖЕ
pthread_attr_init(3), pthread_attr_setaffinity_np(3), pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3), pthread_create(3), pthreads(7)


title: pthread_attr_setstack(3)

summary: изменяет/возвращает атрибуты

text:
# pthread_attr_setstack(3)

## ИМЯ
pthread_attr_setstack, pthread_attr_getstack - изменяет/возвращает атрибуты стека из объекта атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setstack(pthread_attr_t *attr,
                          void *stackaddr, size_t stacksize);
int pthread_attr_getstack(const pthread_attr_t *attr,
                          void **stackaddr, size_t *stacksize);
```

```
Компилируется и компонуется вместе с -pthread.
```

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

pthread_attr_getstack(), pthread_attr_setstack():

_POSIX_C_SOURCE >= 200112L

## ОПИСАНИЕ
Функция pthread_attr_setstack() изменяет атрибуты адреса и размера стека в объекте атрибутов нити, на который указывает attr, на значения, задаваемые в stackaddr и stacksize, соответственно. Данными атрибутами задаёт расположение и размер стека, который будет использоваться нитью, создаваемой с использованием объекта атрибутов нити attr.

Значение stackaddr должно указывать на самый младший адресуемый байт буфера из stacksize байт, выделенного вызывающим. Страницы выделенного буфера должны быть доступны на чтение и запись.

Функция pthread_attr_getstack() возвращает атрибуты адреса и размера стека из объекта атрибутов нити, на который указывает attr, в буфер, на который указывает stackaddr и stacksize, соответственно.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
Функция pthread_attr_setstack() может завершиться со следующей ошибкой:

EINVAL

Значение stacksize меньше PTHREAD_STACK_MIN (16384) байт. В некоторых системах эта ошибка также может возникать, если значения stackaddr или stackaddr + stacksize не выровнены правильным образом.

В POSIX.1 также описана ошибка EACCES, которая возникает, если область стека, определённая stackaddr и stacksize, недоступна вызывающему на чтение и запись.

## ВЕРСИИ
Эти функции определены в glibc начиная с версии 2.2.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setstack(), pthread_attr_getstack()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Эти функции нужны приложениям, в которых нужно размещать стек в определённом месте. В большинстве приложений это не нужно и эти функции использовать не стоит (используйте pthread_attr_setstacksize(3), если приложению нужно задать только размер стека, отличный от умолчательного).

Когда приложение использует pthread_attr_setstack(), оно самостоятельно выделяет место под стек. Защитный размер, задаваемый pthread_attr_setguardsize(3), игнорируется. Если его учитывать необходимо, то приложение должно самостоятельно выделять защитную область (одну или несколько страниц, защищённых от чтения и записи) для обработки возможного переполнения стека.

Адрес, указанный в stackaddr, должен быть выровнен соответствующим образом: для полной переносимости выравнивайте его по границе страницы (sysconf(_SC_PAGESIZE)). Для выделения полезно использовать функцию posix_memalign(3). Вероятно, значение stacksize также должно быть кратно размеру системной страницы.

Если attr используется при создании нескольких нитей, то вызывающий должен изменять атрибут адреса стека между вызовами pthread_create(3); в противном случае нити будут пытаться использовать одну и ту же область памяти для стека и возникнет хаос.

## ПРИМЕР
Смотрите pthread_attr_init(3).

## СМОТРИТЕ ТАКЖЕ
mmap(2), mprotect(2), posix_memalign(3), pthread_attr_init(3), pthread_attr_setguardsize(3), pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3), pthread_create(3), pthreads(7)


title: pthread_attr_setstackaddr(3)

summary: изменяет/возвращает

text:
# pthread_attr_setstackaddr(3)

## ИМЯ
pthread_attr_setstackaddr, pthread_attr_getstackaddr - изменяет/возвращает атрибут адреса стека у объекта атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr);
int pthread_attr_getstackaddr(const pthread_attr_t *attr, void **stackaddr);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Данные функции устарели: не используйте их. Используйте pthread_attr_setstack(3) и pthread_attr_getstack(3).

Функция pthread_attr_setstackaddr() изменяет атрибут адреса стека нити в объекте атрибутов нити, на который указывает attr, в значение stackaddr. Данным атрибутом задаётся расположение стека, который будет использоваться нитью, созданной с учётом объекта атрибутов нити attr.

Значение stackaddr должно указывать на буфер из, по крайней мере, PTHREAD_STACK_MIN байт, который был выделен вызывающим. Страницы выделенного буфера должны быть доступны на чтение и запись.

Функция pthread_attr_getstackaddr() возвращает атрибут адреса стека у объекта атрибутов нити, на который указывает attr, в буфер на который указывает stackaddr.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
Ошибок не предполагается (тем не менее, приложения должны обрабатывать возможную ошибку возврата).

## ВЕРСИИ
Эти функции доступны в glibc начиная с версии 2.1.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setstackaddr(), pthread_attr_getstackaddr()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
В POSIX.1-2001 эта функция определена, но объявлена устаревшей. В POSIX.1-2008 спецификация этих функций удалена.

## ЗАМЕЧАНИЯ
Не используйте эти функции! Они не являются переносимыми, так как не предоставляют возможности указать направление роста или диапазон стека. Например, для архитектур со стеком растущим вниз, в stackaddr указывается следующий адрес за самым верхним адресом выделяемой области стека, Однако для архитектур со стеком растущим вверх, в stackaddr указывается самый нижний адрес выделяемой области стека. area. В отличие от этого, значение stackaddr, используемое pthread_attr_setstack(3) и pthread_attr_getstack(3), всегда является указателем на самый нижний адрес в выделяемой области стека (а в аргументе stacksize указывается диапазон стека).

## СМОТРИТЕ ТАКЖЕ
pthread_attr_init(3), pthread_attr_setstack(3), pthread_attr_setstacksize(3), pthread_create(3), pthreads(7)


title: pthread_attr_setstacksize(3)

summary: изменяет/возвращает

text:
# pthread_attr_setstacksize(3)

## ИМЯ
pthread_attr_setstacksize, pthread_attr_getstacksize - изменяет/возвращает атрибут размера стека у объекта атрибутов нити

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize);
int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_attr_setstacksize() изменяет атрибут размера стека у объекта атрибутов нити, на который указывает attr, в значение stacksize.

Атрибутом размера стека определяется минимальный размер (в байтах), который будет выделен для нитей, созданных с учётом объекта атрибутов нити attr.

Функция pthread_attr_getstacksize() возвращает атрибут размера стека у объекта атрибутов нити, на который указывает attr, в буфер на который указывает stacksize.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
Функция pthread_attr_setstacksize() может завершиться со следующей ошибкой:

EINVAL

Размер стека меньше PTHREAD_STACK_MIN (16384) байт.

В некоторых системах pthread_attr_setstacksize() может завершиться ошибкой EINVAL, если значение stacksize не кратно размеру системной страницы.

## ВЕРСИИ
Эти функции доступны в glibc начиная с версии 2.1.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_attr_setstacksize(), pthread_attr_getstacksize()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
Подробную информацию о размере стека по умолчанию для новых нитей смотрите в pthread_create(3).

Размер стека нити не изменяется во время создания нити. Только главная нить может динамически увеличивать свой стек.

Функция pthread_attr_setstack(3) позволяет приложению изменять размер и положение стека вызывающего, который будет использован нитью.

## ДЕФЕКТЫ
Как указано в glibc 2.8, если указанное значение stacksize не кратно STACK_ALIGN (для большинства архитектур 16 байт), то оно может быть округлено в меньшую сторону, нарушая при этом POSIX.1, где говорится, что выделенный стек должен быть не менее stacksize байт.

## ПРИМЕР
Смотрите pthread_create(3).

## СМОТРИТЕ ТАКЖЕ
getrlimit(2), pthread_attr_init(3), pthread_attr_setguardsize(3), pthread_attr_setstack(3), pthread_create(3), pthreads(7)


title: pthread_cancel(3)

summary: посылает нити запрос отмены

text:
# pthread_cancel(3)

## ИМЯ
pthread_cancel - посылает нити запрос отмены

## ОБЗОР

```
#include <pthread.h>
```

```
int pthread_cancel(pthread_t thread);
```

```
Компилируется и компонуется вместе с -pthread.
```

## ОПИСАНИЕ
Функция pthread_cancel() посылает нити thread запрос отмены. Отреагирует нити назначения и когда на запрос отмены зависит от двух атрибутов, которые управляют этой нитью: состояние и тип возможности отмены.

Состояние отменяемости нити, определённое в pthread_setcancelstate(3), может быть включено (по умолчанию у новых нитей) или выключено. Если отменяемость у нити выключена, то запрос отменяемости остаётся в очереди до тех пор, пока нить не включит отменяемость. Если отменяемость у нити включена, то когда произойдёт отмена определяется типом отменяемости.

Тип отменяемости нити, определённый в pthread_setcanceltype(3), может быть асинхронным или отложенным (по умолчанию у новых нитей). Асинхронная отменяемость означает, что нить может быть отменена в любое время (обычно, немедленно, но система не гарантирует этого). Отложенная отменяемость означает, что отмена будет задержана до тех пор, пока нить не вызовет функцию, являющуюся точкой отмены. Список функций, которые могут быть точками отмены, представлен в pthreads(7).

Когда выполняется запрошенная отмена, для thread выполняются следующие шаги (в таком порядке):

1.

Отмена поднимает очищающие обработчики (в обратном порядке их регистрации) и они вызываются (смотрите pthread_cleanup_push(3)).

2.

Вызываются деструкторы данных нити, в неопределённом порядке (смотрите pthread_key_create(3)).

3.

Нить завершается (смотрите pthread_exit(3)).

Приведённые выше шаги выполняются асинхронно по отношению к вызову pthread_cancel(); возвращаемое pthread_cancel() состояние всего лишь информирует вызывающего, что запрос отмены успешно попал в очередь.

После завершения отменённой нити, при объединении с этой нитью с помощью pthread_join(3) возвращается PTHREAD_CANCELED в качестве состояния выхода (объединение с нитью — единственный способ узнать о завершении отмены).

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении pthread_cancel() возвращается 0; при ошибке возвращается ненулевой номер ошибки.

## ОШИБКИ
ESRCH

Нить с идентификатором thread не найдена.

## АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).

Интерфейс

Атрибут

Значение

pthread_cancel()

Безвредность в нитях

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
В Linux отменяемость реализована с помощью сигналов. В реализации нитей NPTL для этой цели используется первый сигнал реального времени (т. е., сигнал). В LinuxThreads используется второй сигнал реального времени (если сигналы реального времени доступны, в противном случае используется SIGUSR2).

## ПРИМЕР
Программа, представленная ниже, создаёт нить и затем отменяет её. Главная нить объединяется с отменённой нитью, чтобы получить состояние выхода PTHREAD_CANCELED. Далее представлен сеанс работы программы:

```
$ ./a.out
thread_func(): запущена; отмена выключена
main(): отправляем запрос отмены
thread_func(): для включения отмены
main(): нить была отменена
```

### Исходный код программы

```
#include <pthread.h>
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>
#define handle_error_en(en, msg) \

        do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
static void *
thread_func(void *ignored_argument)
{

    int s;

    /* выключаем отмена на некоторое время для того, чтобы

       запрос на отмену не сработал сразу же */

    s = pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);

    if (s != 0)

        handle_error_en(s, "pthread_setcancelstate");

    printf("thread_func(): запущена; отмена выключена\n");

    sleep(5);

    printf("thread_func(): для включения отмены\n");

    s = pthread_setcancelstate(PTHREAD_CANCEL_ENABLE, NULL);

    if (s != 0)

        handle_error_en(s, "pthread_setcancelstate");

    /* sleep() является точкой отмены */

    sleep(1000);        /* должна произойти отмена во время сна */

    /* не должно до сюда дойти */

    printf("thread_func(): не отменена!\n");

    return NULL;
}
int
main(void)
{

    pthread_t thr;

    void *res;

    int s;

    /* запускаем нить, а затем посылаем ей запрос отмены */

    s = pthread_create(&thr, NULL, &thread_func, NULL);

    if (s != 0)

        handle_error_en(s, "pthread_create");

    sleep(2);           /* даём время нити запуститься */

    printf("main(): посылаем запрос отмены\n");

    s = pthread_cancel(thr);

    if (s != 0)

        handle_error_en(s, "pthread_cancel");

    /* присоединяемся к нити для получения её кода выхода */

    s = pthread_join(thr, &res);

    if (s != 0)

        handle_error_en(s, "pthread_join");

    if (res == PTHREAD_CANCELED)

        printf("main(): нить была отменена\n");

    else

        printf("main(): нить не была отменена, чего быть не должно!)\n");

    exit(EXIT_SUCCESS);
}
```

## СМОТРИТЕ ТАКЖЕ
pthread_cleanup_push(3), pthread_create(3), pthread_exit(3), pthread_join(3), pthread_key_create(3), pthread_setcancelstate(3), pthread_setcanceltype(3), pthread_testcancel(3), pthreads(7)