بلاگ

اسم فایلت می‌تونه عجیب باشه؛ ابزارهات نباید عجیب‌ترش کنن

fd --format اسم فایل‌های غیر UTF-8 را در pipe بی‌صدا تغییر می‌داد و xargs فایل را پیدا نمی‌کرد. فیکس من (sharkdp/fd PR #2197) در upstream merge شد.

نویسنده محمدپویا قورچیانیقورچیانی

engineeringopen-sourcerust

پاسخ مستقیم

در لینوکس اسم فایل فقط یک دنباله بایت است و لازم نیست UTF-8 معتبر باشد. تا همین هفته، وقتی خروجی fd --format '{}' به pipe می‌رفت، اسمی مثل test_\xFEinvalid.txt با خروجی سالم بیرون نمی‌آمد: بایت FE جایش را به EF BF BD (کاراکتر جایگزین یونیکد، �) می‌داد. ابزار بعدی در pipeline، مثلاً xargs -0 rm یا xargs -0 cp، دنبال فایلی می‌گشت که وجود نداشت.

فیکس من، sharkdp/fd #2197، روی Unix هر وقت stdout ترمینال نباشد، همان بایت‌های اصلی را می‌نویسد. این PR در upstream merge شده و در نسخهٔ بعدی fd منتشر می‌شود.

کامپیوتری که فکر می‌کرد بهتر می‌داند 🤖

فرض کن یک فایل با اسمی کمی عجیب به کامپیوترت می‌دهی و او می‌گوید:

«هوم، این اسم رو دوست ندارم. بذار برات درستش کنم!»

فایل rename نمی‌شود و روی دیسک دقیقاً همان است که بود. چیزی که عوض می‌شود اسمی است که به ابزار بعدی می‌رسد. تو آن اسم را می‌خواهی و یک نسخهٔ «تمیزشده» تحویل می‌گیری که با هیچ فایلی روی دیسک جور نیست.

نه چیزی crash می‌کند و نه خطایی log می‌شود. بعداً می‌فهمی، وقتی xargs می‌گوید No such file or directory و تو به خودت شک می‌کنی.

نرم‌افزار نباید این‌قدر سخت‌گیر باشد.

بازتولید در ۱۰ ثانیه

این مراحل از گزارش اصلی، sharkdp/fd #2189، آمده است:

Shell
mkdir t && touch "t/test_$(printf '\xfe')invalid.txt"

# plain fd: the raw byte survives
fd invalid t | xxd | head -1

# --format before the fix: FE became EF BF BD
fd --format '{}' invalid t | xxd | head -1

خروجی معمولی fd از قبل درست کار می‌کرد. فقط مسیر --format از to_string_lossy() رد می‌شد، که روش مؤدبانهٔ Rust است برای گفتن «هرچه را نفهمم جایگزین می‌کنم». حتی یک کامنت هم همان‌جا گذاشته شده بود:

Rust
// TODO: support writing raw bytes on unix?

کل ماجرا همین TODO است. کسی قبلاً مشکل را دیده بود و برای بعد یادداشتش کرده بود.

فیکس: چیزی را که از تو نخواسته‌اند عوض نکن

تغییر در src/output.rs کوچک است. اگر روی Unix هستیم و stdout ترمینال تعاملی نیست، بایت‌های OsStr را دست‌نخورده بنویس؛ در غیر این صورت رفتار قبلی می‌ماند:

Rust
#[cfg(unix)]
{
    use std::os::unix::ffi::OsStrExt;

    if config.interactive_terminal {
        print_entry_format_base(stdout, &output, config)
    } else {
        // Preserve the original path bytes when stdout is not an interactive terminal.
        stdout.write_all(output.as_os_str().as_bytes())
    }
}

چرا روی ترمینال نسخهٔ lossy حفظ شد؟ چون آنجا انسان می‌خواندش. یک � روی صفحه صادق و خواناست، ولی بایت خام 0xFE ممکن است ترمینال را به‌هم بریزد. آن سر pipe یک برنامه نشسته و برنامه بایت واقعی لازم دارد.

این رفتار با مسیر خروجی عادی fd یکی است، پس --format حالا همان کاری را می‌کند که fd ساده می‌کند.

بار اصلی روی تست‌هاست

۲۲ خط کد به اندازهٔ ۵۴ خط تست اهمیت نداشت. تست test_format_invalid_utf8 یک فایل واقعی با بایت \xFE در نامش می‌سازد و همهٔ placeholderها را بایت‌به‌بایت چک می‌کند:

Placeholder خروجی مورد انتظار
{} test1/test_\xFEinvalid.txt
{/} test_\xFEinvalid.txt
{//} test1
{.} test1/test_\xFEinvalid
{/.} test_\xFEinvalid
{} با --print0 test1/test_\xFEinvalid.txt\0
{} با --path-separator = test1=test_\xFEinvalid.txt

این تست روی macOS اجرا نمی‌شود، چون APFS نام‌ها را به UTF-8 تبدیل می‌کند و اصلاً نمی‌شود آنجا فایل خراب ساخت. روی Windows هم اجرا نمی‌شود، چون آنجا مسیرها UTF-16 هستند و این مسئلهٔ دیگری است.

چه یاد گرفتم

  • TODOها را بخوان. بعضی از بهترین مشارکت‌های اول، از قبل به شکل یک سؤال در کد نوشته شده‌اند.
  • با xxd بازتولید کن، نه با چشم. ترمینال «کمکت می‌کند» و باگ را قایم می‌کند؛ hex dump نه.
  • scope را کوچک نگه دار. خروجی ترمینال، Windows و --path-separator مثل قبل رفتار می‌کنند؛ فقط حالت خراب عوض شد.
  • دربارهٔ هم‌پوشانی مؤدب باش. نویسندهٔ issue گفته بود فیکسی آماده دارد، ولی PR لینک‌شده‌ای پیدا نکردم. پس PR خودم را باز کردم و در آن نوشتم که اگر رویکردش فرق دارد، PR خودم را به نفع او می‌بندم.
  • اعتبار را به reviewer بده. Thayne McCombs (@tmccombs) PR را review کرد، کامیت نهایی را push کرد و merge کرد. وقت maintainer کمیاب‌ترین منبع اوپن‌سورس است.

به زبان عدد

  • پروژه: sharkdp/fd، جایگزین سریع find که با Rust نوشته شده
  • PR: #2197: fix: write raw bytes for piped –format output on unix
  • issue: #2189
  • تغییرات: ۳ فایل، ‎+78 / −2 (src/output.rs، tests/tests.rs، CHANGELOG.md)
  • CI: ۲۰ چک، ۱۹ پاس و ۱ skip، بدون هیچ شکست
  • وضعیت: merge شده در master در ۷ نوامبر ۲۰۲۶

بی‌گریم ناخواسته. بی‌فایل گم‌شده. بگذار اسم فایل‌ها خودشان باشند. 💖

پرسش‌های پرتکرار

چرا xargs برای فایلی که وجود دارد می‌گوید No such file or directory؟

معمولاً چون ابزاری قبل‌تر در pipeline بایت‌های اسم را عوض کرده است. اگر اسم فایل UTF-8 معتبر نباشد، ابزاری که آن را به متن تبدیل می‌کند ممکن است بایت خراب را با � عوض کند، و بعد xargs از کرنل اسمی را می‌خواهد که وجود ندارد. لیست را از xxd رد کن و با اسم واقعی مقایسه کن.

آیا اسم فایل در لینوکس می‌تواند UTF-8 نامعتبر باشد؟

بله. برای کرنل لینوکس اسم فایل هر دنباله بایتی است به جز / و بایت NUL. UTF-8 یک قرارداد است، نه قانون. macOS (APFS) فرق دارد و اسم‌ها را حتماً UTF-8 معتبر می‌خواهد.

کاراکتر � (U+FFFD) چیست؟

کاراکتر جایگزین یونیکد. نرم‌افزار آن را جایی می‌گذارد که بایتی را نتوانسته decode کند. در UTF-8 این کاراکتر سه بایت EF BF BD است؛ یعنی یک بایت خراب به سه بایت متفاوت تبدیل می‌شود.

فیکس در کدام نسخهٔ fd است؟

در changelog نسخهٔ بعد از fd 10.5.1 آمده است. تا آن موقع می‌توانی fd را از master بسازی.

چطور بایت‌های واقعی اسم یک فایل را ببینم؟

به جای چشم از hex dump استفاده کن: ls | xxd یا fd pattern | xxd. برای مبانی خواندن این بایت‌ها، کد اسکی و جدول اسکی: تبدیل hex به ascii در ترمینال را ببین.

لینک‌ها