.\" Man page generated from reStructuredText .\" by the Docutils 0.23 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "bpftool-map" "8" "" "" .SH "نام (NAME)" bpftool-map \- ابزار بازرسی و دستکاری نگاشت‌های bpf .SH "خلاصه دستور (SYNOPSIS)" .sp \fBbpftool\fP [\fIOPTIONS\fP] \fBmap\fP \fICOMMAND\fP .sp \fIOPTIONS\fP := { { \fB\-j\fP | \fB\-\-json\fP } [{ \fB\-p\fP | \fB\-\-pretty\fP }] | { \fB\-d\fP | \fB\-\-debug\fP } | { \fB\-f\fP | \fB\-\-bpffs\fP } | { \fB\-n\fP | \fB\-\-nomount\fP } } .sp \fICOMMANDS\fP := { \fBshow\fP | \fBlist\fP | \fBcreate\fP | \fBdump\fP | \fBupdate\fP | \fBlookup\fP | \fBgetnext\fP | \fBdelete\fP | \fBpin\fP | \fBhelp\fP } .SH "دستورات نگاشت (MAP COMMANDS)" .nf \fBbpftool\fP \fBmap\fP { \fBshow\fP | \fBlist\fP } [\fIMAP\fP] \fBbpftool\fP \fBmap create\fP \fIFILE\fP \fBtype\fP \fITYPE\fP \fBkey\fP \fIKEY_SIZE\fP \fBvalue\fP \fIVALUE_SIZE\fP .in +2 \fBentries\fP \fIMAX_ENTRIES\fP \fBname\fP \fINAME\fP [\fBflags\fP \fIFLAGS\fP] [\fBinner_map\fP \fIMAP\fP] [\fBoffload_dev\fP \fINAME\fP] .in -2 \fBbpftool\fP \fBmap dump\fP \fIMAP\fP \fBbpftool\fP \fBmap update\fP \fIMAP\fP [\fBkey\fP \fIDATA\fP] [\fBvalue\fP \fIVALUE\fP] [\fIUPDATE_FLAGS\fP] \fBbpftool\fP \fBmap lookup\fP \fIMAP\fP [\fBkey\fP \fIDATA\fP] \fBbpftool\fP \fBmap getnext\fP \fIMAP\fP [\fBkey\fP \fIDATA\fP] \fBbpftool\fP \fBmap delete\fP \fIMAP\fP \fBkey\fP \fIDATA\fP \fBbpftool\fP \fBmap pin\fP \fIMAP\fP \fIFILE\fP \fBbpftool\fP \fBmap event_pipe\fP \fIMAP\fP [\fBcpu\fP \fIN\fP \fBindex\fP \fIM\fP] \fBbpftool\fP \fBmap peek\fP \fIMAP\fP \fBbpftool\fP \fBmap push\fP \fIMAP\fP \fBvalue\fP \fIVALUE\fP \fBbpftool\fP \fBmap pop\fP \fIMAP\fP \fBbpftool\fP \fBmap enqueue\fP \fIMAP\fP \fBvalue\fP \fIVALUE\fP \fBbpftool\fP \fBmap dequeue\fP \fIMAP\fP \fBbpftool\fP \fBmap freeze\fP \fIMAP\fP \fBbpftool\fP \fBmap help\fP \fIMAP\fP := { \fBid\fP \fIMAP_ID\fP | \fBpinned\fP \fIFILE\fP | \fBname\fP \fIMAP_NAME\fP } \fIDATA\fP := { [\fBhex\fP] \fIBYTES\fP } \fIPROG\fP := { \fBid\fP \fIPROG_ID\fP | \fBpinned\fP \fIFILE\fP | \fBtag\fP \fIPROG_TAG\fP | \fBname\fP \fIPROG_NAME\fP } \fIVALUE\fP := { \fIDATA\fP | \fIMAP\fP | \fIPROG\fP } \fIUPDATE_FLAGS\fP := { \fBany\fP | \fBexist\fP | \fBnoexist\fP } \fITYPE\fP := { \fBhash\fP | \fBarray\fP | \fBprog_array\fP | \fBperf_event_array\fP | \fBpercpu_hash\fP .in +2 | \fBpercpu_array\fP | \fBstack_trace\fP | \fBcgroup_array\fP | \fBlru_hash\fP | \fBlru_percpu_hash\fP | \fBlpm_trie\fP | \fBarray_of_maps\fP | \fBhash_of_maps\fP | \fBdevmap\fP | \fBdevmap_hash\fP | \fBsockmap\fP | \fBcpumap\fP | \fBxskmap\fP | \fBsockhash\fP | \fBcgroup_storage\fP | \fBreuseport_sockarray\fP | \fBpercpu_cgroup_storage\fP | \fBqueue\fP | \fBstack\fP | \fBsk_storage\fP | \fBstruct_ops\fP | \fBringbuf\fP | \fBinode_storage\fP | \fBtask_storage\fP | \fBbloom_filter\fP | \fBuser_ringbuf\fP | \fBcgrp_storage\fP | \fBarena\fP | \fBinsn_array\fP | \fBrhash\fP } .in -2 .fi .sp .SH "توضیحات (DESCRIPTION)" .INDENT 0.0 .TP .B bpftool map { show | list } [\fIMAP\fP] نمایش اطلاعات درباره نگاشت‌های بارگذاری‌شده. اگر \fIMAP\fP مشخص شده باشد، اطلاعات فقط برای نگاشت‌های داده‌شده نمایش داده می‌شود، در غیر این صورت تمام نگاشت‌های بارگذاری‌شده فعلی در سیستم فهرست می‌شوند. در صورت استفاده از \fBname\fP، ممکن است \fIMAP\fP با چند نگاشت مطابقت داشته باشد که همگی نمایش داده خواهند شد. .sp خروجی با شناسه نگاشت (ID) آغاز شده و به دنبال آن نوع نگاشت و صفر یا چند صفت نام‌دار (بسته به نسخه هسته) درج می‌شود. .sp از لینوکس ۵.۸ به بعد، bpftool قادر است اطلاعات مربوط به فرآیندهایی را که توصیف‌کننده‌های فایل (FD) باز به نگاشت‌های BPF دارند کشف کند. در چنین هسته‌هایی، bpftool به طور خودکار این اطلاعات را نیز منتشر می‌کند. .TP .B bpftool map create \fIFILE\fP type \fITYPE\fP key \fIKEY_SIZE\fP value \fIVALUE_SIZE\fP entries \fIMAX_ENTRIES\fP name \fINAME\fP [flags \fIFLAGS\fP] [inner_map \fIMAP\fP] [offload_dev \fINAME\fP] ایجاد یک نگاشت جدید با پارامترهای داده‌شده و سنجاق کردن (pin) آن به \fIbpffs\fP با نام \fIFILE\fP\&. .sp مقدار \fIFLAGS\fP باید یک عدد صحیح باشد که ترکیبی از فلگ‌های مورد نظر است، به عنوان مثال ۱۰۲۴ برای \fBBPF_F_MMAPABLE\fP (برای مشاهده فلگ‌های موجود، هدر UAPI با نام bpf.h را بررسی کنید). .sp برای ایجاد نگاشت‌هایی از نوع array\-of\-maps یا hash\-of\-maps، باید از کلمه کلیدی \fBinner_map\fP برای ارسال یک نگاشت درونی استفاده شود. هسته برای جمع‌آوری متادیتای مرتبط با نگاشت‌های درونی که نگاشت جدید با آن‌ها کار خواهد کرد به آن نیاز دارد. .sp کلمه کلیدی \fBoffload_dev\fP انتظار نام یک رابط شبکه را دارد و برای درخواست بارگذاری سخت‌افزاری (hardware offload) برای نگاشت استفاده می‌شود. .TP .B bpftool map dump \fIMAP\fP تخلیه تمام مدخل‌های موجود در یک \fIMAP\fP مشخص. در صورت استفاده از \fBname\fP، ممکن است \fIMAP\fP با چند نگاشت مطابقت داشته باشد که همگی تخلیه خواهند شد. .TP .B bpftool map update \fIMAP\fP [key \fIDATA\fP] [value \fIVALUE\fP] [\fIUPDATE_FLAGS\fP] به‌روزرسانی مدخل نگاشت برای یک \fIKEY\fP مشخص. .sp مقدار \fIUPDATE_FLAGS\fP می‌تواند یکی از این موارد باشد: \fBany\fP به‌روزرسانی مدخل موجود یا افزودن در صورت عدم وجود؛ \fBexist\fP به‌روزرسانی فقط در صورتی که مدخل از قبل وجود داشته باشد؛ \fBnoexist\fP به‌روزرسانی فقط در صورتی که مدخل وجود نداشته باشد. .sp اگر کلمه کلیدی \fBhex\fP قبل از دنباله بایت‌ها مشخص شود، بایت‌ها به عنوان مقادیر هگزادسیمال تحلیل می‌شوند، حتی اگر هیچ پیشوند \(dq0x\(dq اضافه نشده باشد. اگر این کلمه کلیدی مشخص نشود، بایت‌ها به عنوان مقادیر ده‌دهی تحلیل می‌شوند، مگر اینکه پیشوند \(dq0x\(dq (برای هگزادسیمال) یا پیشوند \(dq0\(dq (برای هشت‌هشتی) درج شده باشد. .TP .B bpftool map lookup \fIMAP\fP [key \fIDATA\fP] جستجوی \fBkey\fP در نگاشت. .TP .B bpftool map getnext \fIMAP\fP [key \fIDATA\fP] دریافت کلید بعدی. اگر \fIkey\fP مشخص نشده باشد، نخستین کلید دریافت می‌شود. .TP .B bpftool map delete \fIMAP\fP key \fIDATA\fP حذف مدخل از نگاشت. .TP .B bpftool map pin \fIMAP\fP \fIFILE\fP سنجاق کردن نگاشت \fIMAP\fP به عنوان \fIFILE\fP\&. .sp نکته: \fIFILE\fP باید در محل اتصال \fIbpffs\fP قرار گیرد. نباید شامل نویسه نقطه (\(aq.\(aq) باشد، چرا که برای پسوندهای آینده \fIbpffs\fP رزرو شده است. .TP .B bpftool map event_pipe \fIMAP\fP [cpu \fIN\fP index \fIM\fP] خواندن رویدادها از یک نگاشت \fBBPF_MAP_TYPE_PERF_EVENT_ARRAY\fP\&. .sp نصب حلقه‌های perf در نگاشت آرایه رویداد perf و تخلیه خروجی هر فراخوانی \fBbpf_perf_event_output\fP() در هسته. به طور پیش‌فرض تعداد CPUهای سیستم خوانده شده و برای هر CPU در شاخص مربوطه در آرایه، یک حلقه perf نصب می‌شود. .sp اگر \fBcpu\fP و \fBindex\fP مشخص شوند، حلقه perf برای \fBcpu\fP مشخص در \fBindex\fP داده‌شده در آرایه نصب می‌شود (تک حلقه). .sp توجه داشته باشید که نصب یک حلقه perf در آرایه، بی‌صدا جایگزین هر حلقه موجود خواهد شد. هر برنامه دیگری که قبلاً حلقه‌های خود را نصب کرده باشد دریافت رویدادها را متوقف خواهد کرد. .TP .B bpftool map peek \fIMAP\fP مشاهده مقدار بعدی در صف یا پشته بدون حذف آن. .TP .B bpftool map push \fIMAP\fP value \fIVALUE\fP قرار دادن \fIVALUE\fP در بالای پشته. .TP .B bpftool map pop \fIMAP\fP برداشتن و چاپ مقدار از بالای پشته. .TP .B bpftool map enqueue \fIMAP\fP value \fIVALUE\fP افزودن \fIVALUE\fP به انتهای صف. .TP .B bpftool map dequeue \fIMAP\fP برداشتن و چاپ مقدار از ابتدای صف. .TP .B bpftool map freeze \fIMAP\fP منجمد کردن نگاشت به صورت فقط‌خواندنی از فضای کاربر. مدخل‌های یک نگاشت منجمدشده دیگر نمی‌توانند با فراخوانی سیستمی \fBbpf\fP() به‌روزرسانی یا حذف شوند. این عملیات برگشت‌پذیر نیست و نگاشت تا زمان نابودی‌اش از فضای کاربر تغییرناپذیر باقی می‌ماند. با این حال، مجوزهای خواندن و نوشتن برنامه‌های BPF روی نگاشت دست‌نخورده باقی می‌ماند. .TP .B bpftool map help چاپ پیام راهنمای کوتاه. .UNINDENT .SH "گزینه‌ها (OPTIONS)" .INDENT 0.0 .TP .B \-h\fP,\fB \-\-help چاپ پیام راهنمای کوتاه (مشابه \fBbpftool help\fP). .TP .B \-V\fP,\fB \-\-version چاپ شماره نسخه bpftool (مشابه \fBbpftool version\fP)، شماره نسخه libbpf مورد استفاده و ویژگی‌های اختیاری که هنگام کامپایل bpftool گنجانده شده‌اند. ویژگی‌های اختیاری شامل پیوند به LLVM یا libbfd برای ارائه دیس‌اسمبلر برنامه‌های JIT شده (\fBbpftool prog dump jited\fP) و استفاده از اسکلت‌های BPF (برخی ویژگی‌ها مانند \fBbpftool prog profile\fP یا نمایش pidهای مرتبط با اشیاء BPF ممکن است به آن متکی باشند) است. .TP .B \-j\fP,\fB \-\-json تولید خروجی JSON. برای دستوراتی که نمی‌توانند JSON تولید کنند، این گزینه هیچ تاثیری ندارد. .TP .B \-p\fP,\fB \-\-pretty تولید خروجی JSON خوانا برای انسان. متضمن \fB\-j\fP است. .TP .B \-d\fP,\fB \-\-debug چاپ تمام لاگ‌های موجود، حتی اطلاعات در سطح اشکال‌زدایی (debug). این شامل لاگ‌های libbpf و همچنین وارسی‌کننده (verifier) هنگام تلاش برای بارگذاری برنامه‌ها می‌شود. .UNINDENT .INDENT 0.0 .TP .B \-f\fP,\fB \-\-bpffs نمایش نام فایل‌های نگاشت‌های سنجاق‌شده. .TP .B \-n\fP,\fB \-\-nomount عدم تلاش خودکار برای سوار کردن (mount) هرگونه فایل‌سیستم مجازی (مانند tracefs یا فایل‌سیستم مجازی BPF) در صورت نیاز. .UNINDENT .SH "مثال‌ها (EXAMPLES)" .sp \fB# bpftool map show\fP .INDENT 0.0 .INDENT 3.5 .sp .EX 10: hash name some_map flags 0x0 key 4B value 8B max_entries 2048 memlock 167936B pids systemd(1) .EE .UNINDENT .UNINDENT .sp سه دستور زیر معادل یکدیگرند: .nf \fB# bpftool map update id 10 key hex 20 c4 b7 00 value hex 0f ff ff ab 01 02 03 4c\fP \fB# bpftool map update id 10 key 0x20 0xc4 0xb7 0x00 value 0x0f 0xff 0xff 0xab 0x01 0x02 0x03 0x4c\fP \fB# bpftool map update id 10 key 32 196 183 0 value 15 255 255 171 1 2 3 76\fP .fi .sp .sp \fB# bpftool map lookup id 10 key 0 1 2 3\fP .INDENT 0.0 .INDENT 3.5 .sp .EX key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 .EE .UNINDENT .UNINDENT .sp \fB# bpftool map dump id 10\fP .INDENT 0.0 .INDENT 3.5 .sp .EX key: 00 01 02 03 value: 00 01 02 03 04 05 06 07 key: 0d 00 07 00 value: 02 00 00 00 01 02 03 04 Found 2 elements .EE .UNINDENT .UNINDENT .sp \fB# bpftool map getnext id 10 key 0 1 2 3\fP .INDENT 0.0 .INDENT 3.5 .sp .EX key: 00 01 02 03 next key: 0d 00 07 00 .EE .UNINDENT .UNINDENT .nf \fB# mount \-t bpf none /sys/fs/bpf/\fP \fB# bpftool map pin id 10 /sys/fs/bpf/map\fP \fB# bpftool map del pinned /sys/fs/bpf/map key 13 00 07 00\fP .fi .sp .sp توجه داشته باشید که از به‌روزرسانی نگاشت می‌توان برای تغییر ارجاعات برنامه‌های نگه‌داری‌شده توسط یک نگاشت prog array نیز استفاده کرد. این ویژگی می‌تواند به عنوان مثال برای تغییر برنامه‌های مورد استفاده برای پرش‌های فراخوانی انتهایی (tail\-call) در زمان اجرا، بدون نیاز به بارگذاری مجدد برنامه نقطه ورود (entry\-point) به کار رود. در ادامه مثالی برای این مورد کاربرد آمده است: برنامه‌ای را بارگذاری می‌کنیم که یک نگاشت prog array تعریف می‌کند و دارای یک تابع اصلی شامل یک فراخوانی انتهایی به برنامه‌های دیگر است که می‌توانند برای \(dqprocess\(dq بسته‌ها یا برای \(dqdebug\(dq پردازش به کار روند. توجه داشته باشید که نگاشت prog array حتماً باید در فایل‌سیستم مجازی BPF سنجاق (pin) شود تا به‌روزرسانی نگاشت با موفقیت انجام گیرد، زیرا هنگامی که هیچ ارجاعی از فضای کاربر باقی نماند، هسته نگاشت‌های prog array را پاکسازی می‌کند (و به‌روزرسانی به محض خروج bpftool از دست خواهد رفت). .nf \fB# bpftool prog loadall tail_calls.o /sys/fs/bpf/foo type xdp\fP \fB# bpftool prog \-\-bpffs\fP .fi .sp .INDENT 0.0 .INDENT 3.5 .sp .EX 545: xdp name main_func tag 674b4b5597193dc3 gpl loaded_at 2018\-12\-12T15:02:58+0000 uid 0 xlated 240B jited 257B memlock 4096B map_ids 294 pinned /sys/fs/bpf/foo/xdp 546: xdp name bpf_func_process tag e369a529024751fc gpl loaded_at 2018\-12\-12T15:02:58+0000 uid 0 xlated 200B jited 164B memlock 4096B pinned /sys/fs/bpf/foo/process 547: xdp name bpf_func_debug tag 0b597868bc7f0976 gpl loaded_at 2018\-12\-12T15:02:58+0000 uid 0 xlated 200B jited 164B memlock 4096B pinned /sys/fs/bpf/foo/debug .EE .UNINDENT .UNINDENT .sp \fB# bpftool map\fP .INDENT 0.0 .INDENT 3.5 .sp .EX 294: prog_array name jmp_table flags 0x0 key 4B value 4B max_entries 1 memlock 4096B owner_prog_type xdp owner jited .EE .UNINDENT .UNINDENT .nf \fB# bpftool map pin id 294 /sys/fs/bpf/bar\fP \fB# bpftool map dump pinned /sys/fs/bpf/bar\fP .fi .sp .INDENT 0.0 .INDENT 3.5 .sp .EX Found 0 elements .EE .UNINDENT .UNINDENT .nf \fB# bpftool map update pinned /sys/fs/bpf/bar key 0 0 0 0 value pinned /sys/fs/bpf/foo/debug\fP \fB# bpftool map dump pinned /sys/fs/bpf/bar\fP .fi .sp .INDENT 0.0 .INDENT 3.5 .sp .EX key: 00 00 00 00 value: 22 02 00 00 Found 1 element .EE .UNINDENT .UNINDENT .SH "همچنین ببینید (SEE ALSO)" .sp \fBbpf\fP(2), \fBbpf\-helpers\fP(7), \fBbpftool\fP(8), \fBbpftool\-btf\fP(8), \fBbpftool\-cgroup\fP(8), \fBbpftool\-feature\fP(8), \fBbpftool\-gen\fP(8), \fBbpftool\-iter\fP(8), \fBbpftool\-link\fP(8), \fBbpftool\-net\fP(8), \fBbpftool\-perf\fP(8), \fBbpftool\-prog\fP(8), \fBbpftool\-struct_ops\fP(8), \fBbpftool\-token\fP(8) .\" End of generated man page.