دستور فیلتر (filter command)

یک دستور فیلتر یا یک دستور erase است یا یک ساختار حلقه (loop construct). هر دستور erase و ساختار حلقه باید در یک خط جدید آغاز شود. هر دستور فیلتر داده‌هایی از دامپ را که باید پاک شوند توصیف می‌کند. ساختار نحوی:

<EraseCommands>|<LoopConstruct>

که در آن:

<EraseCommands>

در زیربخش دستور erase (erase command) از این صفحه راهنما شرح داده شده است.

<LoopConstruct>

در زیربخش ساختار حلقه (Loop construct) از این صفحه راهنما شرح داده شده است.

دستور erase (erase command)

اندازه مشخصی از داده‌های هسته را که توسط نماد هسته/ماژول یا مؤلفه عضو آن ارجاع داده شده است، پاک می‌کند. ساختار نحوی دستور erase عبارت است از:

erase <Symbol>[.member[...]] [size <SizeValue>[K|M]]
erase <Symbol>[.member[...]] [size <SizeSymbol>]
erase <Symbol>[.member[...]] [nullify]

که در آن:

<Symbol>

نام یک نماد هسته یا ماژول (متغیر) که بخشی از نمادهای سراسری /proc/kallsyms است.

<SizeValue>

یک مقدار عدد صحیح و مثبت به عنوان اندازه داده بر حسب بایت برای پاک‌سازی. پسوندهای 'K' و 'M' را می‌توان به ترتیب برای مشخص کردن کیلوبایت و مگابایت استفاده کرد، که در آن K به معنای ۱۰۲۴ بایت و M به معنای 1024 ^ 2 = 1048576 بایت است. این پسوندها به بزرگی و کوچکی حروف حساس نیستند.

<SizeSymbol>

یک عبارت ساده به شکل <Symbol>[.member[...]] که نشان‌دهنده نمادی است که حاوی یک مقدار عدد صحیح مثبت به عنوان اندازه داده بر حسب بایت برای پاک‌سازی می‌باشد.

<Symbol>[.member[...]]

یک عبارت ساده که به نام یک نماد سراسری هسته یا مؤلفه‌های عضو آن ختم می‌شود. این عبارت صرف‌نظر از این‌که از نوع اشاره‌گر باشد یا خیر، همواره از عملگر '.' برای مشخص کردن مؤلفه member نماد هسته یا عضو آن استفاده می‌کند.

member[...]

عضو یا مؤلفه‌ای از عضو در <Symbol>.

دستور erase دو آرگومان می‌گیرد: ۱. نام نماد هسته یا مؤلفه‌های عضو آن و ۲. اندازه داده‌های ارجاع‌شده توسط آرگومان (۱) یا کلمه کلیدی nullify. آرگومان دوم size یا nullify اختیاری است. واحد مقدار اندازه بر حسب بایت (bytes) است. اگر گزینه size مشخص نشده باشد، اندازه آرگومان اول بر اساس نوع داده آن با استفاده از اطلاعات dwarf موجود در پرونده debuginfo تعیین می‌شود. در مورد نوع داده 'char *'، طول رشته‌ای که اشاره‌گر 'char *' به آن اشاره می‌کند با حد بالای ۱۰۲۴ تعیین می‌شود. مقدار size را می‌توان به دو صورت تعیین کرد: ۱. یک مقدار عددی صحیح همان‌طور که در بالا توضیح داده شد (<SizeValue>) و ۲. یک عبارت ساده به شکل <Symbol>[.member[...]]] که به یک متغیر از نوع پایه (عدد صحیح) منتهی می‌شود.

اگر <Symbol> مشخص‌شده از نوع 'void *' باشد، کاربر باید گزینه size یا nullify را مشخص کند، در غیر این صورت دستور erase هیچ اثری نخواهد داشت.

گزینه nullify تنها زمانی کار می‌کند که <Symbol> مشخص‌شده یک اشاره‌گر باشد. گزینه nullify به جای پاک کردن داده‌هایی که توسط اشاره‌گر مشخص‌شده به آن‌ها اشاره می‌شود، مقدار اشاره‌گر را پاک کرده و آن را برابر '0' (NULL) قرار می‌دهد. لطفاً توجه داشته باشید که تهی کردن (nullify) مقادیر اشاره‌گر ممکن است بر قابلیت اشکال‌زدایی DUMPFILE ایجادشده تأثیر بگذارد. از گزینه nullify تنها زمانی استفاده کنید که اندازه داده‌هایی که باید پاک شوند مشخص نباشد؛ مانند داده‌هایی که توسط 'void *' به آن‌ها اشاره می‌شود.

بیایید به پرونده makedumpfile.conf در مثال زیر نگاهی بیندازیم که برای پاک‌سازی داده‌های مورد نظر هسته از ماژول هسته‌ای با نام mymodule پیکربندی شده است. در خطوط ۱ و ۳، کاربر گزینه size را هنگام پاک‌سازی نمادهای 'array_var' و 'mystruct1.name' مشخص نکرده است. در عوض، کاربر به makedumpfile متکی است تا به‌طور خودکار اندازه‌های مورد نیاز برای پاک‌سازی را تعیین کند؛ یعنی ۱۰۰ بایت برای 'array_var' و ۱۱ بایت برای 'mystruct1.name'. در خط ۲، هنگام پاک‌سازی عضو 'mystruct1.buffer'، کاربر مقدار اندازه ۲۵ را در برابر اندازه واقعی ۵۰ مشخص کرده است. در این حالت، size مشخص‌شده توسط کاربر اولویت دارد و makedumpfile تنها ۲۵ بایت از 'mystruct1.buffer' را پاک می‌کند. در خط ۴، اندازه داده‌هایی که اشاره‌گر void * با نام 'mystruct1.addr' به آن‌ها اشاره می‌کند ناشناخته است؛ بنابراین گزینه nullify برای بازنشانی مقدار اشاره‌گر به NULL مشخص شده است. در خط ۵، 'mystruct2.addr_size' به عنوان آرگومان size برای تعیین اندازه داده‌هایی که توسط اشاره‌گر void * با نام 'mystruct2.addr' به آن‌ها اشاره می‌شود، مشخص شده است.

مثال:

با فرض این‌که قطعه کد زیر مربوط به ماژول هسته 'mymodule' باشد:

struct s1 {
char *name;
void *addr1;
void *addr2;
char buffer[50];
};
struct s2 {
void *addr;
long addr_size;
};

/* Global symbols */
char array_var[100];
struct s1 mystruct1;
struct s2 *mystruct2;

int foo()
{
...
s1.name = "Hello World";
...
}

makedumpfile.conf:
[mymodule]
erase array_var
erase mystruct1.buffer size 25
erase mystruct1.name
erase mystruct1.addr1 nullify
# Assuming addr2 points to 1024 bytes
erase mystruct1.addr2 size 1K
erase mystruct2.addr size mystruct2.addr_size
EOF

ساختار حلقه (Loop construct)

ساختار حلقه به کاربر امکان می‌دهد تا عناصر لیست پیوندی یا آرایه را پیمایش کرده و محتوای داده‌های ارجاع‌شده توسط هر عنصر را پاک کند.

for <id> in {<ArrayVar> |
<StructVar> via <NextMember> |
<ListHeadVar> within <StructName>:<ListHeadMember>}
erase <id>[.MemberExpression] [size <SizeExpression>|nullify]
[erase <id>...]
[...]
endfor

که در آن:

<id>

نام دلخواهی که برای اشاره موقت به عناصر لیست استفاده می‌شود. این متغیر، متغیر تکرار (iteration variable) نیز نامیده می‌شود.

<ArrayVar>

یک عبارت ساده به شکل <Symbol>[.member[...]] که به یک متغیر آرایه‌ای ختم می‌شود.

<StructVar>

یک عبارت ساده به شکل <Symbol>[.member[...]] که به متغیری اشاره‌کننده به یک ساختار ختم می‌شود.

<NextMember>

عضوی در درون <StructVar> که به شیئی از همان نوع <StructVar> اشاره می‌کند.

<ListHeadVar>

یک عبارت ساده به شکل <Symbol>[.member[...]] که به متغیری از نوع struct list_head ختم می‌شود.

<StructName>

نام نوع ساختاری که می‌تواند با استفاده از متغیر HEAD با نام <ListHeadVar> پیمایش شود و حاوی عضوی به نام <ListHeadMember> است.

<ListHeadMember>

نام عضوی در <StructName> از نوع struct list_head.

<MemberExpression>

یک عبارت ساده به شکل [.member[...]] برای مشخص کردن یک عضو یا مؤلفه‌ای از یک عنصر در <ArrayVar>، <StructVar> یا <StructName>.

<SizeExpression>

مقدار اندازه به شکل <SizeValue>، <id>[.MemberExpression] یا <Symbol>[.member[...]].

ساختار حلقه for امکان پیمایش روی فهرستی از عناصر در یک آرایه یا لیست‌های پیوندی را فراهم می‌کند. هر عنصر در لیست به متغیر تکرار <id> نسبت داده می‌شود. نوع متغیر تکرار بر اساس نوع عناصر لیست تعیین می‌شود. ورودی مشخص‌شده پس از پایانه 'in'، ورودی LIST نامیده می‌شود. ورودی LIST می‌تواند یک متغیر آرایه، متغیر/اشاره‌گر ساختار، یا متغیری از نوع struct list_head باشد. مجموعه دستورهای erase مشخص‌شده بین for و endfor برای هر عنصر در ورودی LIST اجرا خواهند شد.

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

اگر ورودی LIST مشخص‌شده یک متغیر/اشاره‌گر ساختار باشد، باید یک عضو پیمایش (<NextMember>) با استفاده از پایانه 'via' مشخص شود. حلقه for تا زمانی که مقدار عضو پیمایش برابر NULL شود یا در صورت وجود لیست پیوندی حلقوی با آدرس گره اول <StructVar> مطابقت پیدا کند، ادامه خواهد یافت.

اگر ورودی LIST با استفاده از متغیری از نوع struct list_head مشخص شده باشد، باید از پایانه within برای مشخص کردن نام ساختار <StructName> دربرگیرنده آن به همراه عضو از نوع struct list_head پس از ':' که بخشی از لیست پیوندی است، استفاده شود. در دستور erase، شناسه <id> ساختاری را نشان می‌دهد که list_head در آن قرار دارد (ELEMENT_OF).

مثال زیر نحوه استفاده از ساختار حلقه را برای پیمایش آرایه، لیست پیوندی از طریق عضو next، و list_head نشان می‌دهد.

مثال:

با فرض این‌که قطعه کد زیر مربوط به ماژول هسته 'mymodule' باشد:

struct s1 {
struct *next;
struct list_head list;
char private[100];
void *key;
long key_size;
};

/* Global symbols */
struct s1 mystruct1;
static LIST_HEAD(s1_list_head);
struct s1 myarray[100];

void foo()
{
struct s1 *s1_ptr;
...
...
s1_ptr = malloc(...);
...
...
list_add(&s1_ptr->list, &s1_list_head);
...
}

makedumpfile.conf:
[mymodule]
# erase private fields from list starting with mystruct1 connected via
# 'next' member:
for mys1 in mystruct1 via next
erase mys1.private
erase mys1.key size mys1.key_size
endfor

# erase private fields from list starting with list_head variable
# s1_list_head.
for mys1 in s1_list_head.next within s1:list
erase mys1.private
erase mys1.key size mys1.key_size
endfor

# erase private fields from all elements of the array myarray:
for mys1 in myarray
erase mys1.private
erase mys1.key size mys1.key_size
endfor
EOF

در مثال بالا، اولین ساختار for لیست پیوندی را از طریق یک متغیر ساختار مشخص mystruct1 از نوع struct s1 پیمایش می‌کند. لیست پیوندی را می‌توان با استفاده از عضو 'next' از mystruct1 پیمایش کرد؛ بنابراین از پایانه via برای مشخص کردن نام عضو پیمایش 'next' استفاده شده است.

دومین ساختار for لیست پیوندی را از طریق متغیر struct list_head مشخص‌شده s1_list_head.next پیمایش می‌کند. نماد سراسری s1_list_head آدرس شروع لیست پیوندی است و عضو next آن به آدرس عضو از نوع struct list_head به نام 'list' از struct s1 اشاره می‌کند. بنابراین از پایانه within برای مشخص کردن نام ساختار 's1' که با استفاده از متغیر s1_list_head.next قابل پیمایش است به همراه نام عضو از نوع struct list_head به نام 'list' که بخشی از لیست پیوندی آغازشونده از نماد سراسری s1_list_head است، استفاده شده است.

سومین ساختار for عناصر آرایه مشخص‌شده از طریق متغیر آرایه‌ای myarray را پیمایش می‌کند.