.\" -*- nroff -*-
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright © 2010 Jirka Hladky
.\" Copyright © 2010-2024 Inria.  All rights reserved.
.\" See COPYING in top-level directory.
.TH HWLOC-GATHER-TOPOLOGY "1" "Jun 08, 2026" "2.14.0" "hwloc"
.SH "نام (NAME)"
hwloc-gather-topology \- ذخیره فایل‌های توپولوژی مرتبط با لینوکس و x86 و خروجی‌های متنی و XML دستور lstopo برای استفاده‌های بعدی (احتمالاً آفلاین)
.
.\" **************************
.\"    Synopsis Section
.\" **************************
.SH "خلاصه دستور (SYNOPSIS)"
.
.B hwloc-gather-topology [\fIoptions\fR] \fI<path>\fR
.
.\" **************************
.\"    Options Section
.\" **************************
.SH "گزینه‌ها (OPTIONS)"
.
.TP
\fB\-\-io\fR
همچنین فایل‌های مرتبط با I/O را جمع‌آوری می‌کند.
فرآیند جمع‌آوری ممکن است بسیار کندتر باشد و آرشیو ایجادشده حجم بسیار بیشتری داشته باشد.
.
.TP
\fB\-\-dmi\fR
همچنین فایل‌های مرتبط با DMI/SMBIOS را جمع‌آوری می‌کند.
این جمع‌آوری نیازمند دسترسی ریشه (root) است و ماژول هسته dmi-sysfs باید بارگذاری شده باشد.
.
.TP
\fB\-\-dt\fR
همچنین فایل‌های پردازنده Device-Tree را جمع‌آوری می‌کند. این فایل‌ها برای hwloc ضروری نیستند،
اما می‌توان از آن‌ها برای اشکال‌زدایی آنچه لینوکس در /sys ارائه می‌دهد استفاده کرد.
.
.TP
\fB\-\-no\-cpuid\fR
از جمع‌آوری تخلیه (dump) مربوط به CPUID در x86 با استفاده از \fIhwloc\-gather\-cpuid\fR صرف‌نظر می‌کند.
.
.TP
\fB\-\-keep\fR
نگه‌داری رونوشت موقت فایل‌های تخلیه‌شده به‌جای حذف آن‌ها.
.
.TP
\fB\-\-version\fR
نمایش نسخه و خروج.
.
.TP
\fB\-h\fR \fB\-\-help\fR
نمایش پیام راهنما و خروج.
.
.\" **************************
.\"    Description Section
.\" **************************
.SH "توضیحات (DESCRIPTION)"
.
\fBhwloc-gather-topology\fR تمام فایل‌های مرتبط با توپولوژی را در یک آرشیو
(\fB<path>.tar.bz2\fR)، خروجی lstopo را در (\fB<path>.output\fR)
و خروجی XML ابزار lstopo را در (\fB<path>.xml\fR) ذخیره می‌کند.
این ابزار به‌عنوان مثال فایل \fB/proc/cpuinfo\fR و کل درخت
دایرکتوری \fB/sys/devices/system/node/\fR را ذخیره می‌کند.
.
.PP
از این فایل‌ها می‌توان بعداً برای بررسی آفلاین توپولوژی ماشین استفاده کرد.
پس از استخراج آرشیو tar، می‌توان آن را برای مثال از طریق گزینه \fB\-\-input\fR به برخی از ابزارهای خط فرمان hwloc داد.
همچنین می‌توان با تنظیم مسیر استخراج‌شده در متغیر محیطی \fBHWLOC_FSROOT\fR،
توپولوژی پیش‌فرضی را که کتابخانه hwloc می‌خواند بازنویسی کرد.
.
.PP
آرشیو و خروجی‌های متنی و XML ابزار lstopo را می‌توان برای توسعه‌دهندگان hwloc نیز ارسال کرد
تا مشکلات را از راه دور عیب‌یابی و اشکال‌زدایی کنند.
.
.PP
\fBhwloc-gather-topology\fR ابزاری مختص لینوکس است و روی سایر سیستم‌عامل‌ها
نصب نمی‌شود.
.
.PP
.B نکته:
\fBhwloc-gather-topology\fR جزئیات سخت‌افزاری متعددی را در مورد پلتفرم جمع‌آوری می‌کند.
خروجی‌ها و فایل فشرده tar نباید در لیست‌ها یا وب‌سایت‌های عمومی منتشر شوند،
مگر اینکه مشخص باشد حاوی هیچ اطلاعات حساسی نیستند.
.
.PP
.B نکته:
فرآیند جمع‌آوری ممکن است چندین دقیقه زمان ببرد، به‌ویژه در گره‌های بزرگ.
.
.PP
.B نکته:
اکیداً توصیه می‌شود پیش از مطالعه این صفحه راهنما،
صفحه مرور کلی hwloc(7) را مطالعه فرمایید.
.
.\" **************************
.\"    Examples Section
.\" **************************
.SH "مثال‌ها (EXAMPLES)"
.PP
برای ذخیره اطلاعات توپولوژی جهت استفاده‌های بعدی (احتمالاً روی
یک میزبان دیگر)، دستور زیر را اجرا کنید:

    $ hwloc-gather-topology /tmp/myhost

این دستور تمامی فایل‌های توپولوژی مرتبط را در آرشیو \fB/tmp/myhost.tar.bz2\fR،
خروجی lstopo را در فایل \fB/tmp/myhost.output\fR
و خروجی XML ابزار lstopo را در فایل \fB/tmp/myhost.xml\fR ذخیره می‌کند.
.
این فایل‌ها را می‌توان برای تحلیل‌های بعدی یا آفلاین
و یا به‌عنوان ورودی ابزارهای مختلف hwloc به میزبانی دیگر انتقال داد.
.PP
برای استفاده از این داده‌ها در ابزارهای hwloc، ابتدا باید
آرشیو \fBmyhost.tar.bz2\fR را استخراج کنید:

    $ tar jxvf /tmp/myhost.tar.bz2

اکنون دایرکتوری جدیدی با نام \fBmyhost\fR شامل تمامی فایل‌های توپولوژی خواهد بود.
سپس با ارسال \fB\-\-input myhost\fR، از ابزارهای گوناگون hwloc می‌خواهید که به‌جای
توپولوژی ماشین واقعی از این توپولوژی استفاده کنند.
برای نمایش توپولوژی کافی است این دستور را اجرا کنید:

     $ lstopo --input ./myhost

نیازی نیست توپولوژی حتماً در دایرکتوری جاری استخراج شده باشد؛
مسیرهای مطلق یا نسبی نیز پشتیبانی می‌شوند:

     $ lstopo --input /path/to/remote/host/extracted/topology/

برای مشاهده اینکه hwloc چگونه ۸ وظیفه موازی را روی میزبان اصلی توزیع می‌کند:

     $ hwloc-distrib --input myhost --single 8

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

     $ hwloc-calc --input myhost --po --li -I pu $(hwloc-distrib --input myhost --single 8)

هر برنامه‌ای می‌تواند توپولوژی پیش‌فرض را با یک توپولوژی بایگانی‌شده جایگزین کند،
حتی اگر گزینه \fB\-\-input\fR را نداشته باشد.
برای انجام این کار باید از متغیر محیطی \fBHWLOC_FSROOT\fR استفاده شود:

     $ HWLOC_FSROOT=myhost hwloc-calc --po --li -I pu $(hwloc-distrib --single 8)

تمامی این دستورها همان خروجی‌ای را تولید خواهند کرد که گویی مستقیماً
روی میزبانی اجرا شده‌اند که اطلاعات توپولوژی در ابتدا توسط
اسکریپت \fBhwloc-gather-topology\fR از آن جمع‌آوری شده بود.
.
.\" **************************
.\"    Return value section
.\" **************************
.SH "وضعیت خروج (EXIT STATUS)"
در صورت اجرای موفقیت‌آمیز، \fBhwloc-gather-topology\fR با کد خروج 0 خارج خواهد شد.
.
.PP
در صورت بروز هرگونه خطا، مانند (اما نه محدود به) ناتوانی در ایجاد آرشیو یا فایل‌های خروجی،
\fBhwloc-gather-topology\fR یک وضعیت خروج غیرصفر بازمی‌گرداند.
.
.\" **************************
.\"    See also section
.\" **************************
.SH "همچنین ببینید (SEE ALSO)"
.
.ft R
hwloc(7), lstopo(1), hwloc-gather-cpuid(1), hwloc-calc(1), hwloc-distrib(1)
.sp