MANDOCD(8) System Manager's Manual MANDOCD(8)

mandocd — سرور فرمت‌بندی صفحات راهنما در سوکت

mandocd [-I os=name] [-T output] socket_fd

ابزار mandocd تعداد زیادی از صفحات راهنما را بدون نیاز به سربار fork(2) و exec(3) در این میان فرمت‌بندی می‌کند. این ابزار نیازی به فهرست کردن همه راهنماهای مورد نظر برای فرمت‌بندی در خط فرمان ندارد و از نوشتن هر راهنمای فرمت‌شده در توصیف‌کننده فایل اختصاصی خود پشتیبانی می‌کند.

این سرور نیاز دارد که یک socket(2) دامنه یونیکس متصل از قبل در زمان exec(3) وجود داشته باشد. در نتیجه، نمی‌توان آن را از خط فرمان sh(1) شروع کرد زیرا پوسته نمی‌تواند چنین سوکتی را فراهم کند. به طور معمول، سوکت توسط فرایند والد با استفاده از socketpair(2) پیش از فراخوانی fork(2) و exec(3) روی mandocd ایجاد می‌شود. فرایند والد شماره توصیف‌کننده فایل را به عنوان یک آرگومان به exec(3) ارسال می‌کند که به صورت یک عدد صحیح ده‌دهی با کدگذاری اسکی فرمت‌بندی شده است. برای یک پیاده‌سازی متداول از فرایند والد، catman(8) را ببینید.

mandocd به صورت حلقه‌ای پیام‌های یک‌بایتی را با recvmsg(2) از شماره توصیف‌کننده فایل socket_fd می‌خواند. بایت خوانده‌شده را نادیده می‌گیرد و فقط از داده‌های کنترلی کمکی خارج از باند struct cmsghdr استفاده می‌کند که معمولاً توسط فرایند فراخواننده با استفاده از CMSG_FIRSTHDR(3) فراهم می‌شود. انتظار می‌رود فرایند والد همراه با هر بایت ساختگی، سه توصیف‌کننده فایل را ارسال کند. اولی برای ورودی mdoc(7) یا man(7) استفاده می‌شود، دومی برای خروجی فرمت‌بندی‌شده، و سومی برای خروجی خطا.

گزینه‌ها به شرح زیر هستند:

os=name
سیستم‌عامل پیش‌فرض name را برای ماکروی Os در mdoc(7) و برای ماکروی TH در man(7) بازنویسی می‌کند.
output
قالب خروجی. آرگومان output می‌تواند ascii ، utf8 یا html باشد؛ mandoc(1) را ببینید. در حالت خروجی html ، گزینه خروجی fragment ضمنی است. سایر گزینه‌های خروجی پشتیبانی نمی‌شوند.

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

هنگامی که یک پیام صفر بایتی خوانده شود، زمانی که socket_fd توسط فرایند والد بسته شود، یا هنگامی که خطایی رخ دهد، mandocd خارج می‌شود.

The mandocd utility exits 0 on success, and >0 if an error occurs.

یک پیام صفر بایتی یا یک socket_fd بسته‌شده به عنوان موفقیت در نظر گرفته می‌شود. خطاهای احتمالی عبارتند از:

  • آرگومان‌های ناموجود، نامعتبر یا بیش از حد برای exec(3)
  • شکست recvmsg(2) ، برای مثال به دلیل EMSGSIZE
  • داده‌های کنترلی ناموجود یا غیرمنتظره، به ویژه یک cmsg_level در struct cmsghdr که با SOL_SOCKET متفاوت باشد، یک cmsg_type که با SCM_RIGHTS متفاوت باشد، یا یک cmsg_len که سه برابر اندازه یک int نباشد
  • توصیف‌کننده‌های فایل نامعتبر ارسال‌شده در CMSG_DATA(3)
  • اتمام منابع، به ویژه شکست dup(2) یا malloc(3)

به جز کمبود حافظه و خرابی‌های مشابه در سطح سیستم، خطاهای تجزیه و فرمت‌بندی باعث نمی‌شوند که mandocd وضعیت خروج خطا بازگرداند. حتی پس از خطاهای شدید تجزیه، mandocd به سادگی توصیف‌کننده فایل ورودی بعدی را پذیرفته و پردازش می‌کند.

mandoc(1), mandoc(3), catman(8)

ابزار mandocd در نسخه 1.14.1 از جعبه‌ابزار ظاهر شد.

طرح مفهومی توسط Michael Stapelberg <stapelberg@debian.org> طراحی و پیاده‌سازی شد. کد رابط mandoc(3) مورد نیاز برای تبدیل آن به یک فرایند مستقل توسط Ingo Schwarze <schwarze@openbsd.org> اضافه شد.

اگر صفحات راهنمای تجزیه‌شده شامل درخواست‌های .so در roff(7) باشند، mandocd باید با دایرکتوری کاری فعلی تنظیم‌شده روی ریشه درخت صفحات راهنما اجرا شود. از اجرای آن در دایرکتوری‌هایی که شامل فایل‌های محرمانه در هر یک از زیردایرکتوری‌ها هستند خودداری کنید، به‌ویژه اگر کاربری که آن را اجرا می‌کند دسترسی خواندن به این فایل‌های محرمانه را داشته باشد.

March 18, 2017 Linux 6.12.107+deb13-amd64