'\"! tbl | nroff \-man
'\" t macro stdmacro

.de SAMPLE
.br
.RS 0
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..

.TH DEBUGINFOD-FIND 1
.SH "نام (NAME)"
debuginfod-find \- درخواست و دریافت فایلهای اشکالزدایی و کد منبع از سرورهای debuginfod

.SH "خلاصه دستور (SYNOPSIS)"
.B debuginfod-find [\fIOPTION\fP]... debuginfo \fIBUILDID\fP
.br
.B debuginfod-find [\fIOPTION\fP]... debuginfo \fIPATH\fP
.br
.B debuginfod-find [\fIOPTION\fP]... executable \fIBUILDID\fP
.br
.B debuginfod-find [\fIOPTION\fP]... executable \fIPATH\fP
.br
.B debuginfod-find [\fIOPTION\fP]... source \fIBUILDID\fP \fI/FILENAME\fP
.br
.B debuginfod-find [\fIOPTION\fP]... source \fIPATH\fP \fI/FILENAME\fP
.br
.B debuginfod-find [\fIOPTION\fP]... metadata \fIKEY\fP \fIVALUE\fP

.SH "توضیحات (DESCRIPTION)"
دستور
\fBdebuginfod-find\fP
یک یا چند سرور
\fBdebuginfod\fP
را برای داده‌های مرتبط با اشکال‌زدایی (debuginfo) استعلام می‌کند. در صورت یافتن تطابق، پرونده درخواست‌شده را در یک حافظه موقت محلی (کَش) ذخیره کرده، نام پرونده را در خروجی استاندارد چاپ می‌کند و با وضعیت موفقیت 0 خارج می‌شود. در صورت بروز هرگونه خطا، با وضعیت شکست و صدور یک پیام خطا در خروجی خطای استاندارد پایان می‌یابد.

.\" بخش عمده‌ای از متن زیر با debuginfod.8 مشترک است

سامانه debuginfod از شناسه‌های ساخت (buildid) برای شناسایی داده‌های مرتبط با اشکال‌زدایی استفاده می‌کند. این شناسه‌ها به صورت یادداشت‌های باینری (binary notes) در پرونده‌های ELF/DWARF ذخیره شده و به صورت هگزادسیمال با حروف کوچک نشان داده می‌شوند. برای نمونه، برای برنامه
/bin/ls،
به یادداشت ELF با نام GNU_BUILD_ID نگاه کنید:

.SAMPLE
% readelf -n /bin/ls | grep -A4 build.id
Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340:
Owner          Data size  Type
GNU                   20  GNU_BUILD_ID
Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d
.ESAMPLE

سپس BUILDID در مبنای شانزده به سادگی برابر است با:

.SAMPLE
8713b9c3fb8a720137a4a08b325905c7aaf8429d
.ESAMPLE

به جای مقدار هگزادسیمال
\fIBUILDID\fP،
دستور debuginfod-find یک نام مسیر
(\fIPATH\fP)
به باینری ELF را نیز می‌پذیرد و شناسه ساخت را از آن استخراج می‌کند. این جایگزین در صورتی فعال می‌شود که نام پرونده دارای نویسه‌ای غیر از
\fB[0-9a-f]\fP
باشد. پرونده‌هایی با نام مبهم مانند
"\fBdeadbeef\fP"
را می‌توان با یک جزء مسیر اضافی مانند
\fB./deadbeef\fP
ارسال کرد.


.SS debuginfo \fIBUILDID\fP

اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری منجر می‌شود که شامل بخش‌های معمول
\fB.*debug_*\fP
است. این پرونده ممکن است یک پرونده debuginfo تفکیک‌شده باشد که توسط
\fBstrip\fP
ایجاد شده است، یا یک پرونده اجرایی اصلی بدون پیراستگی (unstripped).

.SS executable \fIBUILDID\fP

اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری حاوی بخش‌های اجرایی معمول منتج می‌شود. این پرونده می‌تواند یک فایل اجرایی پیراسته‌شده توسط
\fBstrip\fP
یا یک فایل اجرایی اصلی پیراسته‌نشده باشد. کتابخانه‌های اشتراکی
\fBET_DYN\fP
نوعی فایل اجرایی در نظر گرفته می‌شوند.

.SS source \fIBUILDID\fP \fI/SOURCE/FILE\fP

اگر buildid ارائه‌شده برای سرور شناخته‌شده باشد، این درخواست به یک شیء باینری منجر می‌شود که شامل پرونده منبع ذکرشده است. مسیر باید مطلق باشد. نام‌های مسیر نسبی معمولاً در دایرکتوری منبع پرونده DWARF دیده می‌شوند، اما این مسیرها نسبت به مسیرهای AT_comp_dir مربوط به هر واحد کامپایل منفرد (CU) سنجیده می‌شوند، در حالی که یک پرونده اجرایی از چندین CU تشکیل شده است. بنابراین، برای رفع ابهام، debuginfod انتظار دارد در پرس‌وجوهای فایل منبع، نام‌های مسیر نسبی دارای پیشوند دایرکتوری کامپایل CU باشند که به دنبال آن یک "/" اجباری آمده باشد.

نکته: برای نرم‌افزارهایی که توسط توزیع‌ها بسته‌بندی شده‌اند، دایرکتوری کامپایل CU ممکن است آشکار نباشد. این مسیر را می‌توان با بررسی مقادیر AT_comp_dir در debuginfo دانلودشده پیدا کرد. برای مثال، comp_dir نسخه فدورا ۳۷ برنامه /bin/ls را می‌توان به صورت زیر یافت:

.SAMPLE
% debuginfod-find debuginfo /bin/ls
~/.cache/debuginfod_client/03529d48345409576cd5c82a56ad08555088d353/
% eu-readelf -w ~/.cache/debuginfod_client/03529d48345409576cd5c82a56ad08555088d353/debuginfo | grep comp_dir
           comp_dir             (line_strp) "/usr/src/debug/coreutils-9.1-6.fc37.x86_64/separate"
.ESAMPLE

نکته: فراخواننده ممکن است اجزای مسیر نظیر
\fB../\fP
یا
\fB/./\fP
یا اسلش‌های اضافی
\fB///\fP
را در نام دایرکتوری‌ها حذف کند یا نکند. سامانه debuginfod هر دو حالت را می‌پذیرد. به طور مشخص، debuginfod نام‌های مسیر را مطابق با RFC3986 بخش 5.2.4 (حذف بخش‌های نقطه‌دار) متعارف‌سازی کرده و علاوه بر آن هرگونه
\fB//\fP
را در مسیر به
\fB/\fP
تبدیل می‌کند.

برای مثال:
.TS
l l.
#include <stdio.h>	source BUILDID /usr/include/stdio.h
/path/to/foo.c	source BUILDID /path/to/foo.c
\../bar/foo.c AT_comp_dir=/zoo/	source BUILDID /zoo//../bar/foo.c
.TE

.SS section \fIBUILDID\fP \fISECTION-NAME\fP

اگر buildid داده‌شده برای سرور شناخته‌شده باشد، این درخواست به یک پرونده باینری حاوی محتوای خام بخش (section) منجر می‌شود، چه در یک فایل اجرایی یافت شود و چه در یک پرونده debuginfo جداگانه.


.SS metadata \fIKEY\fP \fIVALUE\fP

تمام سرورهای تعیین‌شده debuginfod برای متاداده‌های مربوط به همه پرونده‌هایی که با پرس‌وجوی کلید/مقدار داده‌شده در نمایه آن‌ها مطابقت دارند، استعلام می‌شوند. نتایج شامل نام‌ها و buildidها است که می‌توان در پرس‌وجوهای آینده برای دریافت فایل‌های واقعی استفاده کرد.

.TS
l l l .
KEY	VALUE	DESCRIPTION

\fBfile\fP	\fIpath\fP	تطابق دقیق با \fIpath\fP، از جمله درون آرشیوها
\fBglob\fP	\fIpattern\fP	تطابق الگوی سراسری شل با \fIpattern\fP، از جمله درون آرشیوها، همانند fnmatch(FNM_PATHNAME)
\fBbuildid\fP	\fIhex\fP	تمام پرونده‌های اجرایی و اشکال‌زدایی منطبق با buildid داده‌شده
.TE

خروجی حاصل شبیه به موارد زیر خواهد بود:
.SAMPLE
{
  "results":[
    {
      "type":"executable",
      "buildid":"f0aa15b8aba4f3c28cac3c2a73801fefa644a9f2",
      "file":"/usr/local/bin/hello",
      "archive":"/opt/elfutils/tests/test-2290642/R/rhel7/hello2-1.0-2.x86_64.rpm"
    },
    {
      "type":"executable",
      "buildid":"bc1febfd03ca05e030f0d205f7659db29f8a4b30",
      "file":"hello2"
    }
  ],
  "complete":true
}
.ESAMPLE

نتایج جستجو در
\fBstdout\fP
به صورت یک شیء JSON حاوی آرایه‌ای از اشیاء چاپ می‌شود که متاداده‌های مربوط به هر تطابق و همچنین یک مقدار بولی متناظر با کامل بودن نتیجه را ارائه می‌دهد. نتیجه در صورتی کامل تلقی می‌شود که تمامی پرس‌وجوها از سرورهای بالادستی نتایج کامل بازگردانده باشند و پرس‌وجوی محلی نیز موفقیت‌آمیز بوده باشد. این گزارش متاداده ممکن است کَش شود. این گزارش ممکن است ناقص باشد یا حاوی موارد تکراری باشد. همچنین فیلدهای شیء JSON اضافی نیز ممکن است وجود داشته باشند.

.TS
l l l .
NAME	TYPE	DESCRIPTION

\fBbuildid\fP	string	شناسه ساخت (buildid) هگزادسیمال مرتبط با پرونده
\fBtype\fP	string	یکی از موارد \fBdebuginfo\fP یا \fBexecutable\fP
\fBfile\fP	string	نام پرونده منطبق‌شده، بیرون یا درون آرشیو
\fBarchive\fP	string	آرشیو حاوی نام پرونده منطبق‌شده، در صورت وجود
.TE

شایان ذکر است که
\fBtype\fP
نمی‌تواند
\fBsource\fP
باشد، زیرا برای انجام چنین جستجویی با سرعت کافی، نیاز به افزودن نمایه‌سازی‌های اضافی به پایگاه‌داده خواهد بود که حجم آن را تقریباً دو برابر می‌کند.
.PP
همچنین این جستجو همیشه فایل‌ها و آرشیوها را در نتایج ترکیب می‌کند و در حال حاضر تفکیک دقیق‌تر در دسترس نیست.

.SH "گزینهها (OPTIONS)"

.TP
.B "\-v" "\-\-verbose"
افزایش پرگویی (جزئیات خروجی)، از جمله چاپ مکرر پیام‌های پیشرفت دانلود و چاپ هدرهای پاسخ http از سرور.

.TP
.B "\-\-help" "\-\-usage"
چاپ پیام راهنما و خروج.

.SH "امنیت (SECURITY)"

اگر امضا(های) IMA از RPMهای حاوی پرونده‌های درخواستی موجود باشند، در این صورت
.BR debuginfod
آن امضاها را در هدرهای پاسخ استخراج می‌کند و
.BR debuginfod-find
اعتبارسنجی را روی پرونده‌ها انجام خواهد داد. سیاست اعتبارسنجی از طریق تگ‌های درج‌شده درون
$DEBUGINFOD_URLS
کنترل می‌شود. به صورت پیش‌فرض،
.BR debuginfod-find
در حالت چشم‌پوشی (ignore mode) عمل می‌کند.
.PP
اگر به جای HTTPS از طریق HTTP دسترسی برقرار شود، شبکه باید قابل‌اعتماد باشد. اطلاعات احراز هویت از طریق کتابخانه داخلی
\fIlibcurl\fP
در حال حاضر فعال نیست، به جز سبک ساده و متن‌باز
\%\fIhttp[s]://userid:password@hostname\fP.
(سرور debuginfod احراز هویت را انجام نمی‌دهد، اما یک سرور پراکسی فرانت‌اند می‌تواند این کار را انجام دهد.)

.nr zZ 1
.so man7/debuginfod-client-config.7

.SH "همچنین ببینید (SEE ALSO)"
.I "debuginfod(8)"
.I "debuginfod_find_debuginfod(3)"