fseek(3)

الاسم
fgetpos, fseek, fsetpos, ftell, rewind - إعادة وضع دفق

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

موجز
#include <stdio.h>

int fseek(FILE *stream, long offset, int whence);
long ftell(FILE *stream);

void rewind(FILE *stream);

int fgetpos(FILE *restrict stream, fpos_t *restrict pos);
int fsetpos(FILE *stream, const fpos_t *pos);

الوصف
تضبط دالة fseek() مؤشر موضع الملف للدفق المشار إليه بـ stream. يُحصل على الموضع الجديد، المُقاس بالبايتات، بإضافة offset بايت إلى الموضع المُحدد بـ whence. إذا ضُبط whence على SEEK_SET أو SEEK_CUR أو SEEK_END، يكون الإزاحة نسبية إلى بداية الملف أو مؤشر الموضع الحالي أو نهاية الملف، على التوالي. يُزيل استدعاء ناجح لدالة fseek() مؤشر نهاية الملف للدفق ويُلغي أي تأثيرات لدالة ungetc(3) على نفس الدفق.

تحصل دالة ftell() على القيمة الحالية لمؤشر موضع الملف للدفق المشار إليه بـ stream.

تضبط دالة rewind() مؤشر موضع الملف للدفق المشار إليه بـ stream إلى بداية الملف. وهي مكافئة لـ:

    (void) fseek(stream, 0L, SEEK_SET)

باستثناء أنه يُمسح أيضًا مؤشر الخطأ للدفق (انظر clearerr(3)).

دالتا fgetpos() و fsetpos() هما واجهتان بديلتان مكافئتان لـ ftell() و fseek() (مع ضبط whence على SEEK_SET)، حيث تضبطان وتخزنان القيمة الحالية لإزاحة الملف في أو من الكائن المشار إليه بـ pos. في بعض الأنظمة غير UNIX، قد يكون كائن fpos_t كائنًا معقدًا وقد تكون هاتان الروتينان الطريقة الوحيدة لإعادة وضع دفق نصي بشكل محمول.

إذا أشار الدفق إلى ملف عادي وكانت إزاحة الدفق الناتجة تتجاوز حجم الملف، فستمتد الكتابات اللاحقة الملف بفجوة، حتى الإزاحة، قبل إيداع أي بيانات. انظر lseek(2) للتفاصيل حول دلالات البحث في الملف.

قيمة الإرجاع
لا تُرجع دالة rewind() أي قيمة. عند الإكمال الناجح، تُرجع fgetpos() و fseek() و fsetpos() القيمة 0، وتُرجع ftell() الإزاحة الحالية. وإلا، تُرجع -1 ويُضبط errno للإشارة إلى الخطأ.

الأخطاء

EINVAL
    لم يكن معامل whence لدالة fseek() هو SEEK_SET أو SEEK_END أو SEEK_CUR. أو: ستكون إزاحة الملف الناتجة سالبة.

ESPIPE
    وصف الملف الأساسي لـ stream غير قابل للبحث (مثلًا، يشير إلى أنبوب أو FIFO أو مقبس).

قد تفشل دوال fgetpos() و fseek() و fsetpos() و ftell() وتضبط errno لأي من الأخطاء المُحددة للروتينات fflush(3) و fstat(2) و lseek(2) و malloc(3).

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

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

التاريخ
POSIX.1-2001، C89.

انظر أيضًا
lseek(2), fseeko(3)

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

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

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