title: sem_init(3)

summary: инициализирует безымянный семафор

text:
# sem_init(3)

## ИМЯ
sem_init - инициализирует безымянный семафор

## ОБЗОР

```
#include <semaphore.h>
```

```
int sem_init(sem_t *sem, int pshared, unsigned int value);
```

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

## ОПИСАНИЕ
Функция sem_init() инициализирует безымянный семафор по адресу, указанному в sem. В аргументе value задаётся начальное значение семафора.

Аргументом pshared определяется, будет ли данный семафор доступен в нитях процесса или в разных процессах.

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

Если значение pshared не равно нулю, то семафор будет коллективно использоваться несколькими процессами, и должен располагаться в области общей памяти (смотрите shm_open(3), mmap(2) и shmget(2)) (так как потомок, создаваемый fork(2), наследует отображение памяти родителя, то ему также доступен и семафор). Любой процесс, имеющий доступ к области общей памяти, может обращаться к семафору с помощью sem_post(3), sem_wait(3) и т. п. функций.

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

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

## ОШИБКИ
EINVAL

Значение value превышает SEM_VALUE_MAX.

ENOSYS

Значение pshared не равно нулю, то система не поддерживает семафоры, коллективно используемые процессами (смотрите sem_overview(7)).

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

Интерфейс

Атрибут

Значение

sem_init()

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

MT-Safe

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

## ЗАМЕЧАНИЯ
Странно, но в POSIX.1-2001 не определено значение, которое должно возвращаться при успешном выполнении вызова sem_init(). В POSIX.1-2008 это исправлено: при успешном выполнении должен возвращаться ноль.

## СМОТРИТЕ ТАКЖЕ
sem_destroy(3), sem_post(3), sem_wait(3), sem_overview(7)


package: man-pages-ru

title: sem_open(3)

text:
# sem_open(3)

## ИМЯ
sem_open - инициализирует и открывает именованный семафор

## ОБЗОР

```
#include <fcntl.h>           /* константы O_* */
#include <sys/stat.h>        /* константы для mode */
#include <semaphore.h>
```

```
sem_t *sem_open(const char *name, int oflag);
sem_t *sem_open(const char *name, int oflag,
                mode_t mode, unsigned int value);
```

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

## ОПИСАНИЕ
Функция sem_open() создаёт новый семафор POSIX или открывает существующий семафор. Семафору присваивается имя name. Подробней об устройстве name смотрите sem_overview(7).

В аргументе oflag задаются флаги, которые управляют работой вызова (определения значений флагов можно получить включив <fcntl.h>). Если в oflag указано O_CREAT, то семафор создаётся, если ещё не существует. Владельцем (ID пользователя) семафора устанавливается эффективный ID пользователя вызывающего процесса. Владельцем группы (ID группы) устанавливается эффективный ID группы вызывающего процесса. Если в oflag указаны O_CREAT и O_EXCL одновременно и семафор с заданным name уже существует, то возвращается ошибка.

Если в oflag указано O_CREAT, то должны быть заданы ещё два аргумента. В аргументе mode задаются права для нового семафора, подобно open(2) (символические определения бит прав можно получить включив <sys/stat.h>). Настройки прав маскируются маской процесса. Права чтения и записи должны быть заданы для каждого класса пользователей, которым нужен доступ к семафору. В аргументе value задаётся начальное значение нового семафора. Если указан O_CREAT и семафор с заданным name существует, то mode и value игнорируются.

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

## ОШИБКИ
EACCES

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

EEXIST

В oflag указаны O_CREAT и O_EXCL, но семафор name уже существует.

EINVAL

Значение value было больше SEM_VALUE_MAX.

EINVAL

В name есть только «/», и нет других символов.

EMFILE

Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.

ENAMETOOLONG

Слишком длинное значение аргумента name.

ENFILE

Достигнуто максимальное количество открытых файлов в системе.

ENOENT

В oflag не указан O_CREAT и семафор name не существует; или указан O_CREAT, но name указан в некорректной форме.

ENOMEM

Недостаточно памяти.

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

Интерфейс

Атрибут

Значение

sem_open()

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

MT-Safe

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

## СМОТРИТЕ ТАКЖЕ
sem_close(3), sem_getvalue(3), sem_post(3), sem_unlink(3), sem_wait(3), sem_overview(7)


title: sem_post(3)

summary: разблокирует семафор

text:
# sem_post(3)

## ИМЯ
sem_post - разблокирует семафор

## ОБЗОР

```
#include <semaphore.h>
```

```
int sem_post(sem_t *sem);
```

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

## ОПИСАНИЕ
Функция sem_post() увеличивает (разблокирует) семафор, на который указывает sem. Если значение семафора после этого становится больше нуля, то другой процесс или нить заблокированная в вызове sem_wait(3), проснётся и заблокирует семафор.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении sem_post() возвращается 0; при ошибке значение семафора остаётся неизменным, возвращается -1, а в errno содержится код ошибки.

## ОШИБКИ
EINVAL

Значение sem не является корректным для семафора.

EOVERFLOW

Превышено максимально допустимое значение для семафора.

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

Интерфейс

Атрибут

Значение

sem_post()

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

MT-Safe

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

## ЗАМЕЧАНИЯ
Функция sem_post() безопасна для асинхронных сигналов: её можно использовать внутри обработчика сигналов.

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

## СМОТРИТЕ ТАКЖЕ
sem_getvalue(3), sem_wait(3), sem_overview(7), signal-safety(7)


title: sem_unlink(3)

summary: удаляет именованный семафор

text:
# sem_unlink(3)

## ИМЯ
sem_unlink - удаляет именованный семафор

## ОБЗОР

```
#include <semaphore.h>
```

```
int sem_unlink(const char *name);
```

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

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

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

## ОШИБКИ
EACCES

Вызывающий не имеет прав для удаления этого семафора.

ENAMETOOLONG

Слишком длинное значение аргумента name.

ENOENT

Семафор с указанным name отсутствует.

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

Интерфейс

Атрибут

Значение

sem_unlink()

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

MT-Safe

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

## СМОТРИТЕ ТАКЖЕ
sem_getvalue(3), sem_open(3), sem_post(3), sem_wait(3), sem_overview(7)


title: sem_wait(3)

summary: блокирует семафор

text:
# sem_wait(3)

## ИМЯ
sem_wait, sem_timedwait, sem_trywait - блокирует семафор

## ОБЗОР

```
#include <semaphore.h>
```

```
int sem_wait(sem_t *sem);
```

```
int sem_trywait(sem_t *sem);
```

```
int sem_timedwait(sem_t *sem, const struct timespec *abs_timeout);
```

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

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

sem_timedwait(): _POSIX_C_SOURCE >= 200112L

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

Функция sem_trywait() подобна sem_wait(), за исключением того, что если уменьшение нельзя выполнить сразу, то вызов завершается с ошибкой (errno становится равным EAGAIN), а не блокируется.

Функция sem_timedwait() подобна sem_wait(), за исключением того, что в abs_timeout задаётся ограничение по количеству времени, на которое вызов должен заблокироваться, если уменьшение невозможно выполнить сразу. Аргумент abs_timeout указывает на структуру, в которой задаётся абсолютное время ожидания в секундах и наносекундах, начиная с эпохи, 1970-01-01 00:00:00 +0000 (UTC). Эта структура определена следующим образом:

```
struct timespec {

    time_t tv_sec;      /* секунды */

    long   tv_nsec;     /* наносекунды [0 .. 999999999] */
};
```

Если на момент вызова время ожидания уже истекло и семафор нельзя заблокировать сразу, то sem_timedwait() завершается с ошибкой просрочки (errno становится равным ETIMEDOUT).

Если операцию можно выполнить сразу, то sem_timedwait() никогда не завершится с ошибкой просрочки, независимо от значения abs_timeout. Кроме того, в этом случае не проверяется корректность abs_timeout.

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

## ОШИБКИ
EINTR

Вызов был прерван обработчиком сигнала; смотрите signal(7).

EINVAL

Значение sem не является корректным для семафора.

В sem_trywait() может возникать следующая дополнительная ошибка:

EAGAIN

Операция не может быть выполнена без блокировки (т. е., значение семафор равно нулю).

В sem_timedwait() дополнительно могут возникать следующие ошибки:

EINVAL

Значение abs_timeout.tv_nsecs меньше 0, или больше или равно 1000 миллионов.

ETIMEDOUT

Истёк период ожидания в вызове раньше возможности блокировки семафора.

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

Интерфейс

Атрибут

Значение

sem_wait(), sem_trywait(), sem_timedwait()

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

MT-Safe

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

## ПРИМЕР
Программа (несколько упрощённая), показанная ниже, работает с безымянным семафором. Она ожидает два аргумента командной строки. В первом аргументе задаётся значение в секундах, которое используется в будильнике для генерации сигнала SIGALRM. Этот обработчик выполняет sem_post(3) для увеличения семафора, которого ждёт в main() вызов sem_timedwait(). Во втором аргументе задаётся период ожидания в секундах для sem_timedwait(). Далее показано что происходит в двух разных запусках программы:

```
$ ./a.out 2 3
About to call sem_timedwait()
sem_post() из обработчика
sem_timedwait() выполнена успешно
$ ./a.out 2 1
About to call sem_timedwait()
истекло время ожидания sem_timedwait()
```

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

```
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
#include <semaphore.h>
#include <time.h>
#include <assert.h>
#include <errno.h>
#include <signal.h>
sem_t sem;
#define handle_error(msg) \

    do { perror(msg); exit(EXIT_FAILURE); } while (0)
static void
handler(int sig)
{

    write(STDOUT_FILENO, "sem_post() из обработчика\n", 24);

    if (sem_post(&sem) == -1) {

        write(STDERR_FILENO, "ошибка sem_post()\n", 18);

        _exit(EXIT_FAILURE);

    }
}
int
main(int argc, char *argv[])
{

    struct sigaction sa;

    struct timespec ts;

    int s;

    if (argc != 3) {

        fprintf(stderr, "Использование: %s <alarm-secs> <wait-secs>\n",

                argv[0]);

        exit(EXIT_FAILURE);

    }

    if (sem_init(&sem, 0, 0) == -1)

        handle_error("sem_init");

    /* установка обработчика SIGALRM; зададим таймер будильника,

       используя argv[1] */

    sa.sa_handler = handler;

    sigemptyset(&sa.sa_mask);

    sa.sa_flags = 0;

    if (sigaction(SIGALRM, &sa, NULL) == -1)

        handle_error("sigaction");

    alarm(atoi(argv[1]));

    /* вычисляем относительный интервал как текущее время плюс

       количество секунд из argv[2] */

    if (clock_gettime(CLOCK_REALTIME, &ts) == -1)

        handle_error("clock_gettime");

    ts.tv_sec += atoi(argv[2]);

    printf("в main() вызывается sem_timedwait()\n");

    while ((s = sem_timedwait(&sem, &ts)) == -1 && errno == EINTR)

        continue;       /* перезапускаем, если прервано обработчиком */

    /* проверяем  что произошло */

    if (s == -1) {

        if (errno == ETIMEDOUT)

            printf("истекло время ожидания sem_timedwait()\n");

        else

            perror("sem_timedwait");

    } else

        printf("sem_timedwait() выполнена успешно\n");

    exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE);
}
```

## СМОТРИТЕ ТАКЖЕ
clock_gettime(2), sem_getvalue(3), sem_post(3), sem_overview(7), time(7)


setaliasent

title: setaliasent(3)

summary: читает запись о псевдониме

text:
# setaliasent(3)

## ИМЯ
setaliasent, endaliasent, getaliasent, getaliasent_r, getaliasbyname, getaliasbyname_r - читает запись о псевдониме

## ОБЗОР
\#include <aliases.h>

void setaliasent(void);

void endaliasent(void);

struct aliasent *getaliasent(void);

int getaliasent_r(struct aliasent *result,

char *buffer, size_t buflen, struct aliasent **res);

struct aliasent *getaliasbyname(const char *name);

int getaliasbyname_r(const char *name, struct aliasent *result,

char *buffer, size_t buflen, struct aliasent **res);

## ОПИСАНИЕ
Одной из баз данных, доступных в диспетчере службы имён (NSS), является база данных псевдонимов (aliases), в которой содержатся почтовые псевдонимы (для вывода поддерживаемых баз данных, запустите getent --help.) Для доступа к базе данных псевдонимов существуют шесть функций.

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

Функция setaliasent() возвращает файловый указатель в начало базы данных псевдонимов.

Функция endaliasent() закрывает базу данных псевдонимов.

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

Функция getaliasbyname() берёт имя из аргумента и ищет его в базе данных псевдонимов. Найденный элемент возвращается в виде указателя на struct aliasent.

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

Структура struct aliasent определена в <aliases.h>:

```
struct aliasent {

    char    *alias_name;             /* имя псевдонима */

    size_t   alias_members_len;

    char   **alias_members;          /* список имён псевдонима */

    int      alias_local;
};
```

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При ошибке функции getaliasent_r() и getaliasbyname_r() возвращают ненулевое значение.

## ФАЙЛЫ
По умолчанию файлом базы данных псевдонимов является /etc/aliases. Это можно изменить в файле /etc/nsswitch.conf.

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

Интерфейс

Атрибут

Значение

setaliasent(), endaliasent(), getaliasent_r(), getaliasbyname_r()

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

MT-Safe locale

getaliasent(), getaliasbyname()

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

MT-Unsafe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Эти функции есть только в glibc. В системе NeXT есть подобные функции:

```
#include <aliasdb.h>
void alias_setent(void);
void alias_endent(void);
alias_ent *alias_getent(void);
alias_ent *alias_getbyname(char *name);
```

## ПРИМЕР
Следующий пример компилируется командой gcc example.c -o example. Он выводит все имена из баз данных псевдонимов.

```
#include <aliases.h>
#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
int
main(void)
{

    struct aliasent *al;

    setaliasent();

    for (;;) {

        al = getaliasent();

        if (al == NULL)

            break;

        printf("Имя: %s\n", al->alias_name);

    }

    if (errno) {

        perror("чтение псевдонимов");

        exit(EXIT_FAILURE);

    }

    endaliasent();

    exit(EXIT_SUCCESS);
}
```

## СМОТРИТЕ ТАКЖЕ
getgrent(3), getpwent(3), getspent(3), aliases(5)


setbuf

title: setbuf(3)

summary: операции с буферизацией потока

text:
# setbuf(3)

## ИМЯ
setbuf, setbuffer, setlinebuf, setvbuf - операции с буферизацией потока

## ОБЗОР

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

```
void setbuf(FILE *stream, char *buf);
```

```
void setbuffer(FILE *stream, char *buf, size_t size);
```

```
void setlinebuf(FILE *stream);
```

```
int setvbuf(FILE *stream, char *buf, int mode, size_t size);
```

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

setbuffer(), setlinebuf():

начиная с glibc 2.19:

_DEFAULT_SOURCE

glibc 2.19 и старее:

_BSD_SOURCE

## ОПИСАНИЕ
Существует три типа буферизации: отсутствие буферизации, блочная буферизация и строковая буферизация. Когда выходной поток не буферизируется, то информация незамедлительно оказывается на терминале или в файле назначения; при блочной буферизации сначала сохраняется большое количество символов, а затем они записываются за один раз; при строковой буферизации все символы сохраняются в буфере до появления символа перевода строки при выводе или при вводе из любого потока, подключённого к устройству терминала (обычно, stdin). Функцию fflush(3) можно использовать для досрочного окончания блочной буферизации (смотрите fclose(3)).

Обычно, для файлов включена блочная буферизация. Если поток ссылается на терминал (обычно для stdout), то он буферизируется построчно. Стандартный поток ошибок stderr по умолчанию никогда не буферизируется.

Функция setvbuf() может быть использована для изменения типа буферизации любого открытого потока. Параметр mode должен быть одним из трёх следующих макросов:

_IONBF

отключить буферизацию

_IOLBF

строковая буферизация

_IOFBF

полная буферизация

За исключением небуферизованных файлов аргумент buf должен указывать на буфер размером, как минимум, size байт; этот буфер будет использоваться вместо текущего. Если аргумент buf равен NULL, то это отразится только на типе буферизации; при следующей операции чтения или записи будет создан новый буфер. Функция setvbuf() может быть использована только после открытия потока и до выполнения над ним любых операций.

Остальные три вызова, фактически, являются псевдонимами вызова setvbuf(). Функция setbuf() в точности соответствует вызову

setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

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

setvbuf(stream, NULL, _IOLBF, 0);

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функция setvbuf() возвращает 0 при нормальном завершении работы. При ошибках она возвращает ненулевое значение (некорректное значение mode или запрос невозможно выполнить). При ошибках может быть соответственно изменено значение errno.

Другие функции не возвращают никаких значений.

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

Интерфейс

Атрибут

Значение

setbuf(), setbuffer(), setlinebuf(), setvbuf()

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

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Функции setbuf() и setvbuf() соответствуют стандарту C89 и C99.

## ДЕФЕКТЫ
Вы должны удостовериться, что пространство, на которое указывает buf, всё ещё существует, в то время как stream закрыт, что обычно случается при закрытии программы. Например, следующее будет неправильным:

```
#include <stdio.h>
int
main(void)
{

    char buf[BUFSIZ];

    setbuf(stdin, buf);

    printf("Hello, world!\n");

    return 0;
}
```

## СМОТРИТЕ ТАКЖЕ
stdbuf(1), fclose(3), fflush(3), fopen(3), fread(3), malloc(3), printf(3), puts(3)


setenv

title: setenv(3)

text:
# setenv(3)

## ИМЯ
setenv - изменяет или добавляет переменную окружения

## ОБЗОР

```
#include <stdlib.h>
```

```
int setenv(const char *name, const char *value, int overwrite);
```

```
int unsetenv(const char *name);
```

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

setenv(), unsetenv():

_POSIX_C_SOURCE >= 200112L

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

## ОПИСАНИЕ
Функция setenv() добавляет переменную name в окружение со значением value, если name ещё не существует. Если name в окружении существует, то её значение изменяется на value, если overwrite имеет ненулевое значение; если overwrite равно нулю, то значение name не изменяется (и setenv() завершается без ошибки). Эта функция делает копию строк, указанных в name и value (в отличии от putenv(3)).

Функция unsetenv() удаляет переменную name из окружения. Если name в окружении не существует, то функция завершается без ошибки и окружение не изменяется.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении setenv() возвращает ноль, при ошибке возвращается -1, а в errno содержится код ошибки.

При успешном выполнении unsetenv() возвращает ноль, при ошибке возвращается -1, а в errno содержится код ошибки.

## ОШИБКИ
EINVAL

Значение name равно NULL, указывает на строку нулевой длины или содержащую символ '='.

ENOMEM

Недостаточно памяти для добавления новой переменной в окружение.

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

Интерфейс

Атрибут

Значение

setenv(), unsetenv()

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

MT-Unsafe const:env

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

## ЗАМЕЧАНИЯ
В POSIX.1 не требуется, чтобы setenv() или unsetenv() были реентерабельными.

До glibc 2.2.2, unsetenv() объявлялась как возвращающая void; более новые версии glibc следуют объявлению из POSIX.1, показанному в ОБЗОРЕ.

## ДЕФЕКТЫ
В POSIX.1 указано, что если name содержит символ '=', то setenv() должна завершаться с ошибкой EINVAL; однако версии glibc до 2.3.4 допускали знак '=' в name.

## СМОТРИТЕ ТАКЖЕ
clearenv(3), getenv(3), putenv(3), environ(7)


setjmp

title: setjmp(3)

summary: выполняет нелокальный переход

text:
# setjmp(3)

## ИМЯ
setjmp, sigsetjmp, longjmp, siglongjmp - выполняет нелокальный переход

## ОБЗОР

```
#include <setjmp.h>
```

```
int setjmp(jmp_buf env);
int sigsetjmp(sigjmp_buf env, int savesigs);
```

```
void longjmp(jmp_buf env, int val);
void siglongjmp(sigjmp_buf env, int val);
```

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

setjmp(): смотрите ЗАМЕЧАНИЯ.

sigsetjmp(): _POSIX_C_SOURCE

## ОПИСАНИЕ
Функции, описываемые в этой странице, используются для выполнения «нелокального goto»: передачи исполнения из одной функции в заранее определённое место другой. Функция setjmp() динамически устанавливает точку для будущей передачи исполнения, а longjmp() выполняет передачу исполнения.

Функция setjmp() сохраняет различную информацию об окружении вызова (обычно, указатель стека, указатель инструкции, значения других регистров и маску сигналов) в буфер env для последующего использования в longjmp(). В этом случае setjmp() возвращает 0.

Функция longjmp() использует информацию, сохранённую в env, для передачи управления обратно в точку, откуда была вызвана setjmp(), и восстанавливает («отматывает») стек до состояния на время вызова setjmp(). Также, в зависимости от реализации (смотрите ЗАМЕЧАНИЯ), значения некоторых регистров маска сигналов процесса могут быть восстановлены в их состояние на момент вызова setjmp().

После успешного вызова longjmp() выполнение продолжается как если бы setjmp() была вызвана второй раз. Этот «фиктивный» возврат можно распознать от настоящего вызова setjmp(), так как «фиктивный» возврат возвращает значение, указанное в val. Если программист ошибочно передаст значение 0 в val, то «фиктивный» возврат вернёт вместо него 1.

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

Если, и только если, аргумент savesigs, передаваемый в sigsetjmp(), не равен нулю, то текущая маска сигналов процесса сохраняется в env и будет восстановлена, если позднее будет запущена siglongjmp() с этим env.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции setjmp() и sigsetjmp() возвращают 0, если вызывают явно; при «фиктивном» возврате, который возникает после longjmp() или siglongjmp(), возвращается ненулевое значение, указанное в val.

Функции longjmp() и siglongjmp() не выполняют возврат.

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

Интерфейс

Атрибут

Значение

setjmp(), sigsetjmp()

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

MT-Safe

longjmp(), siglongjmp()

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

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
setjmp(), longjmp(): POSIX.1-2001, POSIX.1-2008, C89, C99.

sigsetjmp(), siglongjmp(): POSIX.1-2001, POSIX.1-2008.

## ЗАМЕЧАНИЯ
В POSIX не уточняется, должна ли setjmp() сохранять сигнальную маску (чтобы позднее восстановить её при longjmp()). В System V — не должна. В 4.3BSD сохранение выполняется и есть функция _setjmp, в которой этого не происходит. Поведение в Linux зависит от версии glibc и установленных макросов тестирования свойств. В Linux с glibc до версии 2.19 функция setjmp() по умолчанию ведёт себя как в System V, но можно включить поведение как в BSD, если определить макрос тестирования свойств _BSD_SOURCE и будут не определены _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _GNU_SOURCE или _SVID_SOURCE. Начиная с glibc 2.19, в <setjmp.h> представляется только версия System V для setjmp(). Если в программе нужно задействовать семантику BSD, замените вызовы setjmp() на вызовы sigsetjmp() с ненулевым аргументом savesigs.

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

Компилятор может оптимизировать переменные в регистрах и longjmp() может восстановить значения регистров помимо указателя стека и счётчика программы. Следовательно, значения автоматических переменных непредсказуемы после вызова longjmp(), если они удовлетворяют следующим критериям:

- они локальны для функции, которая сделала соответствующий вызов setjmp();

- их значения изменились между вызовами setjmp() и longjmp(); и

- они не объявлены как volatile.

Аналогичные замечания относятся и к siglongjmp().

### Нелокальные переходы и читаемость программы
Хотя этим и можно злоупотребить, обычный оператор C «goto» имеет преимущество в виде лексических отметок (оператор goto и метка перехода), которые позволяют программисту легко понять поток выполнения. Нелокальные переходы не имеют таких отметок: многократные вызовы setjmp() могут использовать одну переменную jmp_buf, то есть контекст переменной может изменяться на протяжении времени работы приложения. Следовательно, программисту придёт вчитываться в код для определения динамической точки перехода определённого вызова longjmp() (для облегчения жизни программиста в каждом вызове setjmp() должна использоваться уникальная переменная jmp_buf).

Дополнительная сложность: вызовы setjmp() и longjmp() даже могут быть в разных модулях исходного кода.

Таким образом, нелокальные переходы могут сделать программу тяжелее для понимания и поддержки, и, если это возможно, нужно использовать альтернативные варианты.

### Предостережения
Если функция, вызвавшая setjmp() завершилась до вызова longjmp(), то поведение не определено. Результатом может стать маленький (или не очень) хаос.

Если в многонитевой программе вызов longjmp() использует буфер env, инициализированный вызовом setjmp() в другой нити, то поведение не определено.

В POSIX.1-2008 Technical Corrigendum 2 вызовы longjmp() и siglongjmp() добавлены в список функций async-signal-safe. Однако стандарт рекомендует избегать использования этих функций в обработчиках сигналов и указывает, что если эти функции вызваны из обработчика сигналов, который прервал вызов функции не async-signal-safe (или её эквивалент, например шагам exit(3), который возникают при возврате из начального вызова main()), то поведение не определено, если программа далее вызывает функцию не async-signal-safe. Единственным способом избежать неопределённого поведения, является проверка следующего:

- После длинного перехода из обработчика сигналов программа не вызывает каких-либо функций не async-signal-safe и не возвращается из первоначального вызова в main().

- Любой сигнал, чей обработчик выполняет длинный переход, должен быть заблокирован на время каждого вызова функции не async-signal-safe и не вызывать функции не async-signal-safe после возврата из начального вызова в main().

## СМОТРИТЕ ТАКЖЕ
signal(7), signal-safety(7)


setlocale

title: setlocale(3)

summary: задаёт текущую локаль

text:
# setlocale(3)

## ИМЯ
setlocale - задаёт текущую локаль

## ОБЗОР

```
#include <locale.h>
```

```
char *setlocale(int category, const char *locale);
```

## ОПИСАНИЕ
Функция setlocale() используется для назначения или запроса текущей локали программы.

Если locale не равно NULL, то текущая локаль программы изменяется согласно переданным аргументам. Аргументом category определяется какую часть текущей локали программы нужно изменить.

Категория

Назначение

LC_ALL

Локаль целиком

LC_ADDRESS

Форматирование адресов и элементов, относящихся к географии (*)

LC_COLLATE

Сортировка строк

LC_CTYPE

Классы символов

LC_IDENTIFICATION

Метаданные, описывающие локаль (*)

LC_MEASUREMENT

Настройки, относящиеся к единицам измерения (метрические или системы мер США) (*)

LC_MESSAGES

Локализированные сообщения на родном языке

LC_MONETARY

Форматирование значений денежных единиц

LC_NAME

Форматирование приветствий людей (*)

LC_NUMERIC

Форматирование не денежных числовых значений

LC_PAPER

Настройки стандартных размеров бумаги (*)

LC_TELEPHONE

Форматы, используемые в телефонных службах (*)

LC_TIME

Форматирование значений дат и времени

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

Аргумент locale — это указатель на строку символов, содержащую требуемую настройку category. Эта строка может быть понятной константой «C» или «da_DK» (смотрите ниже), или строкой со скрытым форматом, которую вернул другой вызов setlocale().

Если locale — пустая строка, "", то любая часть локали, которую требуется изменить, будет задана исходя из переменных окружения. Как это происходит — зависит от реализации. В glibc, во-первых (независимо от category), просматривается переменная окружения LC_ALL, затем переменная окружения с именем как у категории (смотрите таблицу выше), и в конце учитывается переменная окружения LANG. Используется первая найденная переменная окружения. Если её значение некорректно определяет локаль, то локаль не изменяется и setlocale() возвращает NULL.

Локали "C" или "POSIX" являются переносимыми локалями; они существуют во всех соответствующих системах.

Имя локали, обычно, состоит из языка[_территории][таблицы символов][@модификатора], где язык — код языка согласно ISO 639, территория — код страны согласно ISO 3166 и таблица символов — набор символов или кодировка типа ISO-8859-1 или UTF-8. Список поддерживаемых локалей можно получить по команде «locale -a» (смотрите locale(1)).

Если locale равно NULL, то только возвращается текущая локаль и ничего не меняется.

При запуске основной программы по умолчанию выбирается переносимая локаль "C". Программу можно сделать переносимой для всех локалей вызвав

```
setlocale(LC_ALL, "");
```

после инициализации программы, используя информацию об установках локали, полученную из вызова localeconv(3), используя многобайтные или широкосимвольные функции при обработке текста, если MB_CUR_MAX > 1 и используя strcoll(3), wcscoll(3) или strxfrm(3), wcsxfrm(3) для сравнения строк.

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

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

Интерфейс

Атрибут

Значение

setlocale()

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

MT-Unsafe const:locale env

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

В стандарте C определены только следующие категории: LC_ALL, LC_COLLATE, LC_CTYPE, LC_MONETARY, LC_NUMERIC и LC_TIME. В POSIX.1 добавлена LC_MESSAGES. Остальные категории являются расширением GNU.

## СМОТРИТЕ ТАКЖЕ
locale(1), localedef(1), isalpha(3), localeconv(3), nl_langinfo(3), rpmatch(3), strcoll(3), strftime(3), charsets(7), locale(7)


setlogmask

title: setlogmask(3)

summary: изменяет маску приоритета журнала

text:
# setlogmask(3)

## ИМЯ
setlogmask - изменяет маску приоритета журнала

## ОБЗОР

```
#include <syslog.h>
```

```
int setlogmask(int mask);
```

## ОПИСАНИЕ
У процессов есть маска приоритета журнала, которая определяет, какие вызовы syslog(3) будут заноситься в журнал. Все остальные вызовы игнорируются. Протоколирование разрешено для приоритетов, для которых установлен соответствующий бит в mask. Начальная маска такова, что протоколирование разрешено для всех приоритетов.

Функция setlogmask() устанавливает маску для вызывающего процесса и возвращает предыдущую маску. Если аргумент маски равен 0, то текущая маска не изменяется.

Существует восемь приоритетов: LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_ERR, LOG_WARNING, LOG_NOTICE, LOG_INFO и LOG_DEBUG. Бит, соответствующий приоритету p, вычисляется как LOG_MASK(p). Некоторые системы также предоставляют макрос LOG_UPTO(p) для маски всех приоритетов вышеперечисленного списка плюс p.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функция возвращает предыдущую маску приоритета журнала.

## ОШИБКИ
Ничего.

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

Интерфейс

Атрибут

Значение

setlogmask()

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

MT-Unsafe race:LogMask

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

## СМОТРИТЕ ТАКЖЕ
closelog(3), openlog(3), syslog(3)


setnetgrent

title: setnetgrent(3)

summary: работа с

text:
# setnetgrent(3)

## ИМЯ
setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr - работа с элементами групп сетей

## ОБЗОР

```
#include <netdb.h>
```

```
int setnetgrent(const char *netgroup);
```

```
void endnetgrent(void);
```

```
int getnetgrent(char **host, char **user, char **domain);
```

```
int getnetgrent_r(char **host, char **user,
                  char **domain, char *buf, size_t buflen);
```

```
int innetgr(const char *netgroup, const char *host,
            const char *user, const char *domain);
```

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

setnetgrent(), endnetgrent(), getnetgrent(), getnetgrent_r(), innetgr():

начиная с glibc 2.19:

_DEFAULT_SOURCE

glibc 2.19 и старее:

_BSD_SOURCE || _SVID_SOURCE

## ОПИСАНИЕ
Файл netgroup впервые появился в SunOS. База данных netgroup представляет собой список строк с тремя элементами (hostname, username, domainname) или с другими именами netgroup. Любой из элементов тройки может быть пустым, то есть совпадает с любым значением. Описываемые здесь функции предоставляют доступ к базам данных netgroup. В файле /etc/nsswitch.conf задаётся какая база данных будет использована при поиске.

Вызов setnetgrent() настраивает netgroup, которая будет использована при поиске в последующих вызовах getnetgrent(). Функция getnetgrent() выбирает следующий элемент netgroup и возвращает указатели в host, user, domain. Указатель null означает, что соответствующая запись совпадает с любой строкой. Значения указателей корректны до тех пор, пока не произойдёт других вызовов функций работы с netgroup. Чтобы избежать этой проблемы вы можете использовать функцию GNU getnetgrent_r(), которая хранит строки в переданной ей буфере. Чтобы освободить все выделенные буферы используйте endnetgrent().

В большинстве случаев чаще всего проверяется присутствие тройки (hostname, username, domainname) в netgroup. Для этого можно использовать функцию innetgr() и не вызывать остальные три функции. Не забудьте, что указатель null — универсальный символ и совпадает с любой строкой. Функцию можно безопасно использовать в нитях.

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

## ФАЙЛЫ
/etc/netgroup

/etc/nsswitch.conf

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

Интерфейс

Атрибут

Значение

setnetgrent(), getnetgrent_r(), innetgr()

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

MT-Unsafe race:netgrent locale

endnetgrent()

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

MT-Unsafe race:netgrent

getnetgrent()

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

MT-Unsafe race:netgrent race:netgrentbuf locale

В приведённой выше таблице netgrent в race:netgrent означает, что если в нескольких нитях программы одновременно используются функции setnetgrent(), getnetgrent_r(), innetgr(), getnetgrent() или endnetgrent(), то может возникнуть состязательность по данным.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Эти функции отсутствуют в POSIX.1, но setnetgrent(), endnetgrent(), getnetgrent() и innetgr() доступны в большинстве систем UNIX. Функция getnetgrent_r() не так широко распространена в других системах.

## ЗАМЕЧАНИЯ
В реализации BSD функция setnetgrent() возвращает void.

## СМОТРИТЕ ТАКЖЕ
sethostent(3), setprotoent(3), setservent(3)


title: shm_open(3)

text:
# shm_open(3)

## ИМЯ
shm_open, shm_unlink - создаёт/открывает или удаляет объекты общей памяти POSIX

## ОБЗОР
\#include <sys/mman.h>

\#include <sys/stat.h> /* константы для mode */

\#include <fcntl.h> /* константы O_* */

int shm_open(const char *name, int oflag, mode_t mode);

int shm_unlink(const char *name);

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

## ОПИСАНИЕ
Функция shm_open() создаёт и открывает новый (или открывает уже существующий) объект общей памяти POSIX. Объект общей памяти POSIX — это описатель, используемый несвязанными процессами для выполнения mmap(2) для одной области общей памяти. Функция shm_unlink() выполняет обратную операцию, удаляя объект, созданный ранее с помощью shm_open().

Действие shm_open() аналогично open(2). Значением name определяется создаваемый или открываемый объект общей памяти. Для использования в переносимых программах объект общей памяти должен опознаваться по имени в виде /какое_то_имя, то есть строкой, оканчивающейся null и длиной до NAME_MAX (т.е., 255) символов, состоящей из начальной косой черты и одного или более символов (любых, кроме косой черты).

Аргумент oflag содержит маску битов, созданную логическим сложением OR одного из флагов O_RDONLY или O_RWDR и любых других флагов, перечисленных далее:

O_RDONLY

Открыть объект для чтения. Открытый таким образом объект общей памяти можно указывать в mmap(2) только для чтения (PROT_READ).

O_RDWR

Открыть объект для чтения и записи.

O_CREAT

Создать объект общей памяти, если он не существует. Владелец и группа объекта устанавливаются из соответствующих эффективных ID вызвавшего процесса, а биты прав на объект устанавливаются в соответствии с младшими 9 битами mode, за исключением того, что биты, установленные маске режима создания файла (см. umask(2)), очищаются у новых объектов. Набор макросов-констант, используемых для определения mode, описан в open(2). Символические определения этих констант можно получить включением <sys/stat.h>.

Новый объект общей памяти изначально имеет нулевую длину; размер объекта можно установить, используя ftruncate(2). Новые выделенные байты объекта общей памяти автоматически заполняются 0.

O_EXCL

Если также был указан O_CREAT и объект общей памяти с заданным name уже существует, то возвращается ошибка. Проверка существования объекта и его создание, если он не существует, выполняется атомарно.

O_TRUNC

Если объект общей памяти уже существует, то обрезать его до 0 байтов.

Определения значений этих флагов можно получить включением <fcntl.h>.

При успешном выполнении shm_open() возвращает новый файловый дескриптор, ссылающийся на объект общей памяти. Этот файловый дескриптор гарантированно будет дескриптором файла с самым маленьким номером среди ещё не открытых процессом. У дескриптора файла устанавливается флаг FD_CLOEXEC (см. fcntl(2)).

Дескриптор файла обычно используется в последующих вызовах ftruncate(2) (для новых объектов) и mmap(2). После вызова mmap(2) дескриптор файла может быть закрыт без влияния на отображение памяти.

Действие shm_unlink() аналогично unlink(2): оно удаляет имя объекта общей памяти и, как только все процессы завершили работу с объектом и отменили его отображение, очищает пространство и уничтожает связанную с ним область памяти. После успешного выполнения shm_unlink() попытка выполнить shm_open() для объекта с тем же именем name завершается ошибкой (если не был указан O_CREAT, в этом случае создаётся новый, уже другой объект).

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

## ОШИБКИ
При ошибках в errno записываются причины ошибки. Значения errno могут быть такими:

EACCES

Отказ в доступе для shm_unlink() для объекта общей памяти.

EACCES

Отказ в доступе для shm_open() с заданным name и режимом mode, или был указан O_TRUNC, а вызывающий не имеет прав на запись для объекта.

EEXIST

В shm_open() указаны O_CREAT и O_EXCL, но объект общей памяти name уже существует.

EINVAL

Аргумент name для shm_open() некорректен.

EMFILE

Было достигнуто ограничение по количеству открытых файловых дескрипторов на процесс.

ENAMETOOLONG

Длина name превышает PATH_MAX.

ENFILE

Достигнуто максимальное количество открытых файлов в системе.

ENOENT

Была сделана попытка выполнить shm_open() для несуществующего name и при этом не был указан O_CREAT.

ENOENT

Была сделана попытка выполнить shm_unlink() для несуществующего name.

## ВЕРСИИ
Эти функции присутствуют в glibc 2.2 и более новых.

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

Интерфейс

Атрибут

Значение

shm_open(), shm_unlink()

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

MT-Safe locale

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

В POSIX.1-2001 сказано, что группа-владелец нового объекта общей памяти устанавливается или в эффективный ID группы вызвавшего процесса, или «ID системной группы по умолчанию». В POSIX.1-2008 сказано, что группа-владелец может быть установлена или в эффективный ID группы вызвавшего процесса или, если объект видим в файловой системе, ID группы родительского каталога.

## ЗАМЕЧАНИЯ
POSIX оставляет неопределённым поведение при комбинации O_RDONLY и O_TRUNC. В Linux это приводит к успешному обрезанию существующего объекта общей памяти, но в других системах UNIX может быть по-другому.

Реализация объектов общей памяти POSIX в Linux использует выделенную файловую систему tmpfs(5), которая обычно монтируется в /dev/shm.

## СМОТРИТЕ ТАКЖЕ
close(2), fchmod(2), fchown(2), fcntl(2), fstat(2), ftruncate(2), memfd_create(2), mmap(2), open(2), umask(2), shm_overview(7)


siginterrupt

title: siginterrupt(3)

text:
# siginterrupt(3)

## ИМЯ
siginterrupt - разрешает сигналам прерывать системные вызовы

## ОБЗОР

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

```
int siginterrupt(int sig, int flag);
```

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

siginterrupt():

_XOPEN_SOURCE >= 500

|| /* начиная с glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

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

## ОПИСАНИЕ
Функция siginterrupt() изменяет поведение перезапуска когда системный вызов прерывается сигналом sig. Если аргумент flag ложен (0), то системные вызова будут перезапускаться, если они прерывались указанным сигналом sig. Это поведение Linux по умолчанию.

Если аргумент flag истинен (1) и не пересылались данные, то системный вызов, прерванный сигналом sig вернёт -1 и errno будет присвоено значение EINTR.

Если аргумент flag истинен (1) и началась пересылка данных, то системный вызов будет прерван и вернёт действительное количество пересланных данных.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении siginterrupt() возвращает ноль. Она возвращает -1, если был указан неправильный номер сигнала sig, ив errno будет указан код ошибки.

## ОШИБКИ
EINVAL

Задан некорректный номер сигнала.

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

Интерфейс

Атрибут

Значение

siginterrupt()

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

MT-Unsafe const:sigintr

## СООТВЕТСТВИЕ СТАНДАРТАМ
4.3BSD, POSIX.1-2001. В POSIX.1-2008 функция siginterrupt() помечена как устаревшая, вместо неё рекомендуется использовать sigaction(2) с флагом SA_RESTART.

## СМОТРИТЕ ТАКЖЕ
signal(2)


signbit

title: signbit(3)

text:
# signbit(3)

## ИМЯ
signbit - проверка знака вещественного числа с плавающей точкой

## ОБЗОР
\#include <math.h>

int signbit(x);

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

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

signbit():

_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

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

Это не подходит для x < 0.0, так как, согласно IEEE 754, спецификация плавающей точки допускает, что ноль может иметь знак. Сравнение -0.0 < 0.0 будет ложным, однако signbit(-0.0) вернет ненулевое значение.

Значение NaN и бесконечностей имеют бит знака.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Макрос signbit() возвращает ненулевое значение, если знак x отрицателен, иначе он возвращает ноль.

## ОШИБКИ
Ошибки не возникают.

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

Интерфейс

Атрибут

Значение

signbit()

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

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008, C99. Эта функция определена в IEC 559 (и в приложении с рекомендуемыми функциями IEEE 754/IEEE 854).

## СМОТРИТЕ ТАКЖЕ
copysign(3)


significand

title: significand(3)

summary: возвращает мантиссу числа с

text:
# significand(3)

## ИМЯ
significand, significandf, significandl - возвращает мантиссу числа с плавающей запятой

## ОБЗОР
\#include <math.h>

double significand(double x);

float significandf(float x);

long double significandl(long double x);

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

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

significand(), significandf(), significandl():

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

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

## ОПИСАНИЕ
Эти функции возвращают мантиссу x, приведённую к диапазону [1,2). Они эквивалентны

```
scalb(x, (double) -ilogb(x))
```

В основном, эта функция используется в определённых стандартизованных тестах для соответствия IEEE 754.

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

Интерфейс

Атрибут

Значение

significand(), significandf(), significandl()

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

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Эти функции являются нестандартными; в некоторых системах есть функция double.

## СМОТРИТЕ ТАКЖЕ
ilogb(3), scalb(3)


sigpause

title: sigpause(3)

text:
# sigpause(3)

## ИМЯ
sigpause - автоматически разблокирует сигналы и ждёт прерывания

## ОБЗОР

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

```
int sigpause(int sigmask);  /* BSD (но см. ЗАМЕЧАНИЯ) */
```

```
int sigpause(int sig);      /* System V / UNIX 95 */
```

## ОПИСАНИЕ
Не используйте эту функцию. Вместо неё используйте sigsuspend(2).

Функция sigpause() предназначена для ожидания какого-нибудь сигнала. Она изменяет сигнальную маску процесса (набор блокируемых сигналов) и ждёт появления сигнала. При прибытии сигнала первоначальная сигнальная маска восстанавливается.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Если sigpause() возвращает выполнение, то это означает, что она была прервана сигналом и возвращается значение -1, а errno присваивается значение EINTR.

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

Интерфейс

Атрибут

Значение

sigpause()

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

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Версия sigpause() из System V стандартизована в POSIX.1-2001. Также она есть в POSIX.1-2008, но помечена как устаревшая.

## ЗАМЕЧАНИЯ

### История
Классическая BSD-версия этой функции появилась в 4.2BSD. Она изменяет сигнальную маску процесса на sigmask. В UNIX 95 стандартизована несовместимая с System V версия этой функции, которая удаляет сигнальной маски процесса только указанный сигнал sig. Проблемная ситуация двух несовместимых функций с одним именем была исправлена функцией sigsuspend(2), которая ожидает аргумент с типом sigset_t * (вместо int).

### Замечания, касающиеся Linux
В Linux эта процедура является системным вызовом только на архитектуре Sparc (sparc64).

В glibc используется версия BSD, если определён макрос тестирования свойств _BSD_SOURCE и отсутствуют _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _GNU_SOURCE или _SVID_SOURCE. В противном случае используется версия System V и для получения объявления должен быть определен следующие макросы тестирования свойств:

- Начиная с glibc 2.26: _XOPEN_SOURCE >= 500

- glibc 2.25 и старее: _XOPEN_SOURCE

Начиная с glibc 2.19, в <signal.h> представлена только версия System V; в приложениях, которые использовали BSD-версию sigpause(), нужно заменить его на sigsuspend(2).

## СМОТРИТЕ ТАКЖЕ
kill(2), sigaction(2), sigprocmask(2), sigsuspend(2), sigblock(3), sigvec(3), feature_test_macros(7)


sigqueue

title: sigqueue(3)

text:
# sigqueue(3)

## ИМЯ
sigqueue - вставляет сигнал и данные в очередь процесса

## ОБЗОР
\#include <signal.h>

int sigqueue(pid_t pid, int sig, const union sigval value);

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

sigqueue(): _POSIX_C_SOURCE >= 199309L

## ОПИСАНИЕ
Вызов sigqueue() отправляет сигнал, указанный в sig, процессу с идентификатором PID, определённом в pid. Требуются определённые права для отправки сигнала, такие же как для kill(2). Как и в случае с kill(2), пустой сигнал (0) может использоваться для проверки того, что заданный PID вообще существует.

Аргумент value используется для указания сопутствующего элемента данных (либо целого, либо указателя), отправляемых сигналу, и имеет следующий тип:

```
union sigval {

    int   sival_int;

    void *sival_ptr;
};
```

Если у процесса, принимающего сигнал, установлен обработчик посредством sigaction(2) с флагом SA_SIGINFO, то он может получить данные через поле si_value структуры siginfo_t, передаваемой как второй аргумент для обработчика. Кроме этого, значение поля si_code этой структуры будет установлено в SI_QUEUE.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении sigqueue() возвращается 0, что означает, что сигнал попал в очередь принимающего процесса. При ошибке возвращается -1 и в errno содержится код ошибки.

## ОШИБКИ
EAGAIN

Достигнуто ограничение на количество сигналов в очереди (подробней об этом смотрите в signal(7)).

EINVAL

Значение sig некорректно.

EPERM

Процесс не имеет прав для отправки сигнала принимающему процессу. Требуемые права смотрите в kill(2).

ESRCH

Нет процесса с идентификатором PID, соответствующем указанному pid.

## ВЕРСИИ
Функция sigqueue() и используемый ей системный вызов rt_sigqueueinfo() впервые появились в Linux 2.2.

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

Интерфейс

Атрибут

Значение

sigqueue()

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

MT-Safe

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

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

### Отличия между библиотекой C и ядром
В Linux sigqueue() реализована через системный вызов rt_sigqueueinfo(2). Данный системный вызов отличается от неё третьим аргументом: структура siginfo_t, которая будет предоставляться обработчику сигнала принимающего процесса или возвращаться вызовом sigtimedwait(2) из принимающего процесса. В обёрточной функции glibc sigqueue() этот аргумент, uinfo, инициализируется следующим образом:

```
uinfo.si_signo = sig;      /* аргумент, передаваемый в sigqueue() */
uinfo.si_code = SI_QUEUE;
uinfo.si_pid = getpid();   /* ID процесса отправителя */
uinfo.si_uid = getuid();   /* реальный UID отправителя */
uinfo.si_value = val;      /* аргумент, передаваемый в sigqueue() */
```

## СМОТРИТЕ ТАКЖЕ
kill(2), rt_sigqueueinfo(2), sigaction(2), signal(2), pthread_sigqueue(3), sigwait(3), signal(7)


sigset

title: sigset(3)

summary: программный интерфейс сигналов System

text:
# sigset(3)

## ИМЯ
sigset, sighold, sigrelse, sigignore - программный интерфейс сигналов System V

## ОБЗОР
\#include <signal.h>

typedef void (*sighandler_t)(int);

sighandler_t sigset(int sig, sighandler_t disp);

int sighold(int sig);

int sigrelse(int sig);

int sigignore(int sig);

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

sigset(), sighold(), sigrelse(), sigignore():

_XOPEN_SOURCE >= 500

## ОПИСАНИЕ
Данные функции предоставляются glibc для совместимости с программами, в которых используются старый программный интерфейс сигналов System V. Данный программный интерфейс устарел: в новых приложениях нужно использовать программный интерфейс сигналов POSIX (sigaction(2), sigprocmask(2) и т.п.).

Функция sigset() изменяет обработку сигнала sig. В аргументе disp может быть указан адрес функции обработчика сигнала или одна из следующих констант:

SIG_DFL

Сбросить обработку sig в значение по умолчанию.

SIG_IGN

Игнорировать sig.

SIG_HOLD

Добавить sig в маску сигналов процесса, но оставить обработку sig неизменной.

Если в disp задан адрес обработчика сигналов, то при его выполнении sig добавляется в маску сигналов процесса.

Если в disp было указано значение отличное от SIG_HOLD, то sig удаляется из маски сигналов процесса.

Обработку сигналов SIGKILL и SIGSTOP невозможно изменить.

Функция sighold() добавляет sig в маску сигналов вызвавшего процесса.

Функция sigrelse() удаляет sig из маски сигналов вызвавшего процесса.

Функция sigignore() устанавливает обработку sig равной SIG_IGN.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении sigset() возвращает SIG_HOLD, если sig был заблокирован до вызова, или предыдущий обработчик сигнала, если блокировки не было. При ошибке sigset() возвращает -1, а errno записывает номер ошибки (но смотрите раздел ДЕФЕКТЫ далее).

При успешном выполнении функции sighold(), sigrelse() и sigignore() возвращают 0; при ошибке возвращается -1, а в errno — номер ошибки.

## ОШИБКИ
Для функции sigset() смотрите раздел ОШИБКИ в sigaction(2) и sigprocmask(2).

Для функции sighold() и sigrelse() смотрите раздел ОШИБКИ в sigprocmask(2).

Для функции sigignore() смотрите раздел ОШИБКИ в sigaction(2).

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

Интерфейс

Атрибут

Значение

sigset(), sighold(), sigrelse(), sigignore()

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

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Существует в SVr4, POSIX.1-2001, POSIX.1-2008. Эти функции устарели: не используйте их в новых программах. В POSIX.1-2008 функции sighold(), sigignore(), sigpause(3), sigrelse() и sigset() помечены как устаревшие, вместо них рекомендуется использовать sigaction(2), sigprocmask(2), pthread_sigmask(3) и sigsuspend(2).

## ЗАМЕЧАНИЯ
Данные функции впервые появились в glibc 2.1.

Тип sighandler_t является расширением GNU; в этой странице он используется только для более понятного описания прототипа sigset().

Функция sigset() предоставляет семантику надёжной обработки сигналов (как при вызове sigaction(2) с значением sa_mask равным 0).

В System V, функция signal() предоставляет ненадёжную семантику (как при вызове sigaction(2) со значением sa_mask равным SA_RESETHAND | SA_NODEFER). В BSD, signal() предоставляет надёжную семантику. В POSIX.1-2001 эти аспекты signal() не определены. Подробности смотрите в signal(2).

Для ожидания сигналов в BSD и System V предоставляется функция sigpause(3), но в других системах она описана с другим аргументом. Подробности смотрите в sigpause(3).

## ДЕФЕКТЫ
В версиях glibc до 2.2, sigset() не блокирует sig, если в disp было указано значение, отличное от SIG_HOLD.

В версиях glibc до 2.5, sigset() в двух случаях некорректно возвращает предыдущий обработчик сигнала. Во-первых, если disp равно SIG_HOLD, то при успешном выполнении sigset() всегда возвращается SIG_HOLD. Вместо этого должен возвращаться предыдущий обработчик сигнала (если сигнал не заблокирован, в этом случае должно возвращаться SIG_HOLD). Во-вторых, если сигнал в данный момент заблокирован, то возвращаемое значение успешного выполнения sigset() должно быть равно SIG_HOLD. Вместо этого возвращается предыдущий обработчик сигнала. Эти проблемы были устранены начиная с glibc 2.5.

## СМОТРИТЕ ТАКЖЕ
kill(2), pause(2), sigaction(2), signal(2), sigprocmask(2), raise(3), sigpause(3), sigvec(3), signal(7)


sigsetops

title: sigsetops(3)

summary: операции с

text:
# sigsetops(3)

## ИМЯ
sigemptyset, sigfillset, sigaddset, sigdelset, sigismember - операции с набором сигналов POSIX

## ОБЗОР
\#include <signal.h>

int sigemptyset(sigset_t *set);

int sigfillset(sigset_t *set);

int sigaddset(sigset_t *set, int signum);

int sigdelset(sigset_t *set, int signum);

int sigismember(const sigset_t *set, int signum);

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

sigemptyset(), sigfillset(), sigaddset(), sigdelset(), sigismember():

_POSIX_C_SOURCE

## ОПИСАНИЕ
Эти функции позволяют управлять наборами сигналов POSIX.

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

Функция sigfillset() инициализирует set максимальным значением, то есть все сигналы входят в набор.

Функция sigaddset() и sigdelset(), соответственно, добавляет и удаляет сигнал signum из set.

Функция sigismember() проверяет, является ли signum членом набора set.

Объекты типа sigset_t должны быть инициированы вызовом sigemptyset() или sigfillset() до передачи в функции sigaddset(), sigdelset() и sigismember(), или другие дополнительные функции glibc, описанные ниже (sigisemptyset(), sigandset() и sigorset()). Если этого не делать, то результат не определён.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении функции sigemptyset(), sigfillset(), sigaddset() и sigdelset() возвращают 0 и -1 при ошибке.

Функция sigismember() возвращает 1, если signum является членом набора set, 0, если signum не является членом и -1 при ошибке.

При ошибке эти функции изменяют значение errno соответствующим образом.

## ОШИБКИ
EINVAL

В signum задан неправильный сигнал.

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

Интерфейс

Атрибут

Значение

sigemptyset(), sigfillset(), sigaddset(), sigdelset(), sigismember(), sigisemptyset(), sigorset(), sigandset()

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

MT-Safe

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

## ЗАМЕЧАНИЯ
При создании заполненного набора сигналов функция glibc для sigfillset() не включает два сигнала реального времени, которые используются внутри реализации NPTL. Подробности смотрите в nptl(7).

### Расширения glibc
Если определён макрос тестирования свойств _GNU_SOURCE, то <signal.h> поставляет три другие функции для управления набором сигналов:

```
int sigisemptyset(const sigset_t *set);
int sigorset(sigset_t *dest, const sigset_t *left,
              const sigset_t *right);
int sigandset(sigset_t *dest, const sigset_t *left,
              const sigset_t *right);
```

Функция sigisemptyset() возвращает 1, если set не содержит сигналов и 0 в противном случае.

Функция sigorset() помещает объединение наборов left и right в dest. Функция sigandset() помещает пересечение наборов left и right в dest. При успешном выполнении обе функции возвращают 0 и -1 при ошибке.

Эти функции являются нестандартными (но в некоторых других системах имеют подобные)и их лучше не использовать в переносимых приложениях.

## СМОТРИТЕ ТАКЖЕ
sigaction(2), sigpending(2), sigprocmask(2), sigsuspend(2)


sigstack

title: sigstack(3)

text:
# sigstack(3)

See the file man2/sigaltstack.2.


sigvec

title: sigvec(3)

summary: программный интерфейс

text:
# sigvec(3)

## ИМЯ
sigvec, sigblock, sigsetmask, siggetmask, sigmask - программный интерфейс сигналов BSD

## ОБЗОР
\#include <signal.h>

int sigvec(int sig, const struct sigvec *vec, struct sigvec *ovec);

int sigmask(int signum);

int sigblock(int mask);

int sigsetmask(int mask);

int siggetmask(void);

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

Для всех функций, показанных выше:

Начиная с glibc 2.19:

_DEFAULT_SOURCE

в glibc 2.19 и старее:

_BSD_SOURCE

## ОПИСАНИЕ
Данные функции предоставляются glibc для совместимости с программами, в которых используются старый программный интерфейс сигналов BSD. Данный программный интерфейс устарел: в новых приложениях нужно использовать программный интерфейс сигналов POSIX (sigaction(2), sigprocmask(2) и т.п.).

Функция sigvec() назначает или возвращает обработчик сигнала sig (подобно POSIX sigaction(2)). Если vec не равно NULL, то это значение указывает на структуру sigvec, в которой определён новый обработчик для sig. Если ovec не равно NULL, то это значение указывает на структуру sigvec, которая используется для возврата предыдущего обработчика sig. Чтобы получить текущий обработчик sig без его изменения, укажите NULL в vec и не-null указатель в ovec.

Обработку сигналов SIGKILL и SIGSTOP невозможно изменить.

Структура sigvec описана следующим образом:

```
struct sigvec {

    void (*sv_handler)(int); /* обработчик сигнала */

    int    sv_mask;          /* сигналы для блокировки в обработчике */

    int    sv_flags;         /* флаги */
};
```

В поле sv_handler задаётся обработчик сигнала и это может быть: адрес функции сигнального обработчика; SIG_DFL, означающее, что к сигналу применяется обработчик по умолчанию; SIG_IGN, означающее, что сигнал игнорируется.

Если в sv_handler задан адрес обработчика сигнала, то в sv_mask задаётся маска сигналов, которые будут блокироваться на время выполнения обработчика. Также блокируется сигнал, для которого вызывается обработчик. Попытка заблокировать SIGKILL или SIGSTOP просто игнорируется.

Если в sv_handler задан адрес обработчика сигнала, то в поле sv_flags задаются флаги, контролирующие, что происходит при вызове обработчика. Это поле может содержать ноль или несколько следующих флагов:

SV_INTERRUPT

Если обработчик сигнала прерывает блокирующий системный вызов, то по окончании обработчика системный вызов не будет перезапущен: вместо этого он завершается ошибкой EINTR. Если этот флаг не указан, то по умолчанию системные вызовы перезапускаются.

SV_RESETHAND

Сбросить обработку сигнала в значение по умолчанию перед вызовом обработчика сигнала. Если этот флаг не указан, то обработчик остаётся установленным до его явного удаления позднее вызовом sigvec() или пока процесс не вызовет execve(2).

SV_ONSTACK

Обрабатывать сигнал в альтернативном стеке сигналов (исторически устанавливается в BSD с помощью устаревшей функции sigstack(); замена из POSIX — sigaltstack(2)).

Макрос sigmask() создаёт и возвращает «сигнальную маску» для signum. Например, мы можем инициализировать поле vec.sv_mask передаваемого в sigvec() с помощью такого кода:

```
vec.sv_mask = sigmask(SIGQUIT) | sigmask(SIGABRT);

            /* Блокировать SIGQUIT и SIGABRT при

               выполнении обработчика */
```

Функция sigblock() добавляет сигналы в mask в сигнальную маску процесса (подобно POSIX sigprocmask(SIG_BLOCK)) и возвращает старую сигнальную маску процесса. Попытка блокировать SIGKILL или SIGSTOP просто игнорируется.

Функция sigsetmask() устанавливает сигнальную маску процесса равной значению mask (подобно POSIX sigprocmask(SIG_SETMASK)) и возвращает старую сигнальную маску процесса.

Функция siggetmask() возвращает текущую сигнальную маску процесса. Этот вызов эквивалентен sigblock(0).

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

Функции sigblock() и sigsetmask() возвращают предыдущую сигнальную маску процесса.

Макрос sigmask() возвращает сигнальную маску для signum.

## ОШИБКИ
Смотрите раздел ОШИБКИ в sigaction(2) и sigprocmask(2).

## ВЕРСИИ
Начиная с версии 2.21, библиотека GNU C больше не экспортирует функцию sigvec() как часть программного интерфейса (для обеспечения обратной совместимости схема версий символов glibc продолжает экспортировать интерфейс для двоичного кода, скомпонованного со старыми версиями библиотеки).

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

Интерфейс

Атрибут

Значение

sigvec(), sigmask(), sigblock(), sigsetmask(), siggetmask()

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

MT-Safe

## СООТВЕТСТВИЕ СТАНДАРТАМ
Все эти функции появились из 4.3BSD, за исключением siggetmask(), чьё происхождение неясно. Эти функции устарели: не используйте их в новых программах.

## ЗАМЕЧАНИЯ
В 4.3BSD, функция signal() предоставляет надёжную семантику (как при вызове sigvec() со значением vec.sv_mask равным 0). В System V, signal() предоставляет ненадёжную семантику. В POSIX.1 эти аспекты signal() не определены. Подробности смотрите в signal(2).

Для ожидания сигналов в BSD и System V предоставляется функция sigpause(3), но в других системах она описана с другим аргументом. Подробности смотрите в sigpause(3).

## СМОТРИТЕ ТАКЖЕ
kill(2), pause(2), sigaction(2), signal(2), sigprocmask(2), raise(3), sigpause(3), sigset(3), signal(7)


sigwait

title: sigwait(3)

summary: ожидание сигнала

text:
# sigwait(3)

## ИМЯ
sigwait - ожидание сигнала

## ОБЗОР

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

```
 int sigwait(const sigset_t *set, int *sig);
```

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

sigwait():

начиная с glibc 2.26:

_POSIX_C_SOURCE >= 199506L

в glibc 2.25 и старее:

_POSIX_C_SOURCE

## ОПИСАНИЕ
Функция sigwait() приостанавливает выполнение вызвавшей нити до тех пор, пока в ожидании не появится сигнал из заданного набора сигналов set. Функция принимает сигнал (удаляет его из списка ожидающих сигналов) и возвращает номер сигнала в sig.

Действие sigwait() тоже, что и sigwaitinfo(2), за исключением:

- Функция sigwait() возвращает только номер сигнала, а не структуру siginfo_t, описывающую сигнал.

- Функции отличаются возвращаемыми значениями.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении sigwait() возвращает 0. При ошибке возвращается положительный номер ошибки (перечислены в разделе ОШИБКИ).

## ОШИБКИ
EINVAL

В set содержится некорректный номер сигнала.

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

Интерфейс

Атрибут

Значение

sigwait()

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

MT-Safe

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

## ЗАМЕЧАНИЯ
Функция sigwait() реализована с помощью sigtimedwait(2).

В реализации glibc sigwait() просто игнорирует попытки ожидания двух сигналов реального времени, которые используются внутри реализации NPTL. Подробности смотрите в nptl(7).

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

## СМОТРИТЕ ТАКЖЕ
sigaction(2), signalfd(2), sigpending(2), sigsuspend(2), sigwaitinfo(2), sigsetops(3), signal(7)


sin

title: sin(3)

summary: функция вычисления синуса

text:
# sin(3)

## ИМЯ
sin, sinf, sinl - функция вычисления синуса

## ОБЗОР

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

```
double sin(double x);
float sinf(float x);
long double sinl(long double x);
```

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

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

sinf(), sinl():

_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

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

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

## ОПИСАНИЕ
Эти функции возвращают синус от x, где x указан в радианах.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
В случае успеха эти функции возвращают синус от x.

Если x имеет значение NaN, будет возвращено NaN.

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

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

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

Ошибка области: x стремится к бесконечности

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

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

Интерфейс

Атрибут

Значение

sin(), sinf(), sinl()

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

MT-Safe

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

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

## ДЕФЕКТЫ
До версии 2.10 в реализации glibc при возникновении ошибки области errno не устанавливалось в значение EDOM.

## СМОТРИТЕ ТАКЖЕ
acos(3), asin(3), atan(3), atan2(3), cos(3), csin(3), sincos(3), tan(3)


sincos

title: sincos(3)

text:
# sincos(3)

## ИМЯ
sincos, sincosf, sincosl - одновременное вычисление синуса и косинуса

## ОБЗОР

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

```
void sincos(double x, double *sin, double *cos);
void sincosf(float x, float *sin, float *cos);
void sincosl(long double x, long double *sin, long double *cos);
```

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

## ОПИСАНИЕ
Некоторым приложениям необходимы значения синуса и косинуса одного и того же угла x. Эти функции вычисляют одновременно оба значения и сохраняют результаты в *sin и *cos. Использование этой функции может быть более эффективно, чем два отдельных вызова sin(3) и cos(3).

Если x имеет значение NaN, будет возвращено NaN для *sin и *cos.

Если x стремится к плюс бесконечности или минус бесконечности, то будет сгенерирована ошибка выхода за пределы области, а в качестве результата в *sin and *cos будет возвращено NaN.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Эти функции возвращают void.

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

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

Ошибка области: x стремится к бесконечности

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

Эти функции не изменяют errno.

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

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

Интерфейс

Атрибут

Значение

sincos(), sincosf(), sincosl()

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

MT-Safe

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

## ЗАМЕЧАНИЯ
Чтобы увидеть выгоду sincos() может потребоваться отключить встроенные оптимизации gcc(1) с помощью следующих флагов:

```
cc -O -lm -fno-builtin prog.c
```

## СМОТРИТЕ ТАКЖЕ
cos(3), sin(3), tan(3)


sinh

title: sinh(3)

text:
# sinh(3)

## ИМЯ
sinh, sinhf, sinhl - функция вычисления гиперболического синуса

## ОБЗОР

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

```
double sinh(double x);
float sinhf(float x);
long double sinhl(long double x);
```

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

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

sinhf(), sinhl():

_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

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

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

## ОПИСАНИЕ
Эти функции возвращают гиперболический синус от x, как это математически определено:

```
    sinh(x) = (exp(x) - exp(-x)) / 2
```

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
В случае успеха данные функции возвращают гиперболический синус от x.

Если x имеет значение NaN, будет возвращено NaN.

Если x равно +0 (-0), будет возвращено +0 (-0).

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

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

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

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

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

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

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

Интерфейс

Атрибут

Значение

sinh(), sinhf(), sinhl()

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

MT-Safe

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

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

## СМОТРИТЕ ТАКЖЕ
acosh(3), asinh(3), atanh(3), cosh(3), csinh(3), tanh(3)


sleep

title: sleep(3)

text:
# sleep(3)

## ИМЯ
sleep - приостанавливает выполнение на заданное число секунд

## ОБЗОР

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

```
unsigned int sleep(unsigned int seconds);
```

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

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Ноль, если запрошенное время истекло, или число секунд, оставшихся до пробуждения в случае, когда вызов был прерван обработчиком сигнала.

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

Интерфейс

Атрибут

Значение

sleep()

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

MT-Unsafe sig:SIGCHLD/linux

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

## ЗАМЕЧАНИЯ
В Linux sleep() реализована через вызов nanosleep(2). Описание задействованных часов смотрите в справочной странице nanosleep(2).

### Замечания о переносимости
В некоторых системах функция sleep() может быть реализована с помощью alarm(2) или SIGALRM (POSIX.1 это допускает); лучше не смешивать вызовы alarm(2) и sleep().

Использование longjmp(3) из обработчика сигнала или изменение обработки SIGALRM в момент сна может привести к непредсказуемым результатам.

## СМОТРИТЕ ТАКЖЕ
sleep(1), alarm(2), nanosleep(2), signal(2), signal(7)


sockatmark

title: sockatmark(3)

text:
# sockatmark(3)

## ИМЯ
sockatmark - определяет, есть ли в сокете отметка о внеполосных данных

## ОБЗОР
\#include <sys/socket.h>

int sockatmark(int sockfd);

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

sockatmark(): _POSIX_C_SOURCE >= 200112L

## ОПИСАНИЕ
Функция sockatmark() возвращает значение, показывающее присутствует ли в сокете, на который ссылается файловый дескриптор sockfd, отметка о внеполосных данных (out-of-band mark). Если сокет имеет отметку, то возвращается 1; если сокет не имеет отметки, то возвращается 0. Эта функция не удаляет отметку о внеполосных данных.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении sockatmark() возвращает 1, если сокет имеет отметку о внеполосных данных, и 0, если нет. При ошибке возвращается -1, и в errno записывается номер ошибки.

## ОШИБКИ
EBADF

Значение sockfd не является правильным файловым дескриптором.

EINVAL

Значение sockfd является файловым дескриптором, к которому не применима функция sockatmark().

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

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

Интерфейс

Атрибут

Значение

sockatmark()

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

MT-Safe

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

## ЗАМЕЧАНИЯ
Если sockatmark() возвращает 1, то внеполосные данные можно прочитать используя флаг MSG_OOB в recv(2).

Внеполосные данные поддерживаются только для некоторых потоковых сокетных протоколов.

Функцию sockatmark() можно безопасно вызывать из обработчика сигнала SIGURG.

Функция sockatmark() реализована с помощью ioctl(2) с операцией SIOCATMARK.

## ДЕФЕКТЫ
До glibc 2.4, sockatmark() не работала.

## ПРИМЕР
Следующий код можно использовать после получения сигнала SIGURG для чтения (и удаления) всех данных до отметки, и затем для чтения байта данных отметки:

```
    char buf[BUF_LEN];

    char oobdata;

    int atmark, s;

    for (;;) {

        atmark = sockatmark(sockfd);

        if (atmark == -1) {

            perror("sockatmark");

            break;

        }

        if (atmark)

            break;

        s = read(sockfd, buf, BUF_LEN);

        if (s == -1)

            perror("read");

        if (s <= 0)

            break;

    }

    if (atmark == 1) {

        if (recv(sockfd, &oobdata, 1, MSG_OOB) == -1) {

            perror("recv");

            ...

        }

    }
```

## СМОТРИТЕ ТАКЖЕ
fcntl(2), recv(2), send(2), tcp(7)


sqrt

title: sqrt(3)

summary: функция извлечения квадратного корня

text:
# sqrt(3)

## ИМЯ
sqrt, sqrtf, sqrtl - функция извлечения квадратного корня

## ОБЗОР

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

```
double sqrt(double x);
float sqrtf(float x);
long double sqrtl(long double x);
```

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

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

sqrtf(), sqrtl():

_ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

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

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

## ОПИСАНИЕ
Данные функции возвращают неотрицательный квадратный корень от x.

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

Если x имеет значение NaN, будет возвращено NaN.

Если x равно +0 (-0), будет возвращено +0 (-0).

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

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

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

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

Ошибка области: x меньше -0

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

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

Интерфейс

Атрибут

Значение

sqrt(), sqrtf(), sqrtl()

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

MT-Safe

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

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

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


statvfs

title: statvfs(3)

text:
# statvfs(3)

## ИМЯ
statvfs, fstatvfs - получение статистики по файловой системе

## ОБЗОР
\#include <sys/statvfs.h>

int statvfs(const char *path, struct statvfs *buf);

int fstatvfs(int fd, struct statvfs *buf);

## ОПИСАНИЕ
Функция statvfs() возвращает информацию о смонтированной файловой системе. path является путём любого файла, расположенного в смонтированной файловой системе. buf является указателем на структуру statvfs, определённую примерно следующим образом:

```
struct statvfs {

    unsigned long  f_bsize;    /* размер блока файловой системы */

    unsigned long  f_frsize;   /* размер фрагмента */

    fsblkcnt_t     f_blocks;   /* размер ФС в единицах f_frsize */

    fsblkcnt_t     f_bfree;    /* количество свободных блоков */

    fsblkcnt_t     f_bavail;   /* количество свободных блоков

                                  для непривилегированных пользователей */

    fsfilcnt_t     f_files;    /* количество inodes */

    fsfilcnt_t     f_ffree;    /* количество свободных inodes */

    fsfilcnt_t     f_favail;   /* количество свободных inodes

                                  для непривилегированных пользователей */

    unsigned long  f_fsid;     /* идентификатор файловой системы */

    unsigned long  f_flag;     /* параметры монтирования */

    unsigned long  f_namemax;  /* максимальная длина имени файла */
};
```

Типы fsblkcnt_t и fsfilcnt_t определены в файле <sys/types.h>. Для их определения используется тип unsigned long.

Значение поля f_flag — битовая маска различных параметров, которые были указаны при монтировании этой файловой системы. В нём содержится ноль или несколько следующих флагов:

ST_MANDLOCK

Разрешена обязательная (mandatory) блокировка файловой системы (смотрите fcntl(2)).

ST_NOATIME

Не обновлять времена доступа; смотрите mount(2).

ST_NODEV

Запретить доступ к специальным файлам устройств в этой файловой системе.

ST_NODIRATIME

Не обновлять времена доступа к каталогам; смотрите mount(2).

ST_NOEXEC

Исполнение программ в этой файловой системе запрещено.

ST_NOSUID

Биты set-user-ID и set-group-ID игнорируются в exec(3) для исполняемых файлов в этой файловой системе.

ST_RDONLY

Файловая система смонтирована в режиме только для чтения.

ST_RELATIME

Обновлять atime относительно mtime/ctime; смотрите mount(2).

ST_SYNCHRONOUS

Выполнять синхронную запись в файловую систему немедленно (смотрите описание O_SYNC в open(2)).

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

fstatvfs() возвращает такую же информацию об открытом файле через его ссылку на дескриптор fd.

## ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении возвращается 0. В случае ошибки возвращается -1, а errno устанавливается в соответствующее значение.

## ОШИБКИ
EACCES

(statvfs()) Нет права на поиск одного из компонентов префикса пути path (см. также path_resolution(7)).

EBADF

(fstatvfs()) fd не является корректным открытым дескриптором файла.

EFAULT

Buf или path указывает на неправильный адрес.

EINTR

Данный вызов был прерван сигналом; смотрите signal(7).

EIO

При чтении файловой системы произошла ошибка ввода-вывода.

ELOOP

(statvfs()) Было обнаружено слишком много символьных ссылок при трансляции path.

ENAMETOOLONG

(statvfs()) Слишком длинное значение аргумента path.

ENOENT

(statvfs()) Файл, указанный в path, не существует.

ENOMEM

Недостаточное количество памяти ядра.

ENOSYS

Файловая система не поддерживает данный вызов.

ENOTDIR

(statvfs()) Один из компонентов префикса пути path не является каталогом.

EOVERFLOW

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

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

Интерфейс

Атрибут

Значение

statvfs(), fstatvfs()

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

MT-Safe

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

В POSIX.1 в поле f_flag определены только флаги ST_NOSUID и ST_RDONLY. Чтобы получить определения остальных флагов нужно определить _GNU_SOURCE.

## ЗАМЕЧАНИЯ
Для поддержки данной библиотечной функции в ядре Linux есть системные вызовы statfs(2) и fstatfs(2).

В версиях glibc до 2.13, statvfs() заполняла биты поля f_flag сканируя параметры монтирования в /proc/mounts. Однако начиная с Linux 2.6.36, нижележащий системный вызов statfs(2) предоставляет необходимую информацию через поле f_flags, и начиная с glibc версии 2.13, функция statvfs() будет использовать информацию из этого поля, а не сканируя /proc/mounts.

Реализации функций в glibc

```
pathconf(path, _PC_REC_XFER_ALIGN);
pathconf(path, _PC_ALLOC_SIZE_MIN);
pathconf(path, _PC_REC_MIN_XFER_SIZE);
```

используют, соответственно, поля f_frsize, f_frsize и f_bsize, возвращаемые вызовом statvfs() с аргументом path.

## СМОТРИТЕ ТАКЖЕ
statfs(2)


stdarg

title: stdarg(3)

summary: работа со списком переменного

text:
# stdarg(3)

## ИМЯ
stdarg, va_start, va_arg, va_end, va_copy - работа со списком переменного количества аргументов

## ОБЗОР
\#include <stdarg.h>

void va_start(va_list ap, last);

type va_arg(va_list ap, type);

void va_end(va_list ap);

void va_copy(va_list dest, va_list src);

## ОПИСАНИЕ
Функцию можно вызвать передав ей произвольное количество аргументов разных типов. Во включаемом файле <stdarg.h> объявляется тип va_list и определяется три макроса для пошагового обхода списка аргументов, чьё количество и типы неизвестны вызываемой функции.

В вызываемой функции требуется объявить объект с типом va_list, который используется макросами va_start(), va_arg() и va_end().

### va_start()
Макрос va_start() инициализирует ap для последующего использования в va_arg()и va_end(), и должен вызываться первым.

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

Так как адрес этого аргумента может быть использован в макросе va_start(), он не должен быть объявлен как регистровая переменная, иметь тип функции или массива.

### va_arg()
Макрос va_arg() раскрывается в выражение, которое имеет тип и значение следующего аргумента в вызове. Аргумент ap — это va_list ap, инициализированный va_start(). Каждый вызов va_arg() изменяет ap так, что следующий вызов возвращает следующий аргумент. Аргумент type — это имя типа, указанное так, что тип указателя на объект, который имеет указанный тип, можно получить просто добавив * в type.

Первый вызов макроса va_arg() после va_start() вернёт аргумент после last. Последующие вызовы вернут значения оставшихся аргументов.

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

Если ap передан в функцию, которая использует va_arg(ap,type), то значение ap не определено после возврата из функции.

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

### va_copy()
Макрос va_copy() копирует (ранее инициализированный) список с переменным количеством аргументов src в dest. Его действие такое же, как если бы va_start() применили к dest с тем же аргументом last, после чего было бы совершено такое же количество вызовов va_arg(), которое имеется в текущем состоянии src.

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

```
va_list aq = ap;
```

К сожалению, есть системы, в которых это массив указателей (длиной 1), и нужно делать

```
va_list aq;
*aq = *ap;
```

Наконец, в системах, где аргументы передаются через регистры, в va_start() может потребоваться выделить память, сохранить там аргументы, а также индекс следующего элемента для того, чтобы va_arg() мог обойти список. Также va_end() может освобождать выделенную память. Чтобы всё это учесть в C99 добавлен макрос va_copy(), который позволяет показанное выше назначение заменить на

```
va_list aq;
va_copy(aq, ap);
...
va_end(aq);
```

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

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

Интерфейс

Атрибут

Значение

va_start(), va_end(), va_copy()

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

MT-Safe

va_arg()

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

MT-Safe race:ap

## СООТВЕТСТВИЕ СТАНДАРТАМ
Макросы va_start(), va_arg() и va_end() соответствуют C89. В C99 определён макрос va_copy().

## ДЕФЕКТЫ
В отличие от исторических макросов varargs, макросы stdarg не позволяют программистам создать функцию без постоянных аргументов. Эта проблема создаёт работу, в основном, при преобразовании кода varargs в код stdarg, а также есть сложности с функциями с переменным количеством аргументов, которым нужно передать все их аргументы в функцию в виде аргумента с типом va_list, например vfprintf(3).

## ПРИМЕР
Функция foo берёт строку с символами формата и печатает аргумент, связанный с каждым таким символом, на основе его типа.

```
#include <stdio.h>
#include <stdarg.h>
void
foo(char *fmt, ...)   /* «...» это синтаксис C для функции с

                         переменным количеством аргументов */
{

    va_list ap;

    int d;

    char c, *s;

    va_start(ap, fmt);

    while (*fmt)

        switch (*fmt++) {

        case 's':              /* строка */

            s = va_arg(ap, char *);

            printf("строка %s\n", s);

            break;

        case 'd':              /* int */

            d = va_arg(ap, int);

            printf("int %d\n", d);

            break;

        case 'c':              /* символ */

            /* здесь требуется преобразование, так как va_arg только

               с полностью описанными (promoted) типами */

            c = (char) va_arg(ap, int);

            printf("символ %c\n", c);

            break;

        }

    va_end(ap);
}
```


stdin

title: stdin(3)

summary: стандартные потоки ввода/вывода

text:
# stdin(3)

## ИМЯ
stdin, stdout, stderr - стандартные потоки ввода/вывода

## ОБЗОР

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

```
extern FILE *stdin;
extern FILE *stdout;
extern FILE *stderr;
```

## ОПИСАНИЕ
В обычном состоянии каждая программа UNIX после запуска имеет при открытых потока, один для ввода данных, один для вывода и один для печати диагностических сообщений или ошибок. Обычно, они присоединены к терминалу пользователя (смотрите tty(4)), но также они могут ссылаться на файлы или другие устройства, в зависимости от того, как это настроил родительский процесс (также смотрите раздел «Перенаправление (redirection)» в sh(1)).

Входной поток называют «стандартным вводом»; выходной поток называют «стандартным выводом»; поток ошибок называют «стандартным потоком ошибок». Эти термины в сокращённой форме (символы stdin, stdout и stderr) используются для обращения к соответствующим файлам.

Каждый из этих символов является макросом stdio(3) с типом указателя на FILE и может быть использован в функциях вроде fprintf(3) или fread(3).

Так как FILE — буферная обёртка вокруг файловых дескрипторов UNIX, файлы, на которые она ссылается, могут быть доступны через обычный низкоуровневый файловый интерфейс UNIX, то есть через функции read(2) и lseek(2).

При запуске программы с потоками stdin, stdout и stderr связываются целочисленные файловые дескрипторы 0, 1 и 2, соответственно. Для этих значений в <unistd.h> определены препроцессорные символы STDIN_FILENO, STDOUT_FILENO и STDERR_FILENO (с помощью freopen(3) у любого из этих потоков можно изменить номер файлового дескриптора, связанного с потоком).

Заметим, что одновременное использование FILE и низкоуровневых файловых дескрипторов может привести к непредсказуемым результатам и этого нужно избегать (для мазохистов: в POSIX.1, раздел 8.2.3, подробно описано как должно работать такое взаимодействие). Общее правило: файловые дескрипторы обрабатываются в ядре, а stdio всего лишь библиотека. Это означает, что, например, после exec(3) потомок наследует все открытые файловые дескрипторы, но все старые потоки становятся недоступными.

Так как символы stdin, stdout и stderr определены как макросы, присвоение им значения непереносимо. Стандартные потоки можно связать с различными файлами с помощью библиотечной функции freopen(3), специально созданной для переназначения stdin, stdout и stderr. Стандартные потоки закрываются вызовом exit(3) и при нормально завершении программы.

## СООТВЕТСТВИЕ СТАНДАРТАМ
Макросы stdin, stdout и stderr соответствуют C89 и этот стандарт также оговаривает, что три этих потока должны открываться при запуске программы.

## ЗАМЕЧАНИЯ
Поток stderr является небуферизованным. Поток stdout буферизируется построчно, если подключён к терминалу. Часть строки не появляется до тех пор, пока не будет вызвана функция fflush(3) или exit(3), или не появится символ новой строки. Это может приводить к неожиданным результатам, особенно при выводе диагностических сообщений. Режим буферизации стандартных потоков (или любого другого потока) модно изменить с помощью вызова setbuf(3) или setvbuf(3). Заметим, что в случае когда stdin связан с терминалом, также может быть буферизация ввода в драйвере терминала, никак не связанная с буферизацией stdio (более того, обычный терминальный ввод буферизируется построчно в ядре). Работу ядра по обработке ввода можно изменить с помощью вызова tcsetattr(3) и подобным; также смотрите stty(1) и termios(3).

## СМОТРИТЕ ТАКЖЕ
csh(1), sh(1), open(2), fopen(3), stdio(3)


stdio

title: stdio(3)

summary: библиотека функций стандартного ввода\-вывода

text:
# stdio(3)

## ИМЯ
stdio - библиотека функций стандартного ввода-вывода

## ОБЗОР
\#include <stdio.h>

FILE *stdin;

FILE *stdout;

FILE *stderr;

## ОПИСАНИЕ
Библиотеки стандартного ввода-вывода предоставляют простой и эффективный интерфейс буферизируемого потока ввода-вывода. Ввод и вывод представляется логическим потоком данных, а физические характеристики ввода-вывода скрываются. Далее приводится список функций и макросов; более подробная информация находится в соответствующих страницах.

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

Соотношение потока с файлом прекращается при закрытии файла. Перед прекращением потоки вывода очищаются (flushed) (содержимое незаписанного буфера передаётся в системное окружение). Значение указателя на объект FILE после закрытия файла становится неопределённым (мусорным).

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

При запуске программы предопределяются три текстовых потока, которые не следует открывать явно: стандартный ввод (standard input) (для чтения условного ввода), стандартный вывод (standard output) (для записи условного вывода) и стандартный поток ошибок (standard error) (для вывода диагностики). Сокращённые названия потоков: stdin, stdout и stderr. При открытии, стандартный поток ошибок буферизируется не полностью; стандартные потоки ввода и вывода полностью буферизируются только при условии, что они не ссылаются на какое-либо интерактивное устройство.

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

Библиотека stdio является частью библиотеки libc, а функции автоматически загружаются cc(1) по мере надобности. В разделе СИНТАКСИС справочных страниц указано какие файлы заголовков необходимо использовать, как выглядят объявления функций и какие внешние переменные представляют интерес для работы.

В списке далее перечислены макросы; эти имена не могут быть использованы повторно без предварительного удаления их определений с помощью #undef: BUFSIZ, EOF, FILENAME_MAX, FOPEN_MAX, L_cuserid, L_ctermid, L_tmpnam, NULL, SEEK_END, SEEK_SET, SEEK_CUR, TMP_MAX, clearerr, feof, ferror, fileno, getc, getchar, putc, putchar, stderr, stdin, stdout. Для feof, ferror, clearerr, fileno, getc, getchar, putc, и putchar существуют версии в виде функций, которые используются если определения макросов были удалены явно.

### Список функций
функция

описание

clearerr(3)

проверяет и сбрасывает состояние потока

fclose(3)

закрывает поток

fdopen(3)

функции для открытия потоков

feof(3)

проверяет и сбрасывает состояние потока

ferror(3)

проверяет и сбрасывает состояние потока

fflush(3)

сбрасывает поток

fgetc(3)

считывает следующий символ или слово из входного потока

fgetpos(3)

смена указания в потоке

fgets(3)

считывает строку из потока

fileno(3)

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

fopen(3)

функции для открытия потоков

fprintf(3)

вывод по формату

fpurge(3)

сбрасывает поток

fputc(3)

выводит символ или слово в поток

fputs(3)

выводит строку в поток

fread(3)

считывает двоичные данные потока ввода-вывода

freopen(3)

функции для открытия потоков

fscanf(3)

форматирует входные данные

fseek(3)

смена указания в потоке

fsetpos(3)

смена указания в потоке

ftell(3)

смена указания в потоке

fwrite(3)

считывает двоичные данные потока ввода-вывода

getc(3)

считывает следующий символ или слово из входного потока

getchar(3)

считывает следующий символ или слово из входного потока

gets(3)

считывает строку из потока

getw(3)

считывает следующий символ или слово из входного потока

mktemp(3)

создаёт имя временного файла (уникальное)

perror(3)

сообщения о системных ошибках

printf(3)

вывод по формату

putc(3)

выводит символ или слово в поток

putchar(3)

выводит символ или слово в поток

puts(3)

выводит строку в поток

putw(3)

выводит символ или слово в поток

remove(3)

удаляет запись из каталога

rewind(3)

смена указания в потоке

scanf(3)

форматирует входные данные

setbuf(3)

операции буферизации потока

setbuffer(3)

операции буферизации потока

setlinebuf(3)

операции буферизации потока

setvbuf(3)

операции буферизации потока

sprintf(3)

вывод по формату

sscanf(3)

форматирует входные данные

strerror(3)

сообщения о системных ошибках

sys_errlist(3)

сообщения о системных ошибках

sys_nerr(3)

сообщения о системных ошибках

tempnam(3)

функции для работы с временным файлом

tmpfile(3)

функции для работы с временным файлом

tmpnam(3)

функции для работы с временным файлом

ungetc(3)

возвращает символ во входной поток

vfprintf(3)

вывод по формату

vfscanf(3)

форматирует входные данные

vprintf(3)

вывод по формату

vscanf(3)

форматирует входные данные

vsprintf(3)

вывод по формату

vsscanf(3)

форматирует входные данные

## СООТВЕТСТВИЕ СТАНДАРТАМ
Библиотека stdio соответствует C89.

## СМОТРИТЕ ТАКЖЕ
close(2), open(2), read(2), write(2), stdout(3), unlocked_stdio(3)