نام (NAME)

inotifywait, fsnotifywait - انتظار برای تغییرات فایل‌ها با استفاده از inotify یا fanotify

خلاصه دستور (SYNOPSIS)

inotifywait [-hcmrPqIFS] [-e <event> ] [-t <seconds> ] [--format <fmt> ] [--timefmt <fmt> ] <file> [ ... ]

fsnotifywait [-hcmrPqIFS] [-e <event> ] [-t <seconds> ] [--format <fmt> ] [--timefmt <fmt> ] <file> [ ... ]

توضیحات (DESCRIPTION)

دستور inotifywait به‌طور پیش‌فرض با استفاده کارآمد از رابط inotify(7) لینوکس، منتظر تغییرات در فایل‌ها می‌ماند. این ابزار برای انتظار جهت تغییر فایل‌ها در اسکریپت‌های شل مناسب است. این ابزار می‌تواند به محض وقوع یک رویداد خارج شود، یا به‌طور پیوسته اجرا شده و رویدادها را هنگام وقوع در خروجی نمایش دهد.

دستور fsnotifywait مشابه inotifywait است اما به‌طور پیش‌فرض از رابط fanotify(7) لینوکس استفاده می‌کند. در صورت تعیین صریح، از رابط inotify(7) استفاده خواهد کرد.

خروجی (OUTPUT)

دستورهای inotifywait و fsnotifywait اطلاعات عیب‌یابی را روی خطای استاندارد و اطلاعات رویداد را روی خروجی استاندارد چاپ می‌کنند. خروجی رویداد قابل پیکربندی است، اما به‌طور پیش‌فرض از خطوطی با قالب زیر تشکیل شده است:

watched_filename EVENT_NAMES event_filename

watched_filename: نام فایلی است که رویداد روی آن رخ داده است. اگر فایل یک دایرکتوری باشد، یک ممیز (اسلش) انتهایی در خروجی درج می‌شود.
EVENT_NAMES: نام رویدادهای inotify رخ‌داده هستند که با کاما از یکدیگر جدا شده‌اند.
event_filename: تنها زمانی در خروجی نمایش داده می‌شود که رویداد روی یک دایرکتوری رخ داده باشد؛ در این حالت، نام فایلی در داخل دایرکتوری که باعث این رویداد شده است در خروجی درج می‌گردد.
به‌طور پیش‌فرض، نویسه‌های خاص درون نام فایل‌ها به هیچ وجه گریز داده نمی‌شوند (escape نمی‌شوند). این مسئله می‌تواند تجزیه خروجی inotifywait را در اسکریپت‌های awk یا موارد مشابه دشوار کند. گزینه‌های --csv و --format در این موارد مفید خواهند بود.

گزینه‌ها (OPTIONS)

-h, --help: نمایش اطلاعات راهنمای استفاده از دستور.
@<file>: هنگام پایش بازگشتی یک درخت دایرکتوری، فایل مشخص‌شده را از نظارت مستثنی می‌کند. این فایل باید با مسیر نسبی یا مطلق، متناسب با نحوه مشخص‌شدن دایرکتوری‌های تحت نظارت (نسبی یا مطلق)، تعیین گردد. اگر یک مسیر خاص صراحتاً هم مشمول و هم مستثنی شده باشد، همواره تحت نظارت باقی خواهد ماند.
نکته: اگر می‌خواهید دایرکتوری یا فایلی را پایش کنید که نام آن با @ شروع می‌شود، مسیر مطلق آن را مشخص نمایید.
--fromfile <file>: خواندن نام فایل‌های تحت پایش یا موارد استثنا از یک فایل، به صورت یک نام فایل در هر خط. اگر نام فایل‌ها با @ آغاز شوند، مطابق توضیحات بالا مستثنی می‌گردند. اگر مقدار <file> برابر با `-' باشد، نام فایل‌ها از ورودی استاندارد خوانده می‌شوند. از این گزینه زمانی استفاده کنید که تعداد فایل‌های مورد نیاز برای پایش، بیشتر از ظرفیت پذیرش آرگومان‌های خط فرمان باشد.
-m, --monitor: به جای خروج پس از دریافت یک رویداد منفرد، اجرای نامحدود خواهد داشت. رفتار پیش‌فرض این است که برنامه پس از وقوع نخستین رویداد خارج شود.
-d, --daemon: مشابه --monitor است، با این تفاوت که در پس‌زمینه اجرا شده و رویدادها را در فایلی که الزاماً باید توسط --outfile تعیین شود ثبت می‌کند. مستلزم گزینه --syslog است.
-o, --outfile <file>: ارسال رویدادها به خروجی <file> به جای stdout.
-s, --syslog: ارسال خطاها به ماژول گزارش وقایع سیستم syslog(3) به جای stderr.
-P, --no-dereference: عدم دنبال کردن پیوندهای نمادین (symlinks).
-r, --recursive: نظارت بر تمام زیردایرکتوری‌های مربوط به دایرکتوری‌های ارائه‌شده به عنوان آرگومان. نظارت‌ها به صورت بازگشتی و تا عمق نامحدود برقرار خواهند شد. پیوندهای نمادین پیمایش نمی‌شوند. زیردایرکتوری‌های تازه‌ساخته‌شده نیز پایش خواهند شد.
هشدار: اگر از این گزینه هنگام پایش دایرکتوری ریشه در یک درخت پوشه‌ای بزرگ استفاده کنید، ممکن است راه‌اندازی تمام نظارت‌های inotify زمان قابل توجهی ببرد و در این فاصله هیچ رویدادی دریافت نشود. همچنین از آنجا که برای هر زیردایرکتوری یک پایش inotify برقرار می‌گردد، احتمال دارد تعداد پایش‌ها از حد مجاز کاربر فراتر رود. حداکثر پیش‌فرض 8192 است؛ این مقدار را می‌توان از طریق نوشتن در /proc/sys/fs/inotify/max_user_watches افزایش داد.
-q, --quiet: در صورت مشخص شدن به صورت یک‌باره، پیام‌های خروجی برنامه کاهش می‌یابد. به‌طور مشخص، اتمام برقراری تمام نظارت‌های inotify گزارش نخواهد شد.
در صورت تکرار دوباره گزینه، هیچ خروجی چاپ نخواهد شد، مگر در زمان وقوع خطاهای مرگبار (fatal).
--exclude <pattern>: عدم پردازش رویدادها برای زیرمجموعه‌ای از فایل‌ها که نام آن‌ها با عبارت باقاعده POSIX داده‌شده هم‌خوانی دارد (حساس به بزرگی و کوچکی حروف).
--excludei <pattern>: عدم پردازش رویدادها برای زیرمجموعه‌ای از فایل‌ها که نام آن‌ها با عبارت باقاعده POSIX داده‌شده هم‌خوانی دارد (غیرحساس به بزرگی و کوچکی حروف).
--include <pattern>: پردازش رویدادها فقط برای زیرمجموعه‌ای از فایل‌ها که نام آن‌ها با عبارت باقاعده POSIX داده‌شده مطابقت دارد (حساس به بزرگی و کوچکی حروف). در صورت استفاده همراه با --recursive، رویدادها برای فایل‌های منطبق در داخل دایرکتوری‌های تازه ایجادشده نیز تولید خواهند شد، حتی اگر نام خود دایرکتوری‌ها با الگو مطابقت نداشته باشد.
--includei <pattern>: پردازش رویدادها فقط برای زیرمجموعه‌ای از فایل‌ها که نام آن‌ها با عبارت باقاعده POSIX داده‌شده مطابقت دارد (غیرحساس به بزرگی و کوچکی حروف).
-t <seconds>, --timeout <seconds>: خروج از برنامه در صورتی که در طول <seconds> ثانیه رویداد مناسبی رخ ندهد. چنانچه مقدار <seconds> صفر باشد (حالت پیش‌فرض)، به صورت نامحدود در انتظار رویداد می‌ماند.
-e <event>, --event <event>: شنود تنها برای رویداد(های) خاص. رویدادهای قابل شنود در بخش EVENTS فهرست شده‌اند. این گزینه می‌تواند بیش از یک‌بار مشخص شود. در صورت عدم درج، تمام رویدادها شنود می‌شوند.
-c, --csv: خروجی در قالب CSV (مقادیر جداشده با کاما). این گزینه هنگامی مفید است که نام فایل‌ها شامل فاصله (space) باشد، زیرا در این وضعیت شکستن خروجی صرفاً با نویسه فاصله امن نیست..TP --timefmt <fmt> تنظیم یک رشته قالب زمان قابل قبول برای strftime(3) جهت استفاده در تبدیل `%T' در گزینه --format.
--no-newline: عدم چاپ نماد خط جدید (newline) پس از قالب مشخص‌شده توسط کاربر در گزینه --format.
--format <fmt>: خروجی در قالب مشخص‌شده توسط کاربر، با استفاده از ساختار شبیه به printf. طول رشته‌های رویداد خروجی به حدود ۴۰۰۰ نویسه محدود است و تا این اندازه کوتاه خواهند شد. تبدیل‌های زیر پشتیبانی می‌شوند:
%w: با نام فایل تحت نظارتی که رویداد روی آن رخ داده است جایگزین می‌شود. هنگامی که رویدادی درون یک دایرکتوری تحت نظارت رخ دهد یا هنگام نظارت با fanotify، با نام دایرکتوری که رویداد در آن رخ داده است جایگزین خواهد شد.
%f: هنگامی که رویدادی درون یک دایرکتوری تحت نظارت رخ دهد یا هنگام نظارت با fanotify، با نام فایلی که موجب رخداد این رویداد شده است جایگزین می‌شود. در غیر این صورت، با یک رشته خالی جایگزین خواهد شد.
%e: با رویداد(های) رخ‌داده، جدا شده با کاما، جایگزین می‌شود.
%Xe: با رویداد(های) رخ‌داده، جدا شده با هر نویسه‌ای که به جای `X' قرار گرفته باشد، جایگزین می‌شود.
%T: با زمان کنونی در قالب تعیین‌شده توسط گزینه --timefmt جایگزین می‌شود، که باید یک رشته قالب مناسب برای ارسال به strftime(3) باشد.
%0: با NUL جایگزین می‌شود.
%n: با Line Feed (خط جدید) جایگزین می‌شود.
-I, --inotify: نظارت با استفاده از inotify (پیش‌فرض برای inotifywait).
-F, --fanotify: نظارت با استفاده از fanotify (پیش‌فرض برای fsnotifywait). پشتیبانی fanotify از گزارش رویدادها همراه با اطلاعات سازگار با inotify در هسته نسخه ۵.۹ اضافه شد. در هسته‌های قدیمی‌تر این دستور با شکست مواجه می‌شود. از هسته نسخه ۵.۱۲، استفاده از fanotify نیازمند دسترسی‌های مدیر سیستم است.
-S, --filesystem: نظارت بر کل فایل‌سیستم هر یک از دایرکتوری‌های ارائه‌شده به عنوان آرگومان با استفاده از fanotify.

وضعیت خروج (EXIT STATUS)

0: برنامه با موفقیت اجرا شد و رویدادی که شنود می‌شد رخ داد.
1: خطایی در اجرای برنامه رخ داد، یا رویدادی رخ داد که شنود نمی‌شد. مورد دوم معمولاً زمانی رخ می‌دهد که اتفاقی بیفتد که دیده‌بانی inotify را اجباراً حذف کند، مانند حذف فایلی که تحت نظارت است یا پیاده شدن (unmount) فایل‌سیستمی که حاوی فایل تحت نظارت است.
2: از گزینه -t استفاده شد و هیچ رویدادی در بازه زمانی تعیین‌شده رخ نداد..SH "رویدادها (EVENTS)" رویدادهای زیر برای استفاده با گزینهٔ -e معتبر هستند:
access: یک فایل تحت‌نظر یا فایلی درون یک دایرکتوری تحت‌نظر خوانده شد.
modify: در یک فایل تحت‌نظر یا فایلی درون یک دایرکتوری تحت‌نظر نوشته شد.
attrib: متادیتای یک فایل تحت‌نظر یا فایلی درون یک دایرکتوری تحت‌نظر تغییر یافت. این مورد شامل برچسب‌های زمانی، مجوزهای فایل، ویژگی‌های توسعه‌یافته و غیره است.
close_write: یک فایل تحت‌نظر یا فایلی درون یک دایرکتوری تحت‌نظر، پس از باز شدن در حالت قابل نوشتن، بسته شد. این لزوماً به این معنا نیست که در فایل نوشته شده است.
close_nowrite: یک فایل تحت‌نظر یا فایلی درون یک دایرکتوری تحت‌نظر، پس از باز شدن در حالت فقط‌خواندنی، بسته شد.
close: یک فایل تحت‌نظر یا فایلی درون یک دایرکتوری تحت‌نظر، صرف‌نظر از نحوهٔ باز شدن آن، بسته شد. توجه داشته باشید که این در واقع صرفاً با شنود هر دوی close_write و close_nowrite پیاده‌سازی شده است؛ از این‌رو تمام رویدادهای بسته‌شدن دریافتی به‌صورت یکی از این دو در خروجی نمایش داده می‌شوند، نه CLOSE.
open: یک فایل تحت‌نظر یا فایلی درون یک دایرکتوری تحت‌نظر باز شد.
moved_to: یک فایل یا دایرکتوری به درون یک دایرکتوری تحت‌نظر منتقل شد. این رویداد حتی در صورتی که فایل صرفاً از و به همان دایرکتوری منتقل شود نیز رخ می‌دهد.
moved_from: یک فایل یا دایرکتوری از یک دایرکتوری تحت‌نظر منتقل شد. این رویداد حتی در صورتی که فایل صرفاً از و به همان دایرکتوری منتقل شود نیز رخ می‌دهد.
move: یک فایل یا دایرکتوری از یا به یک دایرکتوری تحت‌نظر منتقل شد. توجه داشته باشید که این در واقع صرفاً با شنود هر دوی moved_to و moved_from پیاده‌سازی شده است؛ از این‌رو تمام رویدادهای جابه‌جایی دریافتی به‌صورت یکی از این دو یا هر دو در خروجی نمایش داده می‌شوند، نه MOVE.
move_self: یک فایل یا دایرکتوری تحت‌نظر جابه‌جا شد. پس از این رویداد، فایل یا دایرکتوری دیگر تحت‌نظر نخواهد بود.
create: یک فایل یا دایرکتوری درون یک دایرکتوری تحت‌نظر ایجاد شد.
delete: یک فایل یا دایرکتوری درون یک دایرکتوری تحت‌نظر حذف شد.
delete_self: یک فایل یا دایرکتوری تحت‌نظر حذف شد. پس از این رویداد، فایل یا دایرکتوری دیگر تحت‌نظر نخواهد بود. توجه داشته باشید که این رویداد حتی در صورتی که صراحتاً برای آن شنود نشده باشد نیز می‌تواند رخ دهد.
unmount: سیستم‌فایلی که فایل یا دایرکتوری تحت‌نظر روی آن قرار دارد، پیاده (unmount) شد. پس از این رویداد، فایل یا دایرکتوری دیگر تحت‌نظر نخواهد بود. توجه داشته باشید که این رویداد حتی در صورتی که صراحتاً برای آن شنود نشده باشد نیز می‌تواند رخ دهد..SH "مثال‌ها (EXAMPLES)"

مثال ۱

اجرای inotifywait در خط فرمان برای انتظار جهت دسترسی به هر فایلی در دایرکتوری `test`. پس از اجرای inotifywait، دستور `cat test/foo` در یک کنسول جداگانه اجرا می‌شود.

% inotifywait test
Setting up watches.
Watches established.
test/ ACCESS foo

مثال ۲

یک اسکریپت شل کوتاه برای انتظار کارآمد جهت رویداد پیام‌های لاگ مرتبط با httpd و انجام اقدام مناسب.

#!/bin/sh
while ! inotifywait -e modify /var/log/messages; do
  if tail -n1 /var/log/messages | grep httpd; then
    kdialog --msgbox "Apache needs love!"
  fi
done

مثال ۳

یک قالب خروجی سفارشی برای پایش `~/test` استفاده شده است. در همین حال، در کنسول دیگری دستور `touch ~/test/badfile; touch ~/test/goodfile; rm ~/test/badfile` اجرا می‌شود.

% inotifywait -m -r --format '%:e %f' ~/test
Setting up watches.  Beware: since -r was given, this may take a while!
Watches established.
CREATE badfile
OPEN badfile
ATTRIB badfile
CLOSE_WRITE:CLOSE badfile
CREATE goodfile
OPEN goodfile
ATTRIB goodfile
CLOSE_WRITE:CLOSE goodfile
DELETE badfile

مثال ۴

اعمال مجوزهای فایل در دایرکتوری `~/test`

inotifywait -qmr -e 'moved_to,create' --format '%w%f%0' --no-newline ~/test |\
    while IFS= read -r -d '' file
    do
	  chmod -v a+rX "$file"
    done

هشدارها (CAVEATS)

هنگام استفاده از inotifywait، تضمینی وجود ندارد که نام فایل خروجی پس از جابه‌جایی به‌روز باشد، زیرا در واقع inode پایش می‌شود. علاوه بر این، در مواردی که فایل با چندین نام در سیستم‌فایل شناخته می‌شود، تضمینی نیست که هیچ‌یک از عملیات‌های مشاهده‌شده روی نام فایلی انجام شده باشند که به inotifywait دستور پایش آن داده شده بود.

گزارش باگ‌ها (BUGS)

در کد پایش بازگشتی دایرکتوری شرایط رقابتی (race conditions) وجود دارد که در صورت وقوع رویدادها در یک دایرکتوری بلافاصله پس از ایجاد آن، می‌تواند باعث از دست رفتن رویدادها شود. این مشکل احتمالاً قابل رفع نیست.

فرض بر این است که صف رویدادهای inotify هرگز سرریز نخواهد کرد.

نویسندگان (AUTHORS)

توسعهٔ inotifywait توسط Rohan McGovern آغاز شد و در حال حاضر توسط Eric Curtin و Radu Voicilas نگهداری می‌شود. نشانی https://www.openhub.net/p/inotify-tools/contributors/summary فهرست کامل‌تری از مشارکت‌کنندگان را ارائه می‌دهد.

ابزار inotifywait بخشی از inotify-tools است. وبگاه inotify-tools در نشانی زیر قرار دارد: https://github.com/inotify-tools/inotify-tools/wiki.SH همچنین ببینید (SEE ALSO) inotifywatch(1), strftime(3), inotify(7)