ZSHTCPSYS(1) General Commands Manual ZSHTCPSYS(1)

zshtcpsys - سامانه ارتباط TCP در zsh

ماژول zsh/net/tcp برای فراهم کردن ورودی/خروجی شبکه از طریق TCP/IP از درون پوسته ارائه شده است؛ توضیحات آن را در zshmodules(1) ببینید. این صفحه راهنما مجموعه‌ای از توابع مبتنی بر این ماژول را شرح می‌دهد. اگر ماژول نصب شده باشد، این توابع معمولاً به‌طور هم‌زمان نصب می‌شوند و در این صورت برای بارگذاری خودکار در مسیر جستجوی پیش‌فرض توابع در دسترس خواهند بود. علاوه بر ماژول zsh/net/tcp، ماژول zsh/zselect نیز برای پیاده‌سازی مهلت زمانی (timeout) روی عملیات خواندن به کار می‌رود. برای نکات عیب‌یابی، به توصیه‌های مربوط به توابع zftp شرح‌داده‌شده در zshzftpsys(1) مراجعه کنید.

توابعی متناظر با عملیات پایه ورودی/خروجی باز کردن، بستن، خواندن و ارسال وجود دارند که با نام‌های tcp_open و غیره شناخته می‌شوند؛ همچنین تابع tcp_expect برای تحلیل تطبیق الگو بر روی داده‌های خوانده‌شده به عنوان ورودی در دسترس است. این سامانه دریافت و ارسال داده‌ها را به‌طور هم‌زمان از و به چندین نشست (session) نام‌گذاری‌شده آسان می‌سازد. علاوه بر این، می‌تواند با ویرایشگر خط پوسته پیوند داده شود تا داده‌های ورودی به‌صورت خودکار در پایانه نمایش داده شوند. از دیگر امکانات موجود می‌توان به ثبت وقایع (logging)، پالایش (filtering) و خط اعلان‌های خروجی با قابلیت پیکربندی اشاره کرد.

برای استفاده از این سامانه در جاهایی که در دسترس است، کافی است دستور `autoload -U tcp_open' را اجرا کرده و طبق مستندات زیر tcp_open را برای شروع یک نشست اجرا کنید. تابع tcp_open سایر توابع را به‌طور خودکار بارگذاری خواهد کرد.

tcp_open [ -qz ] host port [ sess ]
tcp_open [ -qz ] [ -s sess | -l sess[,...] ] ...
tcp_open [ -qz ] [ -a fd | -f fd ] [ sess ]
یک نشست جدید باز می‌کند. در حالت اول و ساده‌ترین حالت، یک اتصال TCP به میزبان host روی درگاه port باز می‌کند؛ قالب‌های عددی و نمادین برای هر دو پشتیبانی می‌شوند.

اگر sess داده شود، این مقدار نام نشستی می‌شود که می‌تواند برای ارجاع به چندین اتصال TCP گوناگون استفاده شود. اگر sess داده نشود، تابع یک مقدار نام عددی ایجاد می‌کند (توجه داشته باشید که این مقدار با توصیف‌گر فایلی که نشست به آن متصل است یکی نیست). توصیه می‌شود نام‌های نشست شامل نویسه‌های «عجیب» نباشند؛ نویسه‌های عجیب تعریف دقیقی ندارند اما مسلماً شامل حروف و اعداد یا خط زیرین (underscore) نبوده و قطعاً شامل نویسه‌های فاصله (whitespace) می‌شوند.

در حالت دوم، یک یا چند نشست که باید باز شوند با نام مشخص می‌شوند. یک نام نشست تکی پس از -s و یک فهرست جداشده با کاما پس از -l می‌آید؛ هر دو گزینه می‌توانند به تعداد دفعات مورد نیاز تکرار شوند. بروز خطا در باز کردن هر یک از نشست‌ها باعث توقف tcp_open می‌شود. میزبان و پورت از فایل .ztcp_sessions واقع در همان دایرکتوری فایل‌های راه‌اندازی zsh کاربر، یعنی معمولاً دایرکتوری خانه، و در صورت تنظیم بودن متغیر از $ZDOTDIR خوانده می‌شوند. این فایل شامل خطوطی است که هر کدام به ترتیب نام نشست و میزبان و پورت متناظر را با فاصله از یکدیگر مشخص می‌کنند (توجه داشته باشید که نام نشست در ابتدا می‌آید، نه در انتها).

حالت سوم اتصالات TCP مجهول (passive) و ساختگی (fake) را ممکن می‌سازد. اگر گزینه -a به کار رود، آرگومان آن یک توصیف‌گر فایل خواهد بود که برای گوش دادن به اتصالات باز شده است. هیچ تابع مستقیمی برای باز کردن چنین توصیف‌گر فایلی ارائه نشده است، اما فراخوانی `ztcp -l port' یکی ایجاد می‌کند که توصیف‌گر فایل آن در پارامتر $REPLY ذخیره می‌شود. پورت شنود را می‌توان با `ztcp -c fd' بست. فراخوانی `tcp_open -a fd' تا زمانی که یک اتصال TCP دوردست به port روی ماشین محلی برقرار شود مسدود خواهد شد. در این نقطه، نشست به شیوه معمول ساخته می‌شود و تا حد زیادی از اتصال فعالی که با دو حالت اول ایجاد شده قابل تشخیص نیست.

اگر گزینه -f استفاده شود، آرگومان آن یک توصیف‌گر فایل است که مستقیماً به گونه‌ای استفاده می‌شود که گویی یک نشست TCP است. اینکه بخش‌های دیگر سامانه توابع TCP تا چه حد با این شرایط سازگار باشند به این بستگی دارد که ماهیت اصلی آن توصیف‌گر فایل چیست. یک فایل معمولی احتمالاً غیرقابل‌استفاده خواهد بود؛ یک FIFO (لوله) به نوعی بهتر کار خواهد کرد، اما توجه داشته باشید که تلاش هم‌زمان دو نشست مختلف برای خواندن از یک FIFO مشترک ایده خوبی نیست.

اگر گزینه -q به همراه هر یک از این سه حالت داده شود، tcp_open پیام‌های آگاهی‌رسانی را چاپ نخواهد کرد، اگرچه در هر حال با وضعیت مناسب خارج می‌شود.

اگر ویرایشگر خط (zle) در حال استفاده باشد، که معمولاً در پوسته‌های تعاملی همین‌طور است، tcp_open یک گرداننده (handler) درون zle نصب می‌کند که هم‌زمان با بررسی ورودی صفحه‌کلید، داده‌های جدید را نیز بررسی می‌کند. این ویژگی بسیار سودمند است زیرا پوسته در زمان انتظار هیچ زمان CPU مصرف نمی‌کند؛ این بررسی توسط سیستم‌عامل انجام می‌گیرد. دادن گزینه -z به هر یک از حالت‌های tcp_open مانع از نصب این گرداننده می‌شود، بنابراین داده‌ها باید به‌طور صریح خوانده شوند. با این حال، توجه داشته باشید که این کار برای اجرای مجموعه‌های کاملی از دستورات ارسال و خواندن از درون یک تابع الزامی نیست، زیرا zle در آن هنگام فعال نیست. به‌طور کلی، این گرداننده تنها زمانی فعال است که پوسته در اعلان اعلان فرمان یا در دستور توکار vared منتظر ورودی باشد. این گزینه در صورتی که zle فعال نباشد هیچ تأثیری ندارد؛ دستور `[[ -o zle]]' این مورد را بررسی خواهد کرد.

نخستین نشستی که باز شود تبدیل به نشست جاری می‌شود و فراخوانی‌های بعدی tcp_open آن را تغییر نمی‌دهند. نشست جاری در پارامتر $TCP_SESS ذخیره می‌شود؛ برای جزئیات بیشتر در مورد پارامترهای مورداستفاده این سامانه بخش‌های بعد را ببینید.

تابع tcp_on_open، در صورت تعریف شدن، هنگام باز شدن یک نشست فراخوانی می‌شود. توضیحات زیر را ببینید.

نشست‌های نام‌برده‌شده را می‌بندد، یا اگر هیچ موردی مشخص نشده باشد نشست جاری را، یا در صورت دادن گزینه -a تمامی نشست‌های باز را می‌بندد. گزینه‌های -l و -s هر دو برای سازگاری با tcp_open پشتیبانی می‌شوند، هرچند گزینه دوم تکراری و زائد است.

اگر نشستی که بسته می‌شود نشست جاری باشد، مقدار $TCP_SESS حذف می‌شود (unset)، به طوری که هیچ نشستی جاری نخواهد ماند، حتی اگر نشست‌های دیگری همچنان باز باشند.

اگر نشست با tcp_open -f باز شده باشد، توصیف‌گر فایل تا زمانی که در بازه 0 تا 9 بوده و مستقیماً از خط فرمان قابل دسترس باشد، بسته می‌شود. اگر گزینه -n داده شود، در این حالت هیچ تلاشی برای بستن توصیف‌گرهای فایل صورت نمی‌گیرد. گزینه -n برای نشست‌های واقعی ztcp استفاده نمی‌شود؛ توصیف‌گرهای فایل در آن‌ها همواره همراه با نشست بسته می‌شوند.

اگر گزینه -q داده شود، هیچ پیام آگاهی‌رسانی چاپ نخواهد شد.

tcp_read [ -bdq ] [ -t TO ] [ -T TO ]
[ -a | -u fd[,...] | -l sess[,...] | -s sess ... ]
عملیات خواندن را روی نشست جاری، یا روی فهرستی از نشست‌ها اگر با -u، -l یا -s مشخص شده باشند، یا روی تمامی نشست‌های باز در صورت ارائه گزینه -a انجام می‌دهد. هر یک از گزینه‌های -u، -l یا -s را می‌توان تکرار کرد یا با یکدیگر ترکیب نمود. گزینه -u یک توصیف‌گر فایل را مستقیماً مشخص می‌کند (تنها مواردی که توسط این سامانه مدیریت می‌شوند مفید هستند)، و دو گزینه دیگر نشست‌ها را همان‌طور که برای tcp_open در بالا ذکر شد مشخص می‌کنند.

این تابع وجود داده‌های جدید در تمامی نشست‌های فهرست‌شده را بررسی می‌کند. مگر اینکه گزینه -b داده شده باشد، برای داده‌های جدید مسدود نخواهد شد (در حالت انتظار نخواهد ماند). هر تک سطری از داده‌ها از هر یک از نشست‌های موجود خوانده شده، در پارامتر $TCP_LINE ذخیره می‌شود و در خروجی استاندارد نمایش داده می‌شود مگر آنکه $TCP_SILENT حاوی یک رشته غیرخالی باشد. هنگام چاپ در خروجی استاندارد، رشته $TCP_PROMPT در ابتدای سطر نشان داده خواهد شد؛ ساختار پیش‌فرض برای این مورد شامل نام نشستی است که در حال خوانده شدن است. برای اطلاعات بیشتر درباره این پارامترها به بخش‌های بعد مراجعه کنید. در این حالت، می‌توان tcp_read را مکرراً فراخوانی کرد تا زمانی که وضعیت 2 را برگرداند که نشان می‌دهد تمامی ورودی‌های معلق از همه نشست‌های مشخص‌شده پردازش شده‌اند.

با گزینه -b، که معادل مهلت زمانی نامحدود است، تابع تا زمانی که سطری برای خواندن از یکی از نشست‌های مشخص‌شده در دسترس باشد مسدود می‌ماند. با این حال، تنها یک سطر بازگردانده می‌شود.

گزینه -d مشخص می‌کند که تمام ورودی‌های معلق باید تخلیه شوند. در این حالت، tcp_read ممکن است چندین سطر را به روش بالا پردازش کند؛ تنها آخرین سطر در $TCP_LINE ذخیره می‌شود، اما مجموعه کامل در آرایه $tcp_lines نگهداری خواهد شد. این آرایه در شروع هر فراخوانی از tcp_read پاک می‌شود.

گزینه‌های -t و -T یک مهلت زمانی بر حسب ثانیه را مشخص می‌کنند، که برای دقت بیشتر می‌تواند یک عدد ممیز شناور باشد. با -t این مهلت زمانی قبل از خواندن هر سطر اعمال می‌شود. با -T، مهلت زمانی برای کل عملیات اعمال می‌گردد که در صورت وجود گزینه -d می‌تواند شامل چندین عملیات خواندن باشد؛ بدون این گزینه، تفاوتی میان -t و -T وجود ندارد.

این تابع پیام‌های آگاهی‌رسانی چاپ نمی‌کند، اما اگر گزینه -q داده شود، هیچ پیام خطایی برای یک نشست ناموجود چاپ نخواهد شد.

وضعیت بازگشتی 2 نشان‌دهنده پایان مهلت زمانی یا نبود داده برای خواندن است. هر وضعیت بازگشتی غیرصفر دیگری نشان‌دهنده شرایط بروز خطا است..PP برای چگونگی واپایش محل ارسال داده‌ها توسط tcp_read، به tcp_log مراجعه کنید.

tcp_send [ -cnq ] [ -s sess | -l sess[,...] ] data ...
tcp_send [ -cnq ] -a data ...
رشته‌های داده ارائه‌شده را به نوبت به تمام نشست‌های مشخص‌شده ارسال می‌کند. عملیات زیرین تفاوت چندانی با یک `print -r' بر روی توصیف‌کننده فایل نشست ندارد، اگرچه تلاش می‌کند تا از بسته شدن پوسته به دلیل سیگنال SIGPIPE ناشی از تلاش برای نوشتن در یک نشست ازکارافتاده جلوگیری کند.

گزینه -c باعث می‌شود tcp_send مانند cat رفتار کند. این گزینه خطوط را از ورودی استاندارد تا پایان ورودی می‌خواند و آن‌ها را به نوبت به نشست(های) مشخص‌شده ارسال می‌کند، دقیقاً به گونه‌ای که گویی به عنوان آرگومان‌های data به دستورهای جداگانه tcp_send داده شده‌اند.

گزینه -n مانع از قرار دادن یک خط جدید (newline) توسط tcp_send در انتهای رشته‌های داده می‌شود.

بقیه گزینه‌ها همگی رفتاری مشابه tcp_read دارند.

آرگومان‌های داده پس از ارسال به tcp_send پردازش بیشتری نمی‌شوند؛ آن‌ها صرفاً به print -r منتقل می‌شوند.

اگر پارامتر $TCP_OUTPUT یک رشته غیرخالی باشد و ثبت وقایع فعال باشد، داده‌های ارسال‌شده به هر نشست در صورت لزوم با قرار گرفتن $TCP_OUTPUT در جلوی آن در فایل(های) گزارش منعکس می‌شوند، بسیار شبیه به شیوه $TCP_PROMPT.

tcp_alias [ -q ] alias=sess ...
tcp_alias [ -q ] [ alias ... ]
tcp_alias -d [ -q ] alias ...
این تابع چندان خوب آزمایش نشده است.

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

شکل دوم نام‌های مستعار مشخص‌شده را فهرست می‌کند، یا در صورت تعیین نشدن، تمام نام‌های مستعار را نمایش می‌دهد.

شکل سوم تمام نام‌های مستعار فهرست‌شده را حذف می‌کند. نشست‌های زیرین تحت تأثیر قرار نمی‌گیرند.

گزینه -q زیرمجموعه‌ای ناهمگون از پیام‌های خطا را فرونشانی می‌کند.

با یک آرگومان logfile، تمام ورودی‌های آینده از tcp_read در فایل نام‌برده ثبت خواهند شد. مگر اینکه -a (الحاق) داده شده باشد، این فایل ابتدا کوتاه شده (خالی) یا به صورت خالی ایجاد می‌شود. بدون آرگومان، وضعیت فعلی ثبت گزارش نمایش داده می‌شود.

با گزینه -s، ثبت وقایع به ازای هر نشست فعال می‌شود. ورودی از tcp_read به فایل logfile.sess خروجی داده می‌شود. از آنجا که نشست به طور خودکار از طریق نام فایل تفکیک می‌شود، محتویات خام هستند (بدون $TCP_PROMPT). گزینه -a مانند بالا اعمال می‌شود. ثبت وقایع به ازای هر نشست و ثبت تمام داده‌ها در یک فایل با یکدیگر مانعة‌الجمع نیستند.

گزینه -c تمام گزارش‌گیری‌ها، چه گزارش‌های کامل و چه گزارش‌های به ازای هر نشست را می‌بندد.

گزینه‌های -n و -N به ترتیب خروجی داده‌های خوانده‌شده توسط tcp_read به خروجی استاندارد را خاموش یا بازیابی می‌کنند؛ بنابراین `tcp_log -cn' تمام خروجی‌های tcp_read را خاموش می‌کند.

این تابع صرفاً یک رابط ساده برای تنظیم پارامترهای $TCP_LOG، $TCP_LOG_SESS و $TCP_SILENT است که در زیر شرح داده شده‌اند.

تغییر نام نشست old به نشست new. نام قدیمی نامعتبر می‌شود.
بدون آرگومان، تمام نشست‌های باز و توصیف‌کننده‌های فایل مرتبط را فهرست می‌کند. نشست جاری با یک ستاره علامت‌گذاری می‌شود. برای استفاده در توابع، دسترسی مستقیم به پارامترهای $tcp_by_name، $tcp_by_fd و $TCP_SESS احتمالاً راحت‌تر است؛ زیر را ببینید.

با یک آرگومان sess، نشست جاری روی sess تنظیم می‌شود. این معادل تغییر مستقیم $TCP_SESS است.

با آرگومان‌های اضافی، هنگام اجرای `command arg ...'، نشست جاری به طور موقت تنظیم می‌شود. command دوباره ارزیابی می‌شود تا نام‌های مستعار و غیره بسط یابند، اما بقیه argها همان‌گونه که به tcp_sess داده شده‌اند منتقل می‌شوند. نشست اصلی هنگامی که tcp_sess خارج می‌شود بازگردانده می‌شود.

tcp_command send-option ... send-argument ...
این یک رابط کاربری مناسب برای tcp_send است. تمام آرگومان‌ها به tcp_send فرستاده می‌شوند، سپس تابع منتظر داده می‌ماند. تا زمانی که داده‌ها دست‌کم هر $TCP_TIMEOUT ثانیه یک‌بار (پیش‌فرض ۰.۳ ثانیه) می‌رسند، داده‌ها مطابق با تنظیمات فعلی مدیریت شده و چاپ می‌شوند. وضعیت ۰ همیشه بازگردانده می‌شود.

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

tcp_expect [ -q ] [ -p var | -P var ] [ -t TO | -T TO ]
[ -a | -s sess | -l sess[,...] ] pattern ...
منتظر ورودی تطبیق‌یافته با هر یک از patternهای ارائه‌شده از هر یک از نشست‌های مشخص‌شده می‌ماند. ورودی تا زمانی که یک خط ورودی با یکی از الگوهای ارائه‌شده تطبیق یابد نادیده گرفته می‌شود؛ در این هنگام وضعیت صفر بازگردانده می‌شود، خط منطبق‌شده در $TCP_LINE ذخیره می‌گردد و مجموعه کامل خطوط خوانده‌شده در طول فراخوانی tcp_expect در آرایه $tcp_expect_lines ذخیره می‌شود.

نشست‌ها به همان روش tcp_read مشخص می‌شوند: پیش‌فرض استفاده از نشست فعلی است، در غیر این صورت نشست‌های مشخص‌شده توسط -a، -s یا -l استفاده می‌شوند.

هر pattern یک الگوی استاندارد extended-globbing در zsh است؛ توجه داشته باشید که باید درون نقل‌قول قرار گیرد تا از بسط فوری آن توسط تولید نام فایل جلوگیری شود. الگو باید با کل خط مطابقت داشته باشد، بنابراین برای تطبیق یک زیررشته باید یک «*» در ابتدا و انتهای آن وجود داشته باشد. خطی که بررسی می‌شود شامل $TCP_PROMPT اضافه‌شده توسط tcp_read است. می‌توان پرچم‌های globbing نظیر «#b» یا «#m» را در الگوها گنجاند تا ارجاع‌های بازگشتی در پارامترهای $MATCH، $match و غیره، همان‌طور که در مستندات پایه zsh در مورد تطبیق الگو شرح داده شده، در دسترس قرار گیرند.

برخلاف tcp_read، رفتار پیش‌فرض tcp_expect این است که به‌طور نامحدود مسدود بماند تا ورودی مورد نظر یافت شود. این رفتار را می‌توان با تعیین مهلت زمانی با -t یا -T تغییر داد؛ این‌ها مشابه tcp_read عمل می‌کنند و به‌ترتیب مهلت زمانی به ازای هر خواندن یا مهلت زمانی کلی را برحسب ثانیه، به صورت یک عدد صحیح یا ممیز شناور مشخص می‌سازند. مانند tcp_read، در صورت اتمام مهلت زمانی، تابع وضعیت ۲ را بازمی‌گرداند.

تابع به محض مطابقت با هر یک از الگوهای ارائه‌شده بازمی‌گردد. اگر فراخواننده نیاز داشته باشد بداند کدام یک از الگوها تطبیق یافته است، می‌توان از گزینه -p var استفاده کرد؛ هنگام بازگشت، $var با استفاده از نمایه‌گذاری عادی zsh به شماره الگو تنظیم می‌شود، یعنی اولی ۱ است و به همین ترتیب. به عدم وجود «$» قبل از var توجه کنید. برای جلوگیری از تداخل، نام پارامتر نمی‌تواند با «_expect» شروع شود. در صورت اتمام مهلت زمانی از نمایه -۱ و در صورت عدم تطابق از ۰ استفاده می‌شود.

گزینه -P var عملکردی مشابه با -p دارد، اما به جای نمایه‌های عددی، آرگومان‌های عادی باید با یک پیشوند و به دنبال آن دو نقطه (:) شروع شوند: سپس از آن پیشوند به عنوان یک برچسب استفاده می‌شود که در صورت تطابق آرگومان، var به آن تنظیم می‌گردد. در صورت اتمام مهلت زمانی از برچسب timeout و در صورت عدم تطابق از رشته خالی استفاده می‌شود. توجه داشته باشید که اگر نیازی به تفکیک تطابق‌ها نباشد، شروع آرگومان‌های مختلف با یک پیشوند یکسان مجاز است.

گزینه -q مستقیماً به tcp_read ارسال می‌شود.

از آنجا که تمام ورودی‌ها از طریق tcp_read انجام می‌شوند، تمام قوانین معمول در مورد خروجی خطوط خوانده‌شده اعمال می‌گردند. یک استثنا این است که پارامتر $tcp_lines تنها خطی را منعکس می‌کند که واقعاً توسط tcp_expect تطبیق یافته است؛ برای دسترسی به مجموعه کامل خطوط خوانده‌شده در طول فراخوانی تابع، از $tcp_expect_lines استفاده کنید.

این یک تابع ساده برای پذیرش یک اتصال TCP و اجرای یک دستور با ورودی/خروجی تغییرمسیریافته به آن اتصال است. باید احتیاط شدیدی به کار بست زیرا هیچ‌گونه امنیتی وجود ندارد و این کار می‌تواند رایانه شما را به روی تمام دنیا باز بگذارد. در حالت ایده‌آل، این دستور فقط باید پشت یک فایروال استفاده شود.

آرگومان اول، پورت TCP است که تابع روی آن گوش خواهد داد.

آرگومان‌های باقی‌مانده، یک دستور و آرگومان‌های آن را مشخص می‌کنند که باید با ورودی استاندارد، خروجی استاندارد و خطای استانداردِ تغییرمسیریافته به توصیف‌گر فایلی که نشست TCP روی آن پذیرفته شده است، اجرا شود. اگر دستوری داده نشود، یک zsh جدید راه‌اندازی می‌شود. این کار به همه افراد حاضر در شبکه شما دسترسی مستقیم به حسابتان می‌دهد، که در بسیاری از موارد اتفاق بدی خواهد بود.

دستور در پس‌زمینه اجرا می‌شود، بنابراین tcp_proxy می‌تواند اتصالات جدید را نیز بپذیرد. این تابع تا زمان متوقف شدن به پذیرش اتصالات جدید ادامه می‌دهد.

دستور «cmd [ arg ... ]» را به نوبت برای هر نشست اجرا می‌کند. توجه داشته باشید که این دستور، برنامه و آرگومان‌ها را اجرا می‌کند؛ خط فرمان را به عنوان داده ارسال نمی‌کند مگر اینکه گزینه -t (ارسال) مشخص شده باشد.

نشست‌ها می‌توانند به صورت صریح با گزینه‌های استاندارد -a، -s یا -l انتخاب شوند، یا به صورت ضمنی تعیین گردند. اگر هیچ‌یک از این سه گزینه داده نشود، قوانین به این صورت هستند: اول، اگر آرایه $tcp_spam_list مقداردهی شده باشد، به عنوان فهرست نشست‌ها در نظر گرفته می‌شود، در غیر این صورت تمام نشست‌ها منظور می‌شوند. دوم، هر نشستی که در آرایه $tcp_no_spam_list آمده باشد از فهرست نشست‌ها حذف می‌گردد.

معمولاً هر نشستی که توسط پرچم «-a» اضافه شده باشد یا زمانی که تمام نشست‌ها به صورت ضمنی انتخاب شده باشند، به ترتیب الفبایی پردازش می‌شوند؛ نشست‌هایی که توسط آرایه $tcp_spam_list یا در خط فرمان مشخص شده‌اند به همان ترتیبی که ارائه شده‌اند پردازش می‌گردند. پرچم -r ترتیب حاصل را معکوس می‌کند.

پرچم -v مشخص می‌کند که قبل از هر نشست یک $TCP_PROMPT چاپ شود. این خروجی پس از هرگونه تغییر در TCP_SESS توسط تابع تعریف‌شده توسط کاربر tcp_on_spam که در زیر توضیح داده شده است، چاپ می‌شود. (بدیهی است که آن تابع می‌تواند خروجی اختصاصی خود را تولید کند.)

اگر گزینه -e وجود داشته باشد، خط ارائه‌شده به عنوان «cmd [ arg ... ]» با استفاده از eval اجرا می‌شود، در غیر این صورت بدون پردازش اضافی اجرا خواهد شد.

این تلاشی نسبتاً ساده برای هدایت مستقیم ورودی‌های ویرایشگر خط به TCP_SESS پیش‌فرض است.

یک رشته گریز (escape string)، با متغیر $TCP_TALK_ESCAPE و مقدار پیش‌فرض «:»، برای دسترسی به عملکردهای عادی شل استفاده می‌شود. اگر این رشته به تنهایی در ابتدای خط قرار گیرد، یا فقط فاصله‌های خالی بعد از آن بیایند، ویرایشگر خط به عملکرد عادی برمی‌گردد. در غیر این صورت، آن رشته و فاصله‌های خالیِ پس از آن نادیده گرفته شده و باقی خط به عنوان ورودی شل، بدون تغییر وضعیت عملکرد ویرایشگر خط، اجرا می‌شود.

پیاده‌سازی فعلی از نظر استفاده از تاریخچه دستورها تا حدی ناقص است. به همین دلیل، بسیاری از کاربران ترجیح می‌دهند از روش‌های جایگزین برای ارسال آسان داده به نشست فعلی استفاده کنند. یک رویکرد ساده این است که یک نویسه خاص (مانند «%») را به «tcp_command --» نام‌مستعار (alias) کنید.

تنها آرگومان آن یک عدد صحیح یا ممیز شناور است که زمان تأخیر را برحسب ثانیه مشخص می‌کند. شل در طول این مدت هیچ کاری به جز انتظار برای ورودی در تمام نشست‌های TCP از طریق فراخوانی tcp_read -a انجام نخواهد داد. این رفتار شبیه به رفتار تعاملی در خط فرمان هنگام نصب بودن کنترل‌کننده‌های zle است.
tcp_point port
tcp_shoot host port
این جفت تابع روش ساده‌ای را برای انتقال فایل میان دو میزبان از درون پوسته فراهم می‌کنند. با این حال، توجه داشته باشید که انتقال داده‌های حجیم در حال حاضر با استفاده از cat انجام می‌شود. tcp_point هر داده‌ای را که به port می‌رسد خوانده و به خروجی استاندارد ارسال می‌کند؛ tcp_shoot به port روی host متصل شده و ورودی استاندارد خود را ارسال می‌نماید. هر port استفاده‌نشده‌ای می‌تواند به کار رود؛ سازوکار معمول برای انتخاب درگاه این است که یک عدد چهار رقمی تصادفی بالاتر از 1024 را در نظر بگیرید تا زمانی که یکی از آن‌ها کار کند.

برای انتقال یک فایل از میزبان woodcock به میزبان springes، روی springes:

tcp_point 8091 >output_file

و روی woodcock:

tcp_shoot springes 8091 <input_file

از آنجا که این دو تابع برای برپایی اتصال TCP در ابتدا نیازی به tcp_open ندارند، ممکن است لازم باشد به طور جداگانه با autoload بارگذاری شوند.

توابع خاصی در صورت تعریف توسط کاربر، توسط سامانهٔ توابع در شرایط و زمینه‌های خاصی فراخوانی می‌شوند. این قابلیت به ماژول zsh/parameter وابسته است که معمولاً در پوسته‌های تعاملی در دسترس است زیرا سامانهٔ کامل‌سازی (completion) به آن متکی است. نیازی نیست هیچ‌یک از این توابع تعریف شوند؛ آن‌ها صرفاً در مواقع نیاز، قلاب‌های (hooks) مناسبی را فراهم می‌کنند.

معمولاً این توابع پس از انجام عمل درخواستی فراخوانی می‌شوند تا پارامترهای مختلف نشان‌دهندهٔ وضعیت جدید باشند.

tcp_on_alias alias fd
هنگامی که یک نام مستعار تعریف می‌شود، این تابع با دو آرگومان فراخوانی خواهد شد: نام مستعار، و توصیف‌گر فایل نشست مربوطه.
اگر تابع tcp_fd_handler در حال مدیریت ورودی از ویرایشگر خط فرمان باشد و تشخیص دهد که توصیف‌گر فایل دیگر قابل استفاده مجدد نیست، به طور پیش‌فرض آن را از فهرست توصیف‌گرهای فایلی که با این روش مدیریت می‌شوند حذف کرده و پیامی را چاپ می‌کند. اگر تابع tcp_on_awol تعریف شده باشد، بلافاصله قبل از این نقطه فراخوانی می‌شود. این تابع می‌تواند وضعیت 100 را بازگرداند که نشان می‌دهد رسیدگی عادی همچنان باید انجام شود؛ هر وضعیت بازگشتی دیگری نشان می‌دهد که هیچ اقدام دیگری نباید انجام گیرد و tcp_fd_handler باید بلافاصله با وضعیت داده‌شده بازگردد. به طور معمول عملکرد tcp_on_awol بستن نشست خواهد بود.

اگر باطل کردن صفحهٔ نمایش ویرایشگر خط با استفاده از `zle -I' پیش از چاپ خروجی از تابع ضروری باشد، متغیر TCP_INVALIDATE_ZLE یک رشتهٔ غیرخالی خواهد بود.

(اصطلاح `AWOL' یک اصطلاح نظامی مخفف `absent without leave' [غیبت بدون مرخصی] یا گونه‌ای از آن است. تا آنجا که نویسنده می‌داند هیچ مفهوم فنی قبلی شناخته‌شده‌ای ندارد.)

این تابع با نام نشستی که در حال بسته شدن است و توصیف‌گر فایل متناظر با آن نشست فراخوانی می‌شود. تا زمان فراخوانی تابع، هر دوی آن‌ها نامعتبر خواهند بود.
این تابع پس از تعریف یک نشست جدید با نام نشست و توصیف‌گر فایل به عنوان آرگومان فراخوانی می‌شود. اگر وضعیتی غیر صفر را بازگرداند، باز کردن نشست ناموفق در نظر گرفته شده و نشست دوباره بسته می‌شود؛ با این حال، tcp_open به تلاش برای باز کردن بقیه نشست‌های مشخص‌شده در خط فرمان ادامه خواهد داد.
این تابع پس از تغییر نام یک نشست، با سه آرگومان نام قدیمی نشست، توصیف‌گر فایل و نام جدید نشست فراخوانی می‌شود.
این تابع برای هر نشستی که عملیات ارسال همگانی (spam) روی آن انجام می‌گیرد، دقیقاً پیش از اجرای یک دستور برای آن نشست توسط tcp_spam، یک بار فراخوانی می‌شود. آرگومان‌ها شامل نام نشست و به دنبال آن فهرست دستورات آمادهٔ اجرا هستند. اگر tcp_spam با گزینهٔ -t فراخوانی شده باشد، اولین دستور tcp_send خواهد بود.

این تابع پس از آن‌که $TCP_SESS برای انعکاس نشستی که باید به آن ارسال همگانی شود تنظیم شد، اما پیش از هرگونه استفاده از آن فراخوانی می‌شود. از این رو می‌توان مقدار $TCP_SESS را درون این تابع تغییر داد. برای مثال، آرگومان‌های نشست در tcp_spam می‌توانند شامل اطلاعات اضافی باشند تا در tcp_on_spam جدا شده و پردازش گردند.

اگر این تابع پارامتر $REPLY را برابر با `done' قرار دهد، خط فرمان اجرا نمی‌شود؛ علاوه بر این، هیچ اعلانی برای گزینهٔ -v در tcp_spam چاپ نخواهد شد.

این تابع پس از حذف یک نام مستعار، با نام مستعار و توصیف‌گر فایلِ نشست مربوط به آن فراخوانی می‌شود.

توابع زیر توسط سامانهٔ توابع TCP استفاده می‌شوند، اما به ندرت (یا هرگز) نیاز به فراخوانی مستقیم آن‌ها خواهد بود.

tcp_fd_handler
این تابعی است که توسط tcp_open برای مدیریت ورودی از درون ویرایشگر خط، در صورت نیاز، نصب می‌شود. قالب آن مطابق با مستندات دستور توکار `zle -F' در zshzle(1) است.

این تابع هنگام فعال بودن، پارامتر TCP_HANDLER_ACTIVE را برابر 1 قرار می‌دهد. این امر به کدهای شل که به صورت درونی فراخوانی می‌شوند (برای مثال، با تنظیم tcp_on_read) اجازه می‌دهد تا تشخیص دهند آیا در زمانی که شل در اعلان ویرایشگر بی‌کار (idle) است فراخوانی شده‌اند یا خیر.

این تابع هم برای ثبت گزارش و هم برای مدیریت خروجی به خروجی استاندارد، از درون tcp_read و (در صورتی که $TCP_OUTPUT تنظیم شده باشد) tcp_send استفاده می‌شود.

اعلان (prompt) مورد استفاده توسط -P مشخص می‌شود؛ مقدار پیش‌فرض یک رشتهٔ خالی است. این اعلان می‌تواند شامل موارد زیر باشد:

%c
اگر نشست جاری باشد، به 1 و در غیر این صورت به 0 بسط می‌یابد. با عبارات سه‌تایی مانند `%(c.-.+)' استفاده می‌شود تا برای نشست جاری خروجی `+' و در غیر این صورت `-' تولید کند.
%f
با توصیف‌گر فایل نشست جایگزین می‌شود.
%s
با نام نشست جایگزین می‌شود.
%%
با یک نویسهٔ `%' جایگزین می‌شود.

گزینهٔ -q از ارسال خروجی به خروجی استاندارد جلوگیری می‌کند، اما بر فایل‌های گزارش پیکربندی‌شده تأثیری ندارد.

گزینه‌های -S و -F برای ارسال نام نشست و توصیف‌گر فایل جهت جایگزینی احتمالی در اعلان استفاده می‌شوند.

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

همچنین اغلب مفید است که پارامترهای قابل تنظیم را برای یک تابع محلی (local) کنید. برای مثال، `local TCP_SILENT=1' مشخص می‌کند داده‌هایی که در طول فراخوانی تابع خوانده می‌شوند، بدون توجه به تنظیمات خارج از تابع، در خروجی استاندارد چاپ نخواهند شد. به همین ترتیب، `local TCP_SESS=sess' نشستی را برای مدت زمان اجرای یک تابع تنظیم می‌کند، و `local TCP_PROMPT=' مشخص می‌کند که در طول تابع هیچ اعلانی برای ورودی استفاده نشود.

tcp_expect_lines
آرایه. مجموعه خطوط خوانده‌شده در طول آخرین فراخوانی tcp_expect، شامل آخرین خط ($TCP_LINE).
آرایه. می‌تواند مستقیماً تنظیم شود. مجموعه‌ای از الگوهای انطباق گسترده (extended globbing) که در صورت مطابقت در tcp_output، مانع چاپ خط در خروجی استاندارد می‌شوند. الگوها باید همان‌گونه که برای آرگومان‌های tcp_expect شرح داده شده تعریف شوند. خروجی خطوط به فایل‌های گزارش تحت تأثیر قرار نمی‌گیرد.
اسکالر. درون tcp_fd_handler برابر 1 قرار می‌گیرد تا به توابعی که به‌صورت بازگشتی فراخوانی شده‌اند نشان دهد در طول یک نشست ویرایشگر فراخوانی شده‌اند. در غیر این صورت تنظیم‌نشده (unset) است.
آخرین خط خوانده‌شده توسط tcp_read و در نتیجه توسط tcp_expect.
توصیف‌گر فایلی که $TCP_LINE از آن خوانده شده است. عبارت ${tcp_by_fd[$TCP_LINE_FD]} نام نشست مربوطه را به دست می‌دهد.
آرایه. مجموعه خطوط خوانده‌شده در طول آخرین فراخوانی tcp_read، شامل آخرین خط ($TCP_LINE).
می‌تواند مستقیماً تنظیم شود، اگرچه توسط tcp_log نیز کنترل می‌شود. نام فایلی که خروجی همهٔ نشست‌ها به آن ارسال خواهد شد. خروجی با $TCP_PROMPT معمول آغاز می‌شود. اگر یک نام مسیر مطلق نباشد، نسبت به دایرکتوری جاری کاربر در نظر گرفته می‌شود.
می‌تواند مستقیماً تنظیم شود، هرچند توسط tcp_log نیز کنترل می‌شود. پیشوندی برای مجموعه‌ای از فایل‌ها که خروجی هر نشست به‌طور جداگانه به آن‌ها ارسال خواهد شد؛ نام کامل فایل به صورت ${TCP_LOG_SESS}.sess است. خروجی در هر فایل خام است؛ هیچ اعلانی اضافه نمی‌شود. اگر نام مسیر مطلق نباشد، نسبت به دایرکتوری جاری کاربر در نظر گرفته می‌شود.
آرایه. می‌تواند مستقیماً تنظیم شود. برای نحوهٔ استفاده از آن، به tcp_spam مراجعه کنید.
می‌تواند مستقیماً تنظیم شود. اگر رشته‌ای غیرخالی باشد، هر داده‌ای که توسط tcp_send به یک نشست ارسال شود ثبت خواهد شد. این پارامتر اعلانی را مشخص می‌کند که باید در فایل تعیین‌شده توسط $TCP_LOG استفاده شود، اما در فایلی که از $TCP_LOG_SESS تولید می‌شود اعمال نمی‌گردد. رشتهٔ اعلان دارای قالبی مشابه TCP_PROMPT است و قوانین یکسانی برای استفاده از آن صدق می‌کند.
می‌تواند مستقیماً تنظیم شود. به‌عنوان پیشوندی برای داده‌های خوانده‌شده توسط tcp_read استفاده می‌شود که در خروجی استاندارد یا در فایل گزارش مشخص‌شده توسط $TCP_LOG (در صورت وجود) چاپ می‌شوند. هر `%s'، `%f' یا `%%' در این رشته، به ترتیب با نام نشست، توصیف‌گر فایل زیربنایی نشست، یا یک `%' تنها جایگزین خواهد شد. عبارت `%c' اگر نشستی که خوانده می‌شود نشست جاری باشد به 1 و در غیر این صورت به 0 بسط می‌یابد؛ این ویژگی بیشترین کاربرد را در عبارات سه‌تایی مانند `%(c.-.+)' دارد که اگر نشست جاری باشد `+' و در غیر این صورت `-' را خروجی می‌دهد.

اگر اعلان با %P شروع شود، این پیشوند حذف شده و نتیجهٔ کامل مرحلهٔ قبل، پیش از خروجی داده شدن، از قالب‌بندی استاندارد اعلان به سبک % عبور داده می‌شود.

می‌تواند مستقیماً تنظیم شود. اگر طولی غیرصفر داشته باشد، tcp_read اطلاعات تشخیصی محدودی دربارهٔ داده‌های در حال خواندن ارائه می‌دهد.
این مقدار توسط tcp_open ایجاد شده و با صفر مقداردهی اولیه می‌شود.

توابع tcp_read و tcp_expect از پارامتر SECONDS شل برای مقاصد زمان‌بندی خود استفاده می‌کنند. اگر این پارامتر در زمان ورود به یکی از توابع از نوع ممیز شناور نباشد، یک پارامتر محلی SECONDS از نوع ممیز شناور ایجاد کرده و پارامتر TCP_SECONDS_START را با مقدار قبلی $SECONDS تنظیم می‌کند. اگر این پارامتر از پیش از نوع ممیز شناور باشد، بدون ایجاد رونوشت محلی استفاده می‌شود و TCP_SECONDS_START تنظیم نمی‌گردد. از آنجا که مقدار سراسری صفر است، زمان سپری‌شده در شل تضمین می‌شود که مجموع $SECONDS و $TCP_SECONDS_START باشد.

با تنظیم سراسری SECONDS به یک مقدار ممیز شناور با استفاده از `typeset -F SECONDS' می‌توان از این امر جلوگیری کرد؛ در این حالت توابع TCP هرگز رونوشت محلی نخواهند ساخت و هرگز TCP_SECONDS_START را به یک مقدار غیرصفر تنظیم نخواهند کرد.

می‌تواند مستقیماً تنظیم شود. نشست جاری؛ باید به یکی از نشست‌های برقرارشده توسط tcp_open اشاره کند.
می‌تواند مستقیماً تنظیم شود، هرچند توسط tcp_log نیز کنترل می‌شود. اگر طولی غیرصفر داشته باشد، داده‌های خوانده‌شده توسط tcp_read در خروجی استاندارد نوشته نخواهند شد، اگرچه ممکن است همچنان در فایل گزارش نوشته شوند.
آرایه. می‌تواند مستقیماً تنظیم شود. برای نحوهٔ استفاده از آن، به توضیحات تابع tcp_spam مراجعه کنید.
می‌تواند مستقیماً تنظیم شود. برای نحوهٔ استفاده از آن، به توضیحات تابع tcp_talk مراجعه کنید.
می‌تواند مستقیماً تنظیم شود. در حال حاضر این پارامتر فقط توسط تابع tcp_command استفاده می‌شود؛ به موارد بالا مراجعه کنید..PP

پارامترهای زیر توسط سیستم توابع تنظیم نمی‌شوند، اما در صورت تنظیم توسط کاربر، اثر ویژه‌ای خواهند داشت.

tcp_on_read
این پارامتر باید یک آرایه انجمنی باشد؛ در غیر این صورت، رفتار برنامه تعریف‌نشده است. هر کلید، نام یک تابع شل یا دستوری دیگر است، و مقدار متناظر آن یک الگوی شل است (با استفاده از EXTENDED_GLOB). هر خطی که به طور مستقیم یا غیرمستقیم با استفاده از tcp_read از یک نشست TCP خوانده شود (شامل خطوط خوانده‌شده با tcp_expect) با این الگو مقایسه می‌شود. اگر خط با الگو مطابقت داشته باشد، دستور مشخص‌شده در کلید با دو آرگومان فراخوانی می‌شود: نام نشستی که خط از آن خوانده شده، و خودِ خط.

اگر هر تابعی که برای رسیدگی به یک خط فراخوانی شده است وضعیتی غیرصفر بازگرداند، آن خط در خروجی نمایش داده نمی‌شود. بنابراین، یک گردانندهٔ tcp_on_read که تنها شامل دستور `return 1' باشد می‌تواند برای جلوگیری از نمایش خطوطی خاص به کار رود (با این حال، tcp_filter در بالا را ببینید). با این همه، خط همچنان در TCP_LINE و tcp_lines ذخیره می‌شود؛ این عمل پس از تمام پردازش‌های tcp_on_read رخ می‌دهد.

این پارامترها توسط سیستم توابع کنترل می‌شوند؛ آن‌ها را می‌توان مستقیماً خواند، اما معمولاً نباید توسط کد کاربر مقداردهی شوند.

tcp_aliases
آرایه انجمنی. کلیدها نام نشست‌های برقرارشده با tcp_open هستند؛ هر مقدار فهرستی از نام‌های مستعار جداشده با فاصله است که به آن نشست اشاره دارند.
آرایه انجمنی. کلیدها توصیف‌گرهای فایل نشست هستند؛ هر مقدار نام آن نشست است.
آرایه انجمنی. کلیدها نام نشست‌ها هستند؛ هر مقدار توصیف‌گر فایل مرتبط با آن نشست است.

در اینجا یک مثال ساده با استفاده از یک ماشین‌حساب از راه دور آورده شده است.

برای ایجاد یک سرور ماشین‌حساب روی درگاه 7337 (صفحه راهنمای dc را ببینید تا دریابید دستور زیرین چقدر کلافه‌کننده است):

tcp_proxy 7337 dc

برای اتصال به آن از همان میزبان با نشستی که نام آن نیز `dc' است:

tcp_open localhost 7337 dc

برای ارسال یک دستور به نشست از راه دور و اندکی انتظار برای دریافت خروجی (با فرض اینکه dc نشست جاری باشد):

tcp_command 2 4 + p

برای بستن نشست:

tcp_close

برای متوقف کردن tcp_proxy باید به آن سیگنال خاتمه (kill) فرستاده شود. توجه داشته باشید که این کار معمولاً هیچ‌یک از اتصال‌هایی را که از قبل پذیرفته شده‌اند قطع نمی‌کند، و همچنین درگاه فوراً برای استفادهٔ مجدد در دسترس نخواهد بود.

قطعه کد زیر فهرستی از نشست‌ها را در سرآیند xterm قرار می‌دهد، به طوری که در انتهای نام نشست جاری یک ستاره قرار می‌گیرد.

print -n "\033]2;TCP:" ${(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\*} "\a"

تابع tcp_read از فرمان توکار معمول read در پوسته استفاده می‌کند. از آنجا که این فرمان یک خط کامل را به‌یک‌باره می‌خواند، رسیدن داده‌ها بدون خط جدید (newline) پایانی می‌تواند باعث شود این تابع به‌طور نامحدود مسدود گردد.

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

July 12, 2026 zsh 5.9.2