نام (NAME)

mandoc.db — پایگاه‌داده کلیدواژه‌های صفحات راهنما در mandoc

توضیحات (DESCRIPTION)

قالب فایل mandoc.db برای ذخیره اطلاعات درباره صفحات راهنمای نصب‌شده جهت تسهیل جستجوی معنایی در راهنماها استفاده می‌شود. هر درخت از صفحات راهنما شامل فایل mandoc.db مختص به خود است؛ برای مشاهده مثال‌ها بخش فایل‌ها (FILES) را ببینید.

چنین فایل‌های پایگاه‌داده‌ای توسط makewhatis(8) تولید شده و توسط man(1), apropos(1) و whatis(1) استفاده می‌شوند.

قالب این فایل از سه نوع داده استفاده می‌کند:

• اعداد صحیح علامت‌دار ۳۲ بیتی با ترتیب بایت بزرگ‌پایان (شبکه‌ای / big endian)
• رشته‌های پایان‌یافته با NUL
• فهرست‌هایی از رشته‌های پایان‌یافته با NUL که با یک نویسه دوم NUL خاتمه می‌یابند

اعداد در مرزهای چهار بایتی تراز می‌شوند؛ در جاهایی که پس از رشته‌ها یا فهرست‌هایی از رشته‌ها قرار می‌گیرند، فاصله‌گذاری (padding) با نویسه‌های اضافی NUL انجام می‌شود. برخی از اعداد، اما نه همه آن‌ها، به موقعیت‌هایی درون فایل اشاره می‌کنند. این اشاره‌گرها بر حسب بایت اندازه‌گیری می‌شوند و نخستین بایت فایل به عنوان بایت ۰ در نظر گرفته می‌شود.

هر فایل شامل موارد زیر است:

• یک عدد جادویی (magic number)، 0x3a7d0cdb.
• یک شماره نسخه، در حال حاضر ۱.
• یک اشاره‌گر به جدول ماکروها.
• یک اشاره‌گر به عدد جادویی پایانی.
• جدول صفحات (طول متغیر).
• جدول ماکروها (طول متغیر).
• مجدداً عدد جادویی، 0x3a7d0cdb.

جدول صفحات شامل یک مدخل برای هر فایل فیزیکی صفحه راهنما است، صرف‌نظر از این که چه تعداد پیوند سخت یا نرم در سیستم‌فایل داشته باشد. جدول صفحات شامل موارد زیر است:

• تعداد صفحات موجود در پایگاه‌داده.
• برای هر صفحه:
  • یک اشاره‌گر به فهرست نام‌ها.
  • یک اشاره‌گر به فهرست بخش‌ها.
  • یک اشاره‌گر به فهرست معماری‌ها، یا ۰ در صورتی که صفحه مستقل از ماشین (معماری) باشد.
  • یک اشاره‌گر به رشته توصیف یک‌خطی.
  • یک اشاره‌گر به فهرست نام‌فایل‌ها.
• برای هر صفحه، فهرست نام‌ها. پیش از هر نام یک تک‌بایت قرار دارد که نشان‌دهنده منابع آن نام است. مفهوم بیت‌ها به شرح زیر است:
  • 0x10: نام در یک نام‌فایل ظاهر شده است.
  • 0x08: نام در یک خط هدر آمده است، یعنی در ماکروی .Dt یا .TH.
  • 0x04: نام، نخستین مورد در خط عنوان است، یعنی در نخستین ماکروی .Nm در بخش NAME ظاهر شده است.
  • 0x02: نام در هر ماکروی .Nm در بخش NAME ظاهر شده است.
  • 0x01: نام در یک بلوک .Nm در بخش SYNOPSIS ظاهر شده است.
• برای هر صفحه، فهرست بخش‌ها. هر بخش به صورت یک رشته داده می‌شود، نه یک عدد.
• برای هر صفحه وابسته به معماری، فهرست معماری‌ها.
• برای هر صفحه، رشته توصیف یک‌خطی برگرفته از ماکروی .Nd.
• برای هر صفحه، فهرست نام‌فایل‌ها به صورت نسبی نسبت به ریشه مسیر manpath مربوطه. این فهرست شامل پیوندهای سخت، پیوندهای نرم و پیوندهای شبیه‌سازی‌شده با درخواست‌های .so در roff(7) است. پیش از نخستین نام‌فایل، یک تک‌بایت با مفهوم زیر قرار دارد:
  • FORM_SRC = 0x01: فرمت فایل mdoc(7) یا man(7) است.
  • FORM_CAT = 0x02: صفحه راهنما از پیش فرمت‌بندی شده است.
• صفر تا سه بایت NUL برای فاصله‌گذاری (padding).

جدول ماکروها شامل موارد زیر است:

• تعداد کلیدهای ماکروی متفاوت، در حال حاضر ۳۶ عدد. ترتیب ماکروها در <mansearch.h> تعریف شده و مفهوم کلیدهای ماکرو در apropos(1) مستند شده است.
• برای هر کلید ماکرو، یک اشاره‌گر به جدول ماکروی مربوطه.
• برای هر کلید ماکرو، جدول ماکرو (طول متغیر).

هر جدول ماکرو شامل موارد زیر است:

• تعداد مدخل‌ها در جدول.
• برای هر مدخل:
  • یک اشاره‌گر به مقدار کلید ماکرو. هر مقدار، رشته‌ای از متن است که از فراخوانی یک ماکرو برگرفته شده است.
  • یک اشاره‌گر به فهرست صفحات.
• برای هر مدخل، مقدار کلید ماکرو.
• صفر تا سه بایت NUL برای فاصله‌گذاری (padding).
• برای هر مدخل، یک یا چند اشاره‌گر به صفحات در جدول صفحات، که به اشاره‌گر فهرست نام‌ها اشاره دارند و پس از آن‌ها عدد ۰ قرار می‌گیرد.

فایل‌ها (FILES)

/usr/share/man/mandoc.db

پایگاه‌داده صفحات راهنما برای سیستم پایه.

/usr/X11R6/man/mandoc.db

همان مورد برای سامانه پنجره X(7).

/usr/local/man/mandoc.db

همان مورد برای packages(7).

برنامه‌ای برای استخراج اطلاعات فایل‌های mandoc.db در قالبی خوانا برای انسان که برای diff(1) مناسب باشد، در دایرکتوری /usr/src/regress/usr.bin/mandoc/db/dbm_dump/ فراهم شده است.

همچنین ببینید (SEE ALSO)

apropos(1), man(1), whatis(1), makewhatis(8)

تاریخچه (HISTORY)

پایگاه‌داده صفحات راهنما /usr/lib/whatis نخستین بار در 2BSD پدیدار شد. قالب کنونی نخستین بار در OpenBSD 6.1 ظاهر شد.

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

نسخه اولیه makewhatis(8) در سال ۱۹۷۹ توسط Bill Joy نوشته شد. قالب کنونی پایگاه‌داده در سال ۲۰۱۶ توسط Ingo Schwarze <schwarze@openbsd.org> طراحی شد.