ZSHZFTPSYS(1) General Commands Manual ZSHZFTPSYS(1)

zshzftpsys - رابط کاربری توابع zftp

این بخش مجموعه‌ای از توابع شل عرضه‌شده همراه با توزیع مبدأ را به عنوان یک واسط برای دستور توکار zftp توصیف می‌کند، که به شما امکان می‌دهد عملیات‌های FTP را از خط فرمان شل یا از درون توابع یا اسکریپت‌ها انجام دهید. این واسط شبیه به یک کلاینت سنتی FTP است (برای مثال خود دستور ftp، به ftp(1) نگاه کنید)، اما از آنجا که کاملاً درون شل انجام می‌شود، تمام ویژگی‌های آشنای تکمیل خودکار (completion)، ویرایش و تطبیق الگو (globbing) و غیره حضور دارند، و نوشتن ماکروها به ویژه ساده است زیرا آن‌ها فقط توابع معمولی شل هستند.

پیش‌نیاز این است که دستور zftp، همان‌طور که در zshmodules(1) شرح داده شده است، باید در نسخهٔ zsh نصب‌شده در سیستم شما در دسترس باشد. اگر شل طوری پیکربندی شده باشد که دستورهای جدید را در زمان اجرا بارگیری کند، احتمالاً موجود است: وارد کردن «zmodload zsh/zftp» اطمینان حاصل خواهد کرد (اگر بدون خروجی اجرا شود، کار کرده است). در غیر این صورت، ممکن است zftp به هر حال به صورت داخلی با شل پیوند (link) داده شده باشد: برای آزمایش این مورد، عبارت «which zftp» را بنویسید و اگر zftp در دسترس باشد پیام «zftp: shell built-in command» را دریافت خواهید کرد.

دستورهایی که مستقیماً با دستور توکار zftp صادر می‌شوند ممکن است در میان توابع این مجموعه آمیخته شوند؛ در موارد اندکی، استفادهٔ مستقیم از zftp ممکن است باعث شود برخی از اطلاعات وضعیت ذخیره‌شده در متغیرهای شل نامعتبر شوند. به‌ویژه به توضیحات متغیرهای $ZFTP_TMOUT، $ZFTP_PREFS و $ZFTP_VERBOSE برای zftp توجه کنید.

باید مطمئن شوید که تمامی توابع از دایرکتوری Functions/Zftp توزیع مبدأ در دسترس هستند؛ همگی آن‌ها با دو حرف «zf» شروع می‌شوند. ممکن است آن‌ها از پیش روی سیستم شما نصب شده باشند؛ در غیر این صورت، باید آن‌ها را پیدا کرده و کپی کنید. این دایرکتوری باید به عنوان یکی از عناصر آرایهٔ $fpath ظاهر شود (اگر نصب شده باشند باید از قبل چنین باشد)، و حداقل تابع zfinit باید به صورت خودکار بارگیری (autoload) شود؛ این تابع باقی موارد را به طور خودکار بارگیری خواهد کرد. در نهایت، برای مقداردهی اولیهٔ استفاده از این سامانه، باید تابع zfinit را فراخوانی کنید. کد زیر در فایل .zshrc شما این کار را ترتیب می‌دهد؛ فرض کنید توابع در دایرکتوری ~/myfns ذخیره شده‌اند:

fpath=(~/myfns $fpath)
autoload -U zfinit
zfinit

توجه داشته باشید که zfinit فرض می‌کند شما از روش zmodload برای بارگیری دستور zftp استفاده می‌کنید. اگر این دستور از قبل در شل تعبیه شده است، zfinit را به zfinit -n تغییر دهید. سودمند است (اگرچه ضروری نیست) که فراخوانی zfinit پس از هر کدی برای مقداردهی اولیهٔ سامانهٔ جدید تکمیل خودکار قرار گیرد، در غیر این صورت دستورهای غیرضروری compctl صادر خواهند شد.

ترتیب عملیات در انجام یک انتقال فایل اساساً همانند یک کلاینت استاندارد FTP است. توجه داشته باشید که به دلیل ویژگی خاصی در دستور توکار getopts شل، برای توابعی که گزینه‌ها را پردازش می‌کنند، باید به‌جای «-» از «--» استفاده کنید تا اطمینان حاصل شود که آرگومان‌های باقی‌مانده به‌صورت تحت‌اللفظی رفتار می‌شوند (یک «-» تنها به عنوان یک آرگومان در نظر گرفته می‌شود).

zfparams [ host [ user [ password ... ] ] ]
تنظیم یا نمایش پارامترها برای یک zfopen آتی بدون آرگومان. اگر هیچ آرگومانی داده نشود، پارامترهای فعلی نمایش داده می‌شوند (رمز عبور به صورت خطی از ستاره‌ها نشان داده خواهد شد). اگر یک host داده شود، و user یا password داده نشوند، برای دریافت آن‌ها اعلان (prompt) داده می‌شود؛ همچنین، برای هر پارامتری که به صورت «?» مشخص شود اعلان دریافت خواهد آمد، و اگر پس از «?» یک رشته بیاید، آن رشته به عنوان متن اعلان استفاده می‌شود. از آنجا که zfopen برای ذخیرهٔ پارامترها zfparams را فراخوانی می‌کند، معمولاً نیازی به فراخوانی مستقیم آن نیست.

یک آرگومان تک «-» پارامترهای ذخیره‌شده را حذف خواهد کرد. این کار همچنین باعث می‌شود حافظهٔ آخرین دایرکتوری (و موارد مشابه) در هاست دیگر نیز پاک شود.

اگر host مشخص شده باشد، اتصالی به آن هاست با نام کاربری user و رمز عبور password (و در موارد نادری که لازم است، حساب account) باز می‌کند. اگر یک پارامتر ضروری وجود نداشته باشد یا به صورت «?» داده شده باشد، برای دریافت آن اعلان داده می‌شود. اگر host مشخص نشده باشد، از مجموعه‌ای از پارامترهای ذخیره‌شدهٔ قبلی استفاده می‌شود.

اگر دستور موفقیت‌آمیز باشد و ترمینال با xterm سازگار بوده یا sun-cmd باشد، خلاصه‌ای در نوار عنوان ظاهر می‌شود که host:directory محلی و host:directory راه دور را نمایش می‌دهد؛ این کار توسط تابع zftp_chpwd که در زیر توضیح داده شده مدیریت می‌شود.

به طور معمول، host، user و password به صورت داخلی برای اتصال مجدد در آینده ثبت می‌شوند، چه با یک zfopen بدون آرگومان، یا به صورت خودکار (به زیر مراجعه کنید). با گزینهٔ «-1»، هیچ اطلاعاتی ذخیره نمی‌شود. همچنین، اگر یک دستور open همراه با آرگومان با شکست مواجه شود، پارامترها حفظ نخواهند شد (و هرگونه پارامتر قبلی نیز حذف خواهد شد). یک دستور zfopen به تنهایی، یا یک zfopen -1، هرگز پارامترهای ذخیره‌شده را تغییر نمی‌دهد.

هر دو دستور zfopen و zfanon (اما نه zfparams) نشانی‌های وب به فرم ftp://host/path... را به این معنا تفسیر می‌کنند که به host متصل شوند و سپس دایرکتوری را به path (که باید یک دایرکتوری باشد، نه یک فایل) تغییر دهند. بخش «ftp://» را می‌توان حذف کرد؛ نویسهٔ پایانی «/» برای راه‌اندازی شناسایی path کافی است. توجه داشته باشید پیشوندهایی غیر از «ftp:» شناسایی نمی‌شوند، و تمام نویسه‌های پس از اولین اسلش بعد از host در path دارای اهمیت هستند.

یک اتصال به host برای FTP ناشناس باز می‌کند. نام کاربری مورد استفاده «anonymous» است. رمز عبور (که بار اول گزارش خواهد شد) به صورت user@host تولید می‌شود؛ این مقدار سپس در پارامتر شل $EMAIL_ADDR ذخیره می‌شود که می‌توان آن را به صورت دستی نیز روی یک رشتهٔ مناسب تنظیم کرد.
zfcd [ dir ]
zfcd -
zfcd old new
دایرکتوری جاری در سرور دوردست را تغییر می‌دهد: این دستور طوری پیاده‌سازی شده است که بسیاری از قابلیت‌های دستور توکار پوسته cd را داشته باشد.

در شکل نخست با حضور dir، به دایرکتوری dir تغییر می‌یابد. دستور `zfcd ..' به‌صورت ویژه مدیریت می‌شود، بنابراین تضمین می‌شود که بر روی سرورهای غیر یونیکسی نیز کار کند (توجه داشته باشید که این مورد به‌طور داخلی توسط zftp انجام می‌شود). اگر dir نادیده گرفته شود، اثری مشابه `zfcd ~' خواهد داشت.

شکل دوم، دایرکتوری را به دایرکتوری‌ای تغییر می‌دهد که پیش از این جاری بوده است.

شکل سوم تلاش می‌کند با جایگزینی نخستین رخداد رشتهٔ old با رشتهٔ new در دایرکتوری جاری، دایرکتوری جاری را تغییر دهد.

توجه داشته باشید که در این دستور، و در واقع هر جا که انتظار نام فایل دوردست می‌رود، رشته‌ای که در میزبان محلی معادل `~' است، پیش از ارسال به دستگاه دوردست، مجدداً به `~' تبدیل می‌شود. این امر به‌دلیل شیوهٔ انجام بسط در خط فرمان، پیش از آن‌که zfcd رشته را دریافت کند، بسیار سودمند است. برای نمونه، فرض کنید دستور `zfcd ~/foo' باشد. پوسته این عبارت را به یک مسیر کامل مانند `zfcd /home/user2/pws/foo' بسط می‌دهد. در این مرحله، zfcd مسیر اولیه را به‌عنوان معادل `~' شناسایی کرده و دایرکتوری را به‌صورت ~/foo به میزبان دوردست ارسال می‌کند، تا `~' توسط سرور به دایرکتوری درست در میزبان دوردست بسط داده شود. سایر دایرکتوری‌های نام‌گذاری‌شده به شکل `~name' به این شیوه مدیریت نمی‌شوند.

دایرکتوری را در سرور دوردست به دایرکتوری متناظر با دایرکتوری محلی جاری تغییر می‌دهد، همراه با رفتار ویژه نسبت به `~' همانند zfcd. برای نمونه، اگر دایرکتوری محلی جاری ~/foo/bar باشد، آنگاه zfhere اثری همانند `zfcd ~/foo/bar' خواهد داشت.
فهرست‌بندی کاملی از دایرکتوری ارائه می‌دهد. آرگومان‌های dir-options و dir مستقیماً به سرور فرستاده می‌شوند و تأثیر آن‌ها به پیاده‌سازی سرور وابسته است، اما تعیین یک دایرکتوری دوردست خاص dir معمولاً امکان‌پذیر است. خروجی از طریق یک صفحه‌بندی‌کننده (pager) که توسط متغیر محیطی $PAGER تعیین می‌شود، یا در صورت تنظیم نبودن آن، از طریق `more' نمایش داده می‌شود.

دایرکتوری معمولاً برای استفادهٔ دوباره کَش می‌شود. در واقع، دو کَش نگهداری می‌شود. یکی برای زمانی است که هیچ dir-options یا dir وجود نداشته باشد، یعنی فهرست کاملی از دایرکتوری دوردست جاری؛ این کَش با تغییر دایرکتوری دوردست جاری خالی (flush) می‌شود. کَش دیگر برای استفادهٔ مکرر از zfdir با آرگومان‌های یکسان نگه داشته می‌شود؛ برای نمونه، استفادهٔ مکرر از `zfdir /pub/gnu' فقط در نخستین فراخوانی نیاز به واکشی دایرکتوری خواهد داشت. علاوه بر این، این کَش می‌تواند با گزینهٔ -r دوباره مشاهده شود. از آنجا که دایرکتوری‌های نسبی ممکن است موجب سردرگمی zfdir شوند، می‌توان از گزینهٔ -f استفاده کرد تا پیش از فهرست کردن دایرکتوری، کَش اجباراً پاک‌سازی شود. گزینهٔ -d هر دو کَش را بدون نمایش فهرست دایرکتوری حذف می‌کند؛ همچنین در صورت وجود، کَشِ نام فایل‌ها در دایرکتوری دوردست جاری را نیز حذف خواهد کرد.

فایل‌ها را بر روی سرور دوردست فهرست می‌کند. بدون هیچ آرگومانی، این دستور فهرستی ساده از نام فایل‌ها را برای دایرکتوری دوردست جاری تولید خواهد کرد. هرگونه آرگومان مستقیماً به سرور ارسال می‌شود. از هیچ صفحه‌بندی‌کننده یا کَشی استفاده نمی‌شود.

zftype [ type ]
بدون هیچ آرگومانی، نوع داده‌ای که قرار است منتقل شود را نشان می‌دهد، که معمولاً ASCII یا باینری است. همراه با یک آرگومان، نوع داده را تغییر می‌دهد: انواع `A' یا `ASCII' برای داده‌های ASCII و `B' یا `BINARY'، `I' یا `IMAGE' برای داده‌های باینری بدون حساسیت به حروف کوچک و بزرگ درک می‌شوند.
وضعیت اتصال جاری یا آخرین اتصال، و همچنین وضعیت برخی از متغیرهای وضعیت zftp را نمایش می‌دهد. با گزینهٔ -v، با پرس‌وجو از سرور دربارهٔ گزارش خودش از رویدادها نیز، فهرستی مشروح‌تر و با جزئیات بیشتر تولید می‌شود. دستورهای دریافت فایل همگی دست‌کم دو گزینه می‌پذیرند. -G از بسط نام فایل‌های دوردست که در غیر این صورت انجام می‌شد جلوگیری می‌کند (برای توضیحات دقیق‌تر در این باره، بخش زیر را ببینید). -t تلاش می‌کند زمان تغییر (modification time) فایل محلی را با زمان فایل دوردست تنظیم کند: برای اطلاعات بیشتر، توضیحات تابع zfrtime در زیر را ببینید.
zfget [ -Gtc ] file1 ...
تمام فایل‌های فهرست‌شدهٔ file1 ... را یکی‌یکی از سرور دوردست دریافت می‌کند. اگر نام یک فایل حاوی یک `/' باشد، نام کامل به سرور دوردست ارسال می‌شود، اما فایل به‌صورت محلی با نام برگرفته از بخش پس از آخرین `/' ذخیره می‌شود. گزینهٔ -c (cat) تحمیل می‌کند که تمام فایل‌ها در قالب یک جریان یکپارچه به خروجی استاندارد ارسال شوند؛ در این حالت، گزینهٔ -t هیچ تأثیری ندارد.
مشابه zfget است، اما تنها فایل‌هایی را دریافت می‌کند که نسخهٔ موجود روی سرور دوردست تازه‌تر باشد (زمان تغییر جدیدتری داشته باشد)، یا فایل محلی وجود نداشته باشد. اگر فایل دوردست قدیمی‌تر باشد اما اندازهٔ فایل‌ها متفاوت باشد، یا اندازه یکسان باشد اما فایل دوردست تازه‌تر باشد، معمولاً از کاربر سؤال خواهد شد. با گزینهٔ -s، دستور در حالت بی‌صدا اجرا می‌شود و در هر یک از این دو حالت همواره فایل را دریافت خواهد کرد. با گزینهٔ -v، دستور در حین بررسی این‌که آیا فایل‌ها باید منتقل شوند یا خیر، اطلاعات بیشتری دربارهٔ آن‌ها چاپ می‌کند.
مشابه zfget است، اما اگر هر یک از فایل‌های محلی وجود داشته باشد و حجم آن کمتر از فایل دوردست متناظر باشد، دستور فرض می‌کند که این فایل نتیجهٔ یک انتقال ناتمام است و تلاش می‌کند باقی‌ماندهٔ فایل را دریافت کند. این قابلیت در اتصالات ضعیفی که مکرراً قطع می‌شوند سودمند است.

توجه داشته باشید که این ویژگی نیازمند نسخه‌ای رایج اما غیر استاندارد از پروتکل FTP است، بنابراین کارکرد آن روی همهٔ سرورها تضمین نمی‌شود.

zfgcp [ -Gt ] remote-file local-file
zfgcp [ -Gt ] rfile1 ... ldir
این دستور فایل‌ها را با آرگومان‌هایی با رفتاری مشابه با دستور cp از سرور دوردست دریافت می‌کند.

در شکل نخست، remote-file را از سرور در فایل محلی local-file کپی می‌کند.

در شکل دوم، تمام فایل‌های دوردست rfile1 ... را با حفظ همان نام پایه (basename) در دایرکتوری محلی ldir کپی می‌کند. این عمل ساختار و مفاهیم دایرکتوری‌های UNIX را فرض می‌گیرد.

zfput [ -r ] file1 ...
تمام فایل‌های file1 ... مشخص‌شده را به‌صورت جداگانه به سرور دوردست ارسال می‌کند. اگر نام یک فایل حاوی `/' باشد، نام کامل فایل به‌صورت محلی برای یافتن آن استفاده می‌شود، اما برای نام فایل در سرور دوردست تنها نام پایه (basename) به کار می‌رود.

با گزینهٔ -r، اگر هر یک از files دایرکتوری باشند، به‌صورت بازگشتی همراه با تمام زیردایرکتوری‌هایشان، از جمله فایل‌هایی که با `.' شروع می‌شوند ارسال می‌گردند. این امر مستلزم آن است که ماشین دوردست ساختار فایل‌های UNIX را بفهمد، زیرا از `/' به‌عنوان جداکنندهٔ دایرکتوری استفاده می‌شود.

مشابه zfput است، اما تنها فایل‌هایی را ارسال می‌کند که از معادل‌های دوردست خود جدیدتر باشند، یا در صورتی که فایل دوردست وجود نداشته باشد. منطق آن مانند zfuget است، اما جای فایل‌های محلی و دوردست معکوس شده است.
مشابه zfput است، اما اگر هر فایل دوردستی از پیش موجود باشد و کوتاه‌تر از معادل محلی خود باشد، فرض می‌کند که نتیجهٔ یک انتقال ناقص است و باقی‌ماندهٔ فایل را برای الحاق به بخش موجود ارسال می‌کند. از آنجا که دستور الحاق (append) در FTP بخشی از مجموعهٔ دستورهای استاندارد است، این قابلیت در اصل شانس موفقیت بیشتری نسبت به zfcget دارد.
zfpcp local-file remote-file
zfpcp lfile1 ... rdir
این دستور فایل‌ها را با آرگومان‌هایی با رفتاری مشابه با دستور cp به سرور دوردست ارسال می‌کند.

با دو آرگومان، local-file را با نام remote-file به سرور کپی می‌کند.

با بیش از دو آرگومان، تمام فایل‌های محلی lfile1 ... را با حفظ همان نام پایه در دایرکتوری دوردست موجود rdir کپی می‌کند. این عمل ساختار دایرکتوری‌های UNIX را پیش‌فرض می‌گیرد.

اگر تلاش کنید از دستور zfpcp lfile1 rdir استفاده کنید، یعنی شکل دوم کپی اما با دو آرگومان، مشکلی رخ می‌دهد؛ زیرا دستور راه ساده‌ای برای تشخیص این‌که آیا rdir متناظر با یک دایرکتوری است یا یک نام فایل در دست ندارد. دستور تلاش می‌کند این موضوع را به روش‌های گوناگونی حل کند. نخست، اگر آرگومان rdir برابر با `.' یا `..' باشد یا به یک اسلش ختم شود، دایرکتوری فرض می‌شود. دوم، چنانچه عملیات کپی به یک فایل دوردست در شکل اول شکست بخورد و سرور دوردست کد خطای مورد انتظار 553 و پاسخی شامل رشتهٔ `Is a directory' را بازگرداند، آنگاه zfpcp با استفاده از شکل دوم مجدداً تلاش خواهد کرد.

zfclose
اتصال را می‌بندد.

zfsession [ -lvod ] [ sessname ]
به شما امکان می‌دهد چندین نشست FTP را به‌طور همزمان مدیریت کنید. به‌طور پیش‌فرض، اتصالات در نشستی به نام «default» انجام می‌شوند؛ با اجرای فرمان «zfsession sessname» می‌توانید به یک نشست جدید یا موجود با نام دلخواه خود بروید. نشست جدید اتصال مختص به خود، پارامترهای مرتبط شل، و همچنین پارامترهای میزبان/کاربر تنظیم‌شده توسط zfparams را به خاطر می‌سپارد. از این رو می‌توانید نشست‌های متفاوتی برای اتصال به میزبان‌های گوناگون برپا کنید، به طوری که هر کدام میزبان، کاربر و گذرواژه مناسب را به خاطر داشته باشند.

بدون آرگومان، zfsession نام نشست فعلی را چاپ می‌کند؛ با گزینه -l تمام نشست‌های موجود فعلی را فهرست می‌کند، و با گزینه -v فهرستی با جزئیات شامل میزبان و دایرکتوری هر نشست ارائه می‌دهد که در آن نشست فعلی با یک ستاره مشخص شده است. با -o، به جدیدترین نشست قبلی جابه‌جا می‌شود.

با -d، نشست مشخص‌شده (یا نشست فعلی) حذف می‌شود؛ تمام موارد مربوط به آن کاملاً فراموش خواهد شد. اگر تنها نشست موجود بود، نشست جدیدی به نام «default» ایجاد شده و نشست فعلی می‌شود. امن‌تر آن است که هنگام فعال بودن دستورهای پس‌زمینه با zftp، نشست‌ها حذف نشوند.

انتقال فایل‌ها بین دو نشست؛ هیچ نسخه محلی ایجاد نمی‌شود. فایل از نشست sess1 به صورت file1 خوانده شده و در نشست sess2 به عنوان فایل file2 نوشته می‌شود؛ file1 و file2 می‌توانند نسبت به دایرکتوری‌های فعلی نشست، نسبی باشند. هر یک از sess1 یا sess2 می‌توانند حذف شوند (اگرچه در صورت احتمال وجود علامت دونقطه در نام فایل، باید دونقطه حفظ شود) و پیش‌فرض آن نشست فعلی است؛ file2 می‌تواند حذف شود یا به یک اسلش ختم گردد، که در این صورت نام پایه (basename) مربوط به file1 اضافه خواهد شد. نشست‌های sess1 و sess2 باید متمایز باشند.

عملیات با استفاده از لوله‌ها (pipes) انجام می‌شود، بنابراین لازم است که اتصالات در یک زیرپوسته (subshell) همچنان معتبر باشند، که این مورد در نگارش‌هایی از برخی سیستم‌های عامل احتمالاً به دلیل یک باگ سیستمی صدق نمی‌کند.

دو تابع zfmark و zfgoto به شما اجازه می‌دهند مکان فعلی (میزبان، کاربر و دایرکتوری) اتصال FTP کنونی را برای استفاده‌های بعدی «نشانک‌گذاری» کنید. فایلی که برای ذخیره و بازیابی نشانک‌ها استفاده می‌شود توسط پارامتر $ZFTP_BMFILE تعیین می‌شود؛ اگر هنگام فراخوانی یکی از این دو تابع تنظیم نشده باشد، روی فایل .zfbkmarks در دایرکتوری فایل‌های راه‌اندازی zsh شما (معمولاً ~) تنظیم خواهد شد.

zfmark [ bookmark ]
اگر آرگومانی داده شود، میزبان، کاربر و دایرکتوری فعلی را تحت نام bookmark برای استفاده بعدی توسط zfgoto نشانک‌گذاری می‌کند. اگر اتصالی باز نباشد، از مقادیر آخرین اتصال دقیقاً پیش از بسته شدنش استفاده می‌شود؛ اگر اتصالی وجود نداشته باشد، یک خطا است. هر نشانک موجود با نام مشابه بدون اطلاع قبلی جایگزین خواهد شد.

اگر آرگومانی داده نشود، نشانک‌های موجود و نقاطی را که به آنها اشاره دارند به صورت user@host:directory فهرست می‌کند؛ این قالبی است که در آن ذخیره می‌شوند، و فایل را می‌توان مستقیماً ویرایش کرد.

بازگشت به مکانی که توسط bookmark مشخص شده و قبلاً توسط zfmark تنظیم شده است. اگر مکان کاربر `ftp' یا `anonymous' داشته باشد، اتصال را با zfanon باز می‌کند تا نیازی به گذرواژه نباشد. اگر پارامترهای کاربر و میزبان با مقادیر ذخیره‌شده برای نشست فعلی مطابقت داشته باشد، از آنها استفاده می‌شود و مجدداً گذرواژه‌ای نیاز نخواهد بود. در غیر این صورت گذرواژه درخواست خواهد شد.

با گزینه -n، نشانک به عنوان یک نام مستعار (nickname) ذخیره‌شده توسط برنامه ncftp در فایل نشانک‌های آن در نظر گرفته می‌شود که فرض بر این است که ~/.ncftp/bookmarks باشد. تابع در سایر جهات عملکردی یکسان دارد. توجه داشته باشید که هیچ سازوکاری برای افزودن یا ویرایش نشانک‌های ncftp از طریق توابع zftp وجود ندارد.

غالباً این توابع به طور مستقیم فراخوانی نخواهند شد (به جز zfinit)، اما برای کامل بودن مستندات در اینجا شرح داده شده‌اند. به‌ویژه ممکن است مایل باشید zftp_chpwd و zftp_progress را تغییر دهید.
zfinit [ -n ]
همان‌طور که در بالا شرح داده شد، از این تابع برای راه‌اندازی اولیه سامانه توابع zftp استفاده می‌شود. اگر دستور zftp از پیش به صورت توکار درون شل وجود داشته باشد، باید از گزینه -n استفاده شود.
این تابع برای پیاده‌سازی رفتار بازگشایی خودکار فراخوانی می‌شود، همان‌طور که در ادامه با جزئیات بیشتر توضیح داده شده است. گزینه‌ها باید در نخستین آرگومان قرار گیرند؛ -n مانع از تغییر دایرکتوری دستور به دایرکتوری قبلی می‌شود، در حالی که -d مانع از تنظیم متغیر do_close توسط آن می‌گردد؛ متغیری که در غیر این صورت به عنوان نشانه‌ای برای بستن خودکار اتصال پس از یک انتقال تنظیم می‌شود. میزبان و دایرکتوری آخرین نشست در متغیر $zflastsession ذخیره می‌شوند، اما پارامترهای داخلی host/user/password نیز باید به‌درستی تنظیم شده باشند.
این تابع تطبیق را برای تکمیل خودکار نام‌های دایرکتوری‌های راه دور انجام می‌دهد. اگر کارگزار راه دور UNIX باشد، تلاش می‌کند کارگزار را ترغیب کند تا دایرکتوری راه دور را به همراه علامت‌گذاری زیردایرکتوری‌ها فهرست کند، که این روش معمولاً کار می‌کند اما تضمین‌شده نیست. در سایر میزبان‌ها صرفاً zfget_match را فراخوانی می‌کند و از این رو تمام فایل‌ها را کامل می‌کند، نه فقط دایرکتوری‌ها را. در برخی سیستم‌ها، دایرکتوری‌ها ممکن است حتی شبیه نام فایل نباشند.
این تابع تطبیق را برای تکمیل خودکار نام‌های فایل‌های راه دور انجام می‌دهد. این تابع فایل‌های دایرکتوری جاری (تنها دایرکتوری جاری) را در پارامتر شل $zftp_fcache کش می‌کند. قالب آن به‌گونه‌ای است که توسط گزینه -K دستور compctl فراخوانی شود، اما هنگامی که از یک تابع تکمیل مبتنی بر ویجت با مقادیر مناسب برای prefix و suffix فراخوانی شود نیز کار می‌کند.
تطبیق الگو (globbing) در سمت راه دور را انجام می‌دهد، همان‌طور که در ادامه با جزئیات بیشتر شرح داده شده است. varname نام متغیری است که حاوی الگوی مورد نظر برای بسط است؛ در صورت وجود هرگونه تطابق، هنگام بازگشت همان متغیر با مجموعه بسط‌یافته نام فایل‌ها مقداردهی می‌شود.
زمان تغییر فایل محلی lfile را برابر با زمان تغییر فایل راه دور rfile، یا زمان صریح time در قالب FTP به صورت CCYYMMDDhhmmSS برای منطقه زمانی GMT تنظیم می‌کند. این تابع از ماژول zsh/datetime شل برای تبدیل زمان از GMT به زمان محلی استفاده می‌کند.
این تابع هر بار که اتصالی باز یا بسته می‌شود، یا دایرکتوری راه دور تغییر می‌کند، فراخوانی می‌شود. این نسخه، نوار عنوان یک شبیه‌ساز ترمینال سازگار با xterm یا sun-cmd را برای بازتاب نام میزبان‌های محلی و راه دور و دایرکتوری‌های جاری تغییر می‌دهد. این تابع هنگامی که با تابع chpwd ترکیب شود بهترین عملکرد را دارد. به‌ویژه، تابعی به شکل
chpwd() {
  if [[ -n $ZFTP_USER ]]; then
    zftp_chpwd
  else
    # usual chpwd e.g put host:directory in title bar
  fi
}

به‌خوبی با آن سازگار است.

این تابع وضعیت انتقال را نشان می‌دهد. هیچ چیزی نخواهد نوشت مگر اینکه خروجی به یک ترمینال ارسال شود؛ با این حال، اگر فایل‌ها را در پس‌زمینه انتقال می‌دهید، باید گزارش‌های پیشرفت را دستی با استفاده از `zstyle ':zftp:*' progress none' خاموش کنید. همچنین توجه داشته باشید که اگر آن را تغییر دهید، هرگونه خروجی باید به خطای استاندارد ارسال شود، چرا که خروجی استاندارد ممکن است فایلی باشد که در حال دریافت است. شکل نشانگر پیشرفت، یا اصلاً استفاده شدن یا نشدن از آن، می‌تواند بدون تغییر دادن تابع پیکربندی شود، همان‌طور که در بخش بعدی توضیح داده شده است.
از این تابع برای پیاده‌سازی کش کردن فایل‌ها در دایرکتوری جاری به طور جداگانه برای هر نشست استفاده می‌شود. این تابع توسط zfget_match و zfrglob استفاده می‌شود.

سبک‌های گوناگونی با استفاده از سازوکار استاندارد سبک پوسته در دسترس هستند که در zshmodules(1) شرح داده شده است. به‌طور خلاصه، دستور `zstyle ':zftp:*' style value ...'. سبک style را با مقدار value تعریف می‌کند؛ می‌توان بیش از یک مقدار ارائه داد، اگرچه در موارد شرح‌داده‌شده در اینجا کاربردی ندارد. این مقادیر سپس در سراسر سامانه توابع zftp استفاده خواهند شد. برای کنترل دقیق‌تر، آرگومان نخست که الگوی مطابق با زمینه‌های (contexts) اعمال سبک را مشخص می‌کند، می‌تواند برای در برگرفتن یک تابع خاص تغییر داده شود؛ به عنوان مثال `:zftp:zfget': در این صورت، سبک داده‌شده تنها در تابع zfget اعمال خواهد شد و بر سبک‌های تعیین‌شده تحت `:zftp:*' اولویت خواهد داشت. توجه داشته باشید که تنها نام تابع سطح بالا، آن‌طور که توسط کاربر فراخوانی شده، استفاده می‌شود؛ فراخوانی توابع سطوح پایین‌تر برای کاربر شفاف (نامرئی) است. از این رو، تغییرات نوار عنوان در zftp_chpwd بسته به اینکه از کجا فراخوانی شده باشد، از زمینه‌های :zftp:zfopen، :zftp:zfcd و غیره استفاده می‌کند. سبک‌های زیر پشتیبانی می‌شوند:

progress
نحوه گزارش پیشرفت یک انتقال توسط zftp_progress را کنترل می‌کند. اگر خالی، تنظیم‌نشده، یا `none` باشد، هیچ گزارش پیشرفتی ارائه نمی‌شود؛ اگر `bar` باشد، یک نوار پیش‌رونده به‌صورت تصویر معکوس (inverse video) نمایش داده می‌شود؛ اگر `percent` (یا هر رشته دیگری، اگرچه ممکن است در آینده تغییر کند) باشد، درصد فایل منتقل‌شده نشان داده می‌شود. نوار پیشرفت نیازمند آن است که عرض ترمینال از طریق پارامتر $COLUMNS در دسترس باشد (معمولاً این مقدار به‌طور خودکار تنظیم می‌شود). اگر اندازه فایل در حال انتقال در دسترس نباشد، نمایشگرهای bar و percent صرفاً تعداد بایت‌های منتقل‌شده تا آن لحظه را نمایش می‌دهند.

هنگام اجرای zfinit، اگر این سبک برای زمینه :zftp:* تعریف نشده باشد، روی `bar` تنظیم خواهد شد.

حداقل بازه زمانی بین به‌روزرسانی‌های نمایشگر پیشرفت را به ثانیه مشخص می‌کند. هیچ به‌روزرسانی انجام نمی‌شود مگر اینکه داده جدیدی دریافت شده باشد، بنابراین بازه زمانی واقعی تنها توسط $ZFTP_TIMEOUT محدود می‌شود.

همان‌طور که برای progress شرح داده شد، zfinit این مقدار را به‌طور پیش‌فرض به 1 وادار می‌کند.

اگر روی `1`، `yes` یا `true` تنظیم شود، تولید نام فایل (تطبیق الگو یا globbing) به‌جای خود zsh، روی ماشین دوردست انجام می‌شود؛ به پایین مراجعه کنید.
اگر روی `1`، `yes` یا `true` تنظیم شود، zftp_chpwd میزبان دوردست و دایرکتوری دوردست را در نوار عنوان شبیه‌سازهای ترمینال مانند xterm یا sun-cmd که این اجازه را می‌دهند، قرار می‌دهد.

همان‌طور که برای progress شرح داده شد، zfinit این مقدار را به‌طور پیش‌فرض به 1 وادار می‌کند.

اگر روی `1`، `yes` یا `true` تنظیم شود، zftp_chpwd هنگام بسته شدن یک اتصال، تابع chpwd را فراخوانی می‌کند. این ویژگی زمانی مفید است که مشخصات میزبان دوردست توسط zftp_chpwd در نوار عنوان ترمینال قرار گرفته باشد و تابع chpwd معمول شما نیز نوار عنوان را تغییر دهد.

هنگامی که zfinit اجرا می‌شود، بررسی می‌کند که آیا chpwd وجود دارد یا خیر؛ در این صورت، اگر مقداری از پیش تعیین نشده باشد، مقدار پیش‌فرض این سبک را به 1 تنظیم خواهد کرد.

توجه داشته باشید که یک آرایه انجمنی به نام zfconfig نیز وجود دارد که شامل مقادیر استفاده‌شده توسط سامانه توابع است. این آرایه نباید تغییر داده شده یا بازنویسی شود.

دستورهای دریافت فایل معمولاً روی آرگومان‌های خود تطبیق نام فایل (globbing) را انجام می‌دهند؛ این قابلیت را می‌توان با ارسال گزینه -G به هر یک از این دستورها غیرفعال کرد. در حالت عادی، این کار با دریافت فهرست کاملی از فایل‌های دایرکتوری مورد نظر و سپس تطبیق محلی آن‌ها با الگوی ارائه‌شده انجام می‌شود. مزیت این روش آن است که می‌توان از طیف کامل الگوهای zsh (با رعایت تنظیمات گزینه EXTENDED_GLOB) بهره برد. با این حال، این بدان معناست که بخش دایرکتوری نام فایل بسط داده نخواهد شد و باید دقیقاً مشخص شود. اگر سرور دوردست از معناشناسی دایرکتوری یونیکس پشتیبانی نکند، مدیریت دایرکتوری مشکل‌ساز خواهد بود و توصیه می‌شود که تطبیق الگو تنها در دایرکتوری جاری استفاده شود. فهرست فایل‌های دایرکتوری جاری در صورت دریافت، کش (ذخیره موقت) خواهد شد تا تطبیق‌های بعدی در همان دایرکتوری بدون اجرای دستور میانی zfcd بسیار سریع‌تر انجام شوند.

اگر سبک remote-glob (به بالا مراجعه کنید) تنظیم شده باشد، تطبیق الگو در عوض روی میزبان دوردست انجام می‌شود: از سرور فهرستی از فایل‌های منطبق درخواست می‌شود. این امر به‌شدت به نحوه پیاده‌سازی سرور وابسته است، اگرچه سرورهای یونیکس معمولاً از الگوهای پایه glob پشتیبانی می‌کنند. این روش در برخی موارد می‌تواند سریع‌تر باشد، زیرا از دریافت کل محتویات دایرکتوری جلوگیری می‌کند.

همان‌طور که برای دستور zfopen شرح داده شد، اجرای متعاقب zfopen بدون هیچ پارامتری اتصال به آخرین میزبان را مجدداً باز خواهد کرد (این شامل اتصالات برقرارشده با دستور zfanon نیز می‌شود). اتصال بازشده به این شیوه، در دایرکتوری دوردست پیش‌فرض آغاز شده و تا زمانی که صریحاً بسته نشود باز خواهد ماند.

بازگشایی خودکار نیز در دسترس است. اگر اتصالی در حال حاضر باز نباشد و دستوری صادر شود که به اتصال نیاز دارد، آخرین اتصال به‌طور ضمنی مجدداً باز می‌شود. در این حالت، دایرکتوری‌ای که هنگام بسته شدن اتصال جاری بود، دوباره به دایرکتوری جاری تبدیل می‌شود (مگر این‌که البته دستور صادرشده آن را تغییر دهد). بازگشایی خودکار همچنین در صورتی که اتصال به هر دلیلی توسط سرور دوردست بسته شده باشد (مانند وقفه زمانی یا timeout) رخ خواهد داد. اگر از گزینهٔ -1 برای zfopen یا zfanon استفاده شده باشد، این قابلیت در دسترس نیست.

علاوه بر این، اگر دستور صادرشده یک انتقال فایل باشد، اتصال پس از اتمام انتقال بسته خواهد شد، و بدین ترتیب یک حالت تک‌باره (one-shot) را برای انتقال‌ها فراهم می‌کند. این موضوع در مورد دستورهای تغییر دایرکتوری یا فهرست‌گیری صدق نمی‌کند؛ به عنوان مثال یک دستور zfdir ممکن است اتصال را مجدداً باز کند اما آن را باز نگه خواهد داشت. همچنین، بسته شدن خودکار تنها در همان دستوری رخ می‌دهد که بازگشایی خودکار در آن انجام شده است، یعنی یک zfdir که بلافاصله پس از آن zfget اجرا شود، هرگز اتصال را به‌طور خودکار نخواهد بست.

اطلاعات دربارهٔ اتصال قبلی توسط تابع zfstat ارائه می‌شود. بنابراین، به عنوان مثال، اگر آن تابع چنین گزارش دهد:

Session:        default
Not connected.
Last session:   ftp.bar.com:/pub/textfiles

آنگاه دستور zfget file.txt تلاش خواهد کرد تا اتصال به ftp.bar.com را مجدداً باز کند، فایل /pub/textfiles/file.txt را دریافت نماید، و سپس بلافاصله اتصال را دوباره ببندد. از طرف دیگر، zfcd .. اتصال را در دایرکتوری /pub باز کرده و آن را باز نگه خواهد داشت.

توجه داشته باشید که تمام موارد بالا محلی و مختص هر نشست است؛ اگر به یک نشست قبلی بازگردید، اتصالی که مجدداً باز خواهد شد اتصال مربوط به همان نشست است.

تکمیل خودکار فایل‌ها، دایرکتوری‌ها، نشست‌ها و نشانک‌های محلی و دوردست پشتیبانی می‌شود. تکمیل قدیمی‌تر به سبک compctl هنگام فراخوانی zfinit تعریف می‌شود؛ پشتیبانی از سیستم تکمیل جدیدِ مبتنی بر ابزارک در تابع Completion/Zsh/Command/_zftp ارائه شده است، که باید همراه با دیگر توابع سیستم تکمیل نصب شده باشد و در نتیجه باید به‌طور خودکار در دسترس باشد.

July 12, 2026 zsh 5.9.2