PTHREAD_SETNAME_NP(3)

ИМЯ
pthread_setname_np, pthread_getname_np - изменяет/возвращает имя нити

ОБЗОР
#define _GNU_SOURCE             /* смотрите feature_test_macros(7) */
#include <pthread.h>
int pthread_setname_np(pthread_t thread, const char *name);
int pthread_getname_np(pthread_t thread,
                       char *name, size_t len);

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

ОПИСАНИЕ
По умолчанию, все нити, созданные pthread_create(), наследуют имя программы. Функция pthread_setname_np() позволяет задать уникальное имя нити, которое можно использовать при отладки многонитевых приложений. Имя нити задаётся по правилам строк языка C, его длина ограничена 16 символами, включая конечный байт null ('\0'). В аргументе thread указывается нить, чьё имя будет изменено; в name указывается новое имя.

Функция pthread_getname_np() возвращает имя нити. В аргументе thread указывает нить, чьё имя будет возвращено. В буфер name возвращается имя нити; в аргументе len указывается количество байт, доступное в name. Длина буфера name должна быть не менее 16 символов. Возвращаемое имя в выходном буфере завершается байтом null.

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

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

ERANGE
    Длина строки, на которую ссылается name, превышает разрешённую.

Функция pthread_getname_np() может завершиться со следующей ошибкой:

ERANGE
    Буфер, задаваемый name и len, слишком мал для имени нити.

Если одна из этих функций завершается с ошибкой открытия /proc/self/task/[tid]/comm, то вызов может завершиться одной из ошибок, описанных в open(2).

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

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
pthread_setname_np(), pthread_getname_np() | Безвредность в нитях | MT-Safe

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

ЗАМЕЧАНИЯ
Запись pthread_setname_np() выполняет через файл нити comm из файловой системы /proc: /proc/self/task/[tid]/comm. Функция pthread_getname_np() также используется его для возврата имени.

ПРИМЕР

Представленная ниже программа показывает использование pthread_setname_np() и pthread_getname_np().

Пример сеанса работы с программой:

    $ ./a.out
    Нить создана. Имя по умолчанию: a.out
    Имя нити после изменения — THREADFOO.
    ^Z                           # Приостановка программы
    [1]+  Stopped           ./a.out
    $ ps H -C a.out -o 'pid tid cmd comm'
      PID   TID CMD                         COMMAND
     5990  5990 ./a.out                     a.out
     5990  5991 ./a.out                     THREADFOO
    $ cat /proc/5990/task/5990/comm
    a.out
    $ cat /proc/5990/task/5991/comm
    THREADFOO

  Исходный код программы
    #define _GNU_SOURCE
    #include <pthread.h>
    #include <stdio.h>
    #include <string.h>
    #include <unistd.h>
    #include <errno.h>
    #include <stdlib.h>
    #define NAMELEN 16
    #define errExitEN(en, msg) \
                do { errno = en; perror(msg); exit(EXIT_FAILURE); \
            } while (0)
    static void *
    threadfunc(void *parm)
    {
        sleep(5);          // позволить главной программе изменить имя нити
        return NULL;
    }
    int
    main(int argc, char **argv)
    {
        pthread_t thread;
        int rc;
        char thread_name[NAMELEN];
        rc = pthread_create(&thread, NULL, threadfunc, NULL);
        if (rc != 0)
            errExitEN(rc, "pthread_create");
        rc = pthread_getname_np(thread, thread_name, NAMELEN);
        if (rc != 0)
            errExitEN(rc, "pthread_getname_np");
        printf("Нить создана. Имя по умолчанию: %s\n", thread_name);
        rc = pthread_setname_np(thread, (argc > 1) ? argv[1] : "THREADFOO");
        if (rc != 0)
            errExitEN(rc, "pthread_setname_np");
        sleep(2);
        rc = pthread_getname_np(thread, thread_name,
                                (argc > 2) ? atoi(argv[1]) : NAMELEN);
        if (rc != 0)
            errExitEN(rc, "pthread_getname_np");
        printf("Имя нити после изменения — %s.\n", thread_name);
        rc = pthread_join(thread, NULL);
        if (rc != 0)
            errExitEN(rc, "pthread_join");
        printf("Done\n");
        exit(EXIT_SUCCESS);
    }

СМОТРИТЕ ТАКЖЕ
prctl(2), pthread_create(3), pthreads(7)