الدالة fseek() في PHP
(PHP 4, PHP 5, PHP 7)
تحرِّك الدالة fseek() مؤشِّر الملف الحالي إلى موقع محدَّد.
الوصف
int fseek ( resource $handle , int $offset [, int $whence = SEEK_SET ] )
تغيِّر هذه الدالة دليل موقع المؤشِّر للملف الذي يشير إليه المورد handle. يُحدَّد الموقع الجديد للمؤشِّر، والذي يقاس بالبايت انطلاقًا من بداية الملف، بإضافة قيمة الإزاحة offset إلى الموقع الذي يُحدِّده المعامل whence.
يُسمح عمومًا بالانتقال إلى موقعٍ يأتي بعد نهاية الملف (EOF). إن أُضيفت بيانات إلى ذاك الموقع، فإنَّ القراءة من المجال الذي لم تُكتب فيه البيانات والذي يقع بين نهاية الملف وموقع المؤشِّر المحدَّد سيؤدي إلى الحصول على بايتات ذات القيمة 0. مع ذلك، قد لا يدعم المجرى المستخدم في فتح الملف هذا الأمر خصوصًا إن كان نظام الملفات أو الوسيط المستخدم ذو حجم ثابت.
المعاملات
handle
مؤشِّر (pointer) يشير إلى ملف. يجب أن يكون سليمًا، ويشير إلى ملف فُتح بطريقة صحيحة باستعمال الدالة fopen().
offset
قيمة إزاحة موقع المؤشِّر بالبايت.
إن أردت تحريك المؤشِّر انطلاقًا من نهاية الملف، فمرِّر قيمة سالبة للمعامل offset ثمَّ حدِّد القيمة SEEK_END للمعامل whence.
whence
قيمة هذا المعامل هي إحدى القيم التالية:
SEEK_SET: تغيير موقع المؤشِّر إلى قيمة المعاملoffsetالمعطاة بالبايت.SEEK_CUR: تغيير موقع المؤشر إلى قيمة المعاملoffsetالمعطاة بالبايت مضافًا إليها قيمة موقع المؤشِّر الحالي.SEEK_END: تغيير موقع المؤشِّر إلى قيمة موقع نهاية الملف مضافًا إليها قيمة المعاملoffsetالمعطاة بالبايت.
القيم المعادة
تُعاد القيمة 0 عند نجاح العمليَّة. خلا ذلك، تُعاد القيمة -1.
أمثلة
المثال 1: استعمال الدالة fseek()
<?php
$fp = fopen('somefile.txt', 'r');
// قراءة بعض البيانات
$data = fgets($fp, 4096);
// إعادة المؤشر مجدَّدًا إلى بداية الملف
// rewind($fp) هذا مشابه تمامًا لاستعمال الدالة
fseek($fp, 0);
?>
ملاحظات
إن فتحت الملف في الوضع a أو الوضع a+، فستضاف جميع البيانات في نهاية الملف دومًا بغض النظر عن موقع مؤشِّر الملف الحالي وستكون حينئذٍ نتيجة استدعاء الدالة fseek() غير معروفة.
لا يدعم أي مجرى عمليَّة تتبع موقع المؤشر وتغييره. يمكن في تلك الحالة تغيير موقع المؤشر انطلاقًا من موقعه الحالي (أي استعمال القيمة SEEK_CUR) وذلك بقراءة البيانات وتجاهلها. أمَّا إن استُعملت أنواع أخرى لتتبع موقع المؤشر وتغييره، فستفشل هذه العمليَّة.
انظر أيضًا
- الدالة
ftell(): تعيد الموقع الحالي لمؤشِّر القراءة من أو الكتابة على الملف. - الدالة
rewind(): تُرجع المؤشِّر إلى موقع بداية الملف.