pthread_setname_np(3)

الاسم
pthread_setname_np, pthread_getname_np - ضبط/الحصول على اسم خيط

المكتبة
مكتبة مسالك POSIX (libpthread، -lpthread)

موجز
#define _GNU_SOURCE             /* انظر feature_test_macros(7) */
#include <pthread.h>

int pthread_setname_np(pthread_t thread, const char *name);
int pthread_getname_np(size_t size;
                       pthread_t thread, char name[size], size_t size);

الوصف
بشكل مبدئي، ترث جميع الخيوط المنشأة باستخدام pthread_create() اسم البرنامج. يمكن استخدام دالة pthread_setname_np() لضبط اسم فريد لخيط، وهو ما قد يكون مفيدًا لتصحيح تطبيقات متعددة الخيوط. اسم الخيط هو سلسلة محارف ذات معنى بلغة C، ويقتصر طولها على 16 حرفًا، بما في ذلك البايت الختامي الصفري ('\0'). تُحدد الوسيطة thread الخيط الذي سيُغيَّر اسمه؛ وتُحدد name الاسم الجديد.

يمكن استخدام دالة pthread_getname_np() لاسترجاع اسم الخيط. تُحدد الوسيطة thread الخيط الذي سيُسترجَع اسمه. يُستخدم المخزن المؤقت name لإرجاع اسم الخيط؛ وتُحدد size عدد البايتات المتاحة في name. يجب أن يكون المخزن المؤقت المُحدَّد بواسطة name بطول 16 حرفًا على الأقل. سيكون اسم الخيط المُرجَع في المخزن المؤقت للإخراج منتهيًا بصفر.

قيمة الإرجاع
عند النجاح، تُعيد هذه الدوال القيمة 0؛ وعند الخطأ، تُعيد رقم خطأ غير صفري.

الأخطاء
قد تفشل دالة pthread_setname_np() مع الخطأ التالي:

ERANGE
    يتجاوز طول السلسلة المُشار إليها بواسطة name الحد المسموح به.

قد تفشل دالة pthread_getname_np() مع الخطأ التالي:

ERANGE
    المخزن المؤقت المُحدَّد بواسطة name و size صغير جدًا لاحتواء اسم الخيط.

إذا فشلت أي من هاتين الدالتين في فتح /proc/self/task/tid/comm، فقد تفشل الاستدعاء مع أحد الأخطاء الموصوفة في open(2).

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
pthread_setname_np(), pthread_getname_np() | سلامة الخيوط | MT-Safe

المعايير
جنو؛ ومن هنا جاءت اللاحقة "_np" (غير منقول) في الأسماء.

التاريخ
glibc 2.12.

ملاحظات
تكتب pthread_setname_np() داخليًا إلى ملف comm الخاص بالخيط تحت نظام الملفات /proc: /proc/self/task/tid/comm. تسترجع pthread_getname_np() منه من نفس الموقع.

أمثلة
يوضح البرنامج أدناه استخدام pthread_setname_np() و pthread_getname_np().

تظهر جلسة الصدفة التالية تشغيلًا نموذجيًا للبرنامج:

    $ ./a.out;
    Created a thread.  Default name is: a.out
    The thread name after setting it is THREADFOO.
    ^Z                           # Suspend the program
    [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 <err.h>
    #include <errno.h>
    #include <pthread.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <unistd.h>

    #define NAMELEN 16

    static void *
    threadfunc(void *parm)
    {
        sleep(5);          // allow main program to set the thread name
        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)
            errc(EXIT_FAILURE, rc, "pthread_create");

        rc = pthread_getname_np(thread, thread_name, NAMELEN);
        if (rc != 0)
            errc(EXIT_FAILURE, rc, "pthread_getname_np");

        printf("Created a thread.  Default name is: %s\n", thread_name);
        rc = pthread_setname_np(thread, (argc > 1) ? argv[1] : "THREADFOO");
        if (rc != 0)
            errc(EXIT_FAILURE, rc, "pthread_setname_np");

        sleep(2);

        rc = pthread_getname_np(thread, thread_name, NAMELEN);
        if (rc != 0)
            errc(EXIT_FAILURE, rc, "pthread_getname_np");
        printf("The thread name after setting it is %s.\n", thread_name);

        rc = pthread_join(thread, NULL);
        if (rc != 0)
            errc(EXIT_FAILURE, rc, "pthread_join");

        printf("Done\n");
        exit(EXIT_SUCCESS);
    }

انظر أيضًا
prctl(2), pthread_create(3), pthreads(7)

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.