getline(3)

الاسم
getline, getdelim - إدخال سلسلة محارف محددة

المكتبة
مكتبة سي المعيارية (libc، -lc)

موجز
#include <stdio.h>

ssize_t getline(char **restrict lineptr, size_t *restrict n,
                FILE *restrict stream);
ssize_t getdelim(char **restrict lineptr, size_t *restrict n,
                int delim, FILE *restrict stream);

    متطلبات ماكروات اختبار الميزات لـ glibc (انظر feature_test_macros(7)):

getline(), getdelim():
    منذ glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    قبل glibc 2.10:
        _GNU_SOURCE

الوصف
getline() تقرأ سطرًا كاملاً من stream، وتخزن عنوان المخزن المؤقت الذي يحتوي النص في *lineptr. يُنهى المخزن المؤقت بحرف فارغ ويتضمن حرف السطر الجديد، إذا وُجد.

إذا ضُبط *lineptr على NULL قبل الاستدعاء، فستخصص getline() مخزنًا مؤقتًا لتخزين السطر. يجب تحرير هذا المخزن المؤقت بواسطة برنامج المستخدم حتى لو فشلت getline().

بدلاً من ذلك، قبل استدعاء getline()، يمكن أن يحتوي *lineptr على مؤشر إلى مخزن مؤقت مخصص بواسطة malloc(3) بحجم *n بايت. إذا لم يكن المخزن المؤقت كبيرًا بما يكفي لاستيعاب السطر، فتعيد getline() تحجيمه باستخدام realloc(3)، وتُحدّث *lineptr و *n حسب الضرورة.

في كلتا الحالتين، عند استدعاء ناجح، يُحدّث *lineptr و *n ليعكسا عنوان المخزن المؤقت والحجم المخصص على التوالي.

تعمل getdelim() مثل getline()، باستثناء أنه يمكن تحديد محدد سطر غير السطر الجديد كوسيطة delimiter. كما هو الحال مع getline()، لا يُضاف حرف المحدد إذا لم يكن موجودًا في الإدخال قبل الوصول إلى نهاية الملف.

قيمة الإرجاع
عند النجاح، تُرجع getline() و getdelim() عدد المحارف المقروءة، بما في ذلك حرف المحدد، ولكن لا يشمل البايت الفارغ الختامي ('\0'). يمكن استخدام هذه القيمة للتعامل مع البايتات الفارغة المضمنة في السطر المقروء.

عند نهاية الملف، تُرجع كلتا الدالتين -1 مع تعيين مؤشر نهاية الملف لدفق الملف. عند الخطأ، تُرجع كلتا الدالتين -1 مع تعيين مؤشر خطأ دفق الملف، ويُضبط errno للإشارة إلى الخطأ.

إذا ضُبط *lineptr على NULL قبل الاستدعاء، فيجب تحرير المخزن المؤقت بواسطة برنامج المستخدم حتى عند الفشل.

الأخطاء

EINVAL
    وسائط سيئة (n أو lineptr هو NULL، أو stream غير صالح).

ENOMEM
    فشل تخصيص أو إعادة تخصيص المخزن المؤقت للسطر.

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

المعايير
POSIX.1-2008.

التاريخ
جنو، POSIX.1-2008.

أمثلة
    #define _GNU_SOURCE
    #include <stdio.h>
    #include <stdlib.h>

    int
    main(int argc, char *argv[])
    {
        FILE *stream;
        char *line = NULL;
        size_t size = 0;
        ssize_t nread;

        if (argc != 2) {
            fprintf(stderr, "Usage: %s <file>\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        stream = fopen(argv[1], "r");
        if (stream == NULL) {
            perror("fopen");
            exit(EXIT_FAILURE);
        }

        while ((nread = getline(&line, &size, stream)) != -1) {
            printf("Retrieved line of length %zd:\n", nread);
            fwrite(line, nread, 1, stdout);
        }

        free(line);
        fclose(stream);
        exit(EXIT_SUCCESS);
    }

انظر أيضًا
read(2), fgets(3), fopen(3), fread(3), scanf(3)

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

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

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