.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.56.0 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "virt-ls 1"
.TH virt-ls 1 2026-07-11 guestfs-tools-1.56.0 "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "نام (NAME)"
virt\-ls \- فهرست کردن فایل‌ها در یک ماشین مجازی
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
.Vb 1
\& virt\-ls [\-\-options] \-d domname directory [directory ...]
\&
\& virt\-ls [\-\-options] \-a disk.img [\-a disk.img ...] directory [directory ...]
.Ve
.PP
شیوه قدیمی:
.PP
.Vb 1
\& virt\-ls [\-\-options] domname directory
\&
\& virt\-ls [\-\-options] disk.img [disk.img ...] directory
.Ve.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`virt\-ls\*(C'\fR نام فایل‌ها، اندازه فایل‌ها، مجموع‌های کنترلی (checksums)، ویژگی‌های گسترش‌یافته (extended attributes) و موارد دیگر را از یک ماشین مجازی یا ایمیج دیسک فهرست می‌کند.
.PP
می‌توان چندین نام دایرکتوری را مشخص کرد که در این حالت خروجی هر یک به یکدیگر متصل می‌شود.
.PP
برای فهرست کردن دایرکتوری‌ها از یک مهمان libvirt از گزینه \fI\-d\fR برای تعیین نام مهمان استفاده کنید. برای یک ایمیج دیسک، از گزینه \fI\-a\fR استفاده کنید.
.PP
\&\f(CW\*(C`virt\-ls\*(C'\fR می‌تواند بسیاری از فهرست‌بندی‌های ساده فایل را انجام دهد. برای موارد پیچیده‌تر ممکن است نیاز باشد از \fBguestfish\fR\|(1) استفاده کنید یا مستقیماً برنامه‌ای برای API \fBguestfs\fR\|(3) بنویسید.
.SH "مثال‌ها (EXAMPLES)"
.IX Header "EXAMPLES"
دریافت فهرستی از تمام فایل‌ها و دایرکتوری‌ها در یک ماشین مجازی:
.PP
.Vb 1
\& virt\-ls \-R \-d guest /
.Ve
.PP
فهرست کردن تمام برنامه‌های دارای مجوز setuid یا setgid در یک ماشین مجازی لینوکس:
.PP
.Vb 1
\& virt\-ls \-lR \-d guest / | grep \*(Aq^\- [42]\*(Aq
.Ve
.PP
فهرست کردن تمام دایرکتوری‌های قابل نوشتن همگانی (public\-writable) در یک ماشین مجازی لینوکس:
.PP
.Vb 1
\& virt\-ls \-lR \-d guest / | grep \*(Aq^d ...7\*(Aq
.Ve
.PP
فهرست کردن تمام سوکت‌های دامنه یونیکس (Unix domain sockets) در یک ماشین مجازی لینوکس:
.PP
.Vb 1
\& virt\-ls \-lR \-d guest / | grep \*(Aq^s\*(Aq
.Ve
.PP
فهرست کردن تمام فایل‌های عادی که نام آن‌ها به ‘.png’ ختم می‌شود:
.PP
.Vb 1
\& virt\-ls \-lR \-d guest / | grep \-i \*(Aq^\-.*\e.png$\*(Aq
.Ve
.PP
برای نمایش فایل‌های بزرگ‌تر از 10MB در دایرکتوری‌های home:
.PP
.Vb 1
\& virt\-ls \-lR \-d guest /home | awk \*(Aq$3 > 10*1024*1024\*(Aq
.Ve
.PP
یافتن هر آنچه در 7 روز گذشته تغییر یافته است:
.PP
.Vb 1
\& virt\-ls \-lR \-d guest \-\-time\-days / | awk \*(Aq$6 <= 7\*(Aq
.Ve
.PP
یافتن فایل‌های عادی تغییریافته در 24 ساعت گذشته:
.PP
.Vb 1
\& virt\-ls \-lR \-d guest \-\-time\-days / | grep \*(Aq^\-\*(Aq | awk \*(Aq$6 < 1\*(Aq
.Ve
.SS "تفاوت‌ها در اسنپ‌شات‌ها و فایل‌های پشتیبان (DIFFERENCES IN SNAPSHOTS AND BACKING FILES)"
.IX Subsection "DIFFERENCES IN SNAPSHOTS AND BACKING FILES"
اگرچه می‌توان از virt\-ls برای بررسی تفاوت‌ها استفاده کرد، اما از نسخه libguestfs ≥ 1.26 ابزار جدیدی به نام \fBvirt\-diff\fR\|(1) در دسترس است.
.SH "حالت‌های خروجی (OUTPUT MODES)"
.IX Header "OUTPUT MODES"
\&\f(CW\*(C`virt\-ls\*(C'\fR دارای چهار حالت خروجی است که با ترکیب‌های مختلف گزینه‌های \fI\-l\fR و \fI\-R\fR کنترل می‌شوند.
.SS "فهرست‌بندی ساده (SIMPLE LISTING)"
.IX Subsection "SIMPLE LISTING"
یک فهرست‌بندی ساده شبیه دستور معمول \fBls\fR\|(1) است:
.PP
.Vb 4
\& $ virt\-ls \-d guest /
\& bin
\& boot
\& [etc.]
.Ve.SS "فهرست‌بندی تفصیلی (LONG LISTING)"
.IX Subsection "LONG LISTING"
با گزینهٔ \fI\-l\fR (\fI\-\-long\fR)، خروجی مشابه دستور \f(CW\*(C`ls \-l\*(C'\fR
خواهد بود (به‌طور دقیق‌تر، مانند تابع \f(CW\*(C`guestfs_ll\*(C'\fR).
.PP
.Vb 5
\& $ virt\-ls \-l \-d guest /
\& total 204
\& dr\-xr\-xr\-x.   2 root root   4096 2009\-08\-25 19:06 bin
\& dr\-xr\-xr\-x.   5 root root   3072 2009\-08\-25 19:06 boot
\& [etc.]
.Ve
.PP
توجه داشته باشید هرچند این قابلیت برای نمایش یک دایرکتوری سودمند است، اما سعی نکنید
این خروجی را در برنامه‌ای دیگر پردازش کنید. در عوض از «فهرست‌بندی تفصیلی بازگشتی (RECURSIVE LONG LISTING)»
استفاده کنید.
.SS "فهرست‌بندی بازگشتی (RECURSIVE LISTING)"
.IX Subsection "RECURSIVE LISTING"
با گزینهٔ \fI\-R\fR (\fI\-\-recursive\fR)، دستور \f(CW\*(C`virt\-ls\*(C'\fR نام‌های
فایل‌ها و دایرکتوری‌ها را به‌صورت بازگشتی فهرست می‌کند:
.PP
.Vb 4
\& $ virt\-ls \-R \-d guest /tmp
\& foo
\& foo/bar
\& [etc.]
.Ve
.PP
برای تولید این خروجی، \f(CW\*(C`virt\-ls\*(C'\fR تابع \f(CW\*(C`guestfs_find0\*(C'\fR را اجرا کرده
و نویسه‌های \f(CW\*(C`\e0\*(C'\fR را به \f(CW\*(C`\en\*(C'\fR تبدیل می‌کند.
.SS "فهرست‌بندی تفصیلی بازگشتی (RECURSIVE LONG LISTING)"
.IX Subsection "RECURSIVE LONG LISTING"
استفادهٔ هم‌زمان از گزینه‌های \fI\-lR\fR خروجی را به‌گونه‌ای تغییر می‌دهد که دایرکتوری‌ها
را به‌طور بازگشتی، همراه با مشخصات آماری فایل‌ها و به‌صورت اختیاری ویژگی‌های
دیگری مانند مجموع مقابله‌ای (checksum) و خصیصه‌های گسترش‌یافته (extended attributes) نمایش دهد.
.PP
بیشتر ویژگی‌های کاربردی \f(CW\*(C`virt\-ls\*(C'\fR تنها هنگام استفاده از حالت
\fI\-lR\fR در دسترس هستند.
.PP
فیلدها معمولاً با فاصله از هم جدا می‌شوند. نام‌فایل‌ها درون گیومه قرار \fBنمی‌گیرند\fR،
بنابراین نمی‌توانید از خروجی در برنامهٔ دیگری استفاده کنید (زیرا نام‌فایل‌ها می‌توانند
حاوی فاصله و دیگر نویسه‌های ناامن باشند). اگر ماشین مهمان غیرقابل‌اعتماد باشد و فردی
بداند که شما از \f(CW\*(C`virt\-ls\*(C'\fR برای تحلیل آن استفاده می‌کنید، می‌تواند با ساختن
نام‌فایل‌هایی حاوی نویسه‌های خط جدید (newline)، شما را فریب دهد. برای پردازش
\fBامن\fR خروجی در برنامه‌ای دیگر، از گزینهٔ \fI\-\-csv\fR (مقادیر جداشده با کاما) استفاده کنید.
.PP
توجه داشته باشید که این قالب خروجی کاملاً با دستور \f(CW\*(C`ls \-lR\*(C'\fR
متفاوت و بی‌ارتباط است.
.PP
.Vb 8
\& $ virt\-ls \-lR \-d guest /bin
\& d 0555       4096 /bin
\& \- 0755        123 /bin/alsaunmute
\& \- 0755      28328 /bin/arch
\& l 0777          4 /bin/awk \-> gawk
\& \- 0755      27216 /bin/basename
\& \- 0755     943360 /bin/bash
\& [etc.]
.Ve
.PP
این فیلدهای اولیه همواره نمایش داده می‌شوند:
.IP type 4
.IX Item "type"
نوع فایل، یکی از موارد زیر:
\&\f(CW\*(C`\-\*(C'\fR (فایل عادی)،
\&\f(CW\*(C`d\*(C'\fR (دایرکتوری)،
\&\f(CW\*(C`c\*(C'\fR (دستگاه نویسه‌ای)،
\&\f(CW\*(C`b\*(C'\fR (دستگاه بلوکی)،
\&\f(CW\*(C`p\*(C'\fR (پایپ نام‌گذاری‌شده)،
\&\f(CW\*(C`l\*(C'\fR (پیوند نمادین)،
\&\f(CW\*(C`s\*(C'\fR (سوکت) یا
\&\f(CW\*(C`u\*(C'\fR (ناشناخته).
.IP permissions 4
.IX Item "permissions"
مجوزهای Unix، که به‌صورت یک عدد ۴ رقمی در مبنای هشت نمایش داده می‌شوند.
.IP size 4
.IX Item "size"
اندازهٔ فایل. این مقدار به بایت نشان داده می‌شود، مگر اینکه گزینهٔ \fI\-h\fR یا
\&\fI\-\-human\-readable\fR مشخص شده باشد که در آن صورت به‌صورت عددی خوانا برای
انسان نمایش داده خواهد شد.
.IP path 4
.IX Item "path"
مسیر کامل فایل یا دایرکتوری.
.IP link 4
.IX Item "link"
تنها برای پیوندهای نمادین، مقصد پیوند.
.PP
در حالت \fI\-lR\fR، گزینه‌های اضافی خط فرمان امکان نمایش فیلدهای بیشتری را فراهم می‌کنند.
.PP
با پرچم \fI\-\-uids\fR، این فیلدهای اضافی پیش از مسیر نمایش داده می‌شوند:
.IP uid 4
.IX Item "uid"
.PD 0
.IP gid 4
.IX Item "gid"
.PD
شناسهٔ UID و GID مالک فایل (به‌صورت عددی نمایش داده می‌شوند).
توجه داشته باشید این مقادیر تنها در بستر یک مهمان شبه‌یونیکس معنادار هستند.
.PP
با پرچم \fI\-\-times\fR، این فیلدهای اضافی نمایش داده می‌شوند:
.IP atime 4
.IX Item "atime"
زمان آخرین دسترسی.
.IP mtime 4
.IX Item "mtime"
زمان آخرین تغییر محتوا.
.IP ctime 4
.IX Item "ctime"
زمان آخرین تغییر وضعیت.
.PP
فیلدهای زمانی به‌صورت تاریخ و ساعت رشته‌ای نمایش داده می‌شوند، مگر اینکه یکی از
پرچم‌های \fI\-\-time\-t\fR، \fI\-\-time\-relative\fR یا \fI\-\-time\-days\fR داده شده باشد.
.PP
با پرچم \fI\-\-extra\-stats\fR، این فیلدهای اضافی نمایش داده می‌شوند:
.IP device 4
.IX Item "device"
دستگاهی که فایل را در بر دارد (به‌صورت major:minor نمایش می‌یابد).
این ممکن است با دستگاه‌هایی که سیستم مهمان می‌شناسد مطابقت نداشته باشد.
.IP inode 4
.IX Item "inode"
شمارهٔ inode.
.IP nlink 4
.IX Item "nlink"
تعداد پیوندهای سخت (hard links).
.IP rdev 4
.IX Item "rdev"
برای فایل‌های ویژهٔ بلوکی و نویسه‌ای، دستگاه
(به‌صورت major:minor نمایش می‌یابد).
.IP blocks 4
.IX Item "blocks"
تعداد بلوک‌های ۵۱۲ بایتی تخصیص‌یافته به فایل.
.PP
با پرچم \fI\-\-checksum\fR، مجموع مقابله‌ای محتویات فایل نمایش داده می‌شود
(تنها برای فایل‌های عادی). محاسبهٔ مجموع مقابله‌ای فایل‌ها می‌تواند
زمان قابل‌توجهی ببرد..SH "گزینه‌ها (OPTIONS)"
.IX Header "OPTIONS"
.IP \fB\-\-help\fR 4
.IX Item "--help"
نمایش راهنمای کوتاه.
.IP "\fB\-a\fR file" 4
.IX Item "-a file"
.PD 0
.IP "\fB\-\-add\fR file" 4
.IX Item "--add file"
.PD
افزودن \fIfile\fR که باید یک تصویر دیسک از یک ماشین مجازی باشد. اگر ماشین مجازی دارای چندین دستگاه بلوکی است، باید همهٔ آن‌ها را با گزینه‌های \fI\-a\fR جداگانه مشخص کنید.
.Sp
قالب تصویر دیسک به‌طور خودکار تشخیص داده می‌شود. برای لغو این رفتار و تحمیل قالبی خاص، از گزینهٔ \fI\-\-format=..\fR استفاده کنید.
.IP "\fB\-a URI\fR" 4
.IX Item "-a URI"
.PD 0
.IP "\fB\-\-add URI\fR" 4
.IX Item "--add URI"
.PD
افزودن یک دیسک دوردست. بخش «ADDING REMOTE STORAGE» را در \fBguestfish\fR\|(1) ببینید.
.IP \fB\-\-blocksize=512\fR 4
.IX Item "--blocksize=512"
.PD 0
.IP \fB\-\-blocksize=4096\fR 4
.IX Item "--blocksize=4096"
.IP \fB\-\-blocksize\fR 4
.IX Item "--blocksize"
.PD
این پارامتر اندازهٔ سکتور تصویر دیسک را تعیین می‌کند. این مقدار بر تمامی دیسک‌های بعدی که پس از این پارامتر به‌طور صریح اضافه می‌شوند، تأثیر می‌گذارد. استفاده از \&\fI\-\-blocksize\fR بدون آرگومان، اندازهٔ سکتور دیسک را به مقدار پیش‌فرض که معمولاً ۵۱۲ بایت است بازمی‌گرداند. همچنین بخش «guestfs_add_drive_opts» را در \fBguestfs\fR\|(3) ببینید.
.IP \fB\-\-checksum\fR 4
.IX Item "--checksum"
.PD 0
.IP \fB\-\-checksum=crc|md5|sha1|sha224|sha256|sha384|sha512\fR 4
.IX Item "--checksum=crc|md5|sha1|sha224|sha256|sha384|sha512"
.PD
نمایش چِک‌سام روی محتویات فایل برای فایل‌های عادی. بدون آرگومان، پیش‌فرض استفاده از \fImd5\fR است. با ارائهٔ یک آرگومان، می‌توانید نوع چک‌سام مورد استفاده را انتخاب کنید.
.Sp
این گزینه تنها در حالت خروجی \fI\-lR\fR اثر دارد. بخش «RECURSIVE LONG LISTING» را در بالا ببینید.
.IP "\fB\-c\fR URI" 4
.IX Item "-c URI"
.PD 0
.IP "\fB\-\-connect\fR URI" 4
.IX Item "--connect URI"
.PD
در صورت استفاده از libvirt، به \fIURI\fR ارائه‌شده متصل می‌شود. در صورت عدم ذکر، اتصال به هایپروایزر پیش‌فرض libvirt برقرار می‌شود.
.Sp
اگر دستگاه‌های بلوکی مهمان را مستقیماً مشخص کنید (\fI\-a\fR)، آن‌گاه libvirt اصلاً استفاده نخواهد شد.
.IP \fB\-\-csv\fR 4
.IX Item "--csv"
نوشتن نتایج در قالب CSV (مقادیر جداشده با کاما). این قالب می‌تواند به‌راحتی در پایگاه‌های داده و صفحات گسترده وارد شود، اما بخش «NOTE ABOUT CSV FORMAT» را در ادامه بخوانید.
.IP "\fB\-d\fR guest" 4
.IX Item "-d guest"
.PD 0
.IP "\fB\-\-domain\fR guest" 4
.IX Item "--domain guest"
.PD
افزودن تمام دیسک‌ها از مهمان libvirt نام‌برده‌شده. می‌توان به‌جای نام‌ها از UUID دامنه استفاده کرد.
.IP \fB\-\-echo\-keys\fR 4
.IX Item "--echo-keys"
هنگام درخواست کلیدها و عبارات عبور، virt\-ls معمولاً بازتاب ورودی را غیرفعال می‌کند تا نتوانید آنچه تایپ می‌کنید را ببینید. اگر نگران حملات Tempest نیستید و کس دیگری در اتاق نیست، می‌توانید این پرچم را تعیین کنید تا آنچه تایپ می‌کنید را ببینید.
.IP \fB\-\-extra\-stats\fR 4
.IX Item "--extra-stats"
نمایش آمارهای اضافی.
.Sp
این گزینه تنها در حالت خروجی \fI\-lR\fR اثر دارد. بخش «RECURSIVE LONG LISTING» را در بالا ببینید.
.IP \fB\-\-format=raw|qcow2|..\fR 4
.IX Item "--format=raw|qcow2|.."
.PD 0
.IP \fB\-\-format\fR 4
.IX Item "--format"
.PD
حالت پیش‌فرض برای گزینهٔ \fI\-a\fR تشخیص خودکار قالب تصویر دیسک است. استفاده از این گزینه، قالب دیسک را برای گزینه‌های \fI\-a\fR که در ادامهٔ خط فرمان می‌آیند تحمیل می‌کند. استفاده از \fI\-\-format\fR بدون آرگومان، تشخیص را برای گزینه‌های بعدی \fI\-a\fR به حالت خودکار بازمی‌گرداند.
.Sp
برای مثال:
.Sp
.Vb 1
\& virt\-ls \-\-format=raw \-a disk.img /dir
.Ve
.Sp
قالب raw (بدون تشخیص خودکار) را برای \fIdisk.img\fR تحمیل می‌کند.
.Sp
.Vb 1
\& virt\-ls \-\-format=raw \-a disk.img \-\-format \-a another.img /dir
.Ve
.Sp
قالب raw (بدون تشخیص خودکار) را برای \fIdisk.img\fR تحمیل کرده و برای \fIanother.img\fR به حالت تشخیص خودکار بازمی‌گردد.
.Sp
اگر تصاویر دیسک مهمانِ غیرقابل‌اعتمادی با قالب raw دارید، باید از این گزینه برای تعیین صریح قالب دیسک استفاده کنید. این کار از یک مشکل امنیتی احتمالی مرتبط با مهمان‌های مخرب جلوگیری می‌کند (CVE\-2010\-3851).
.IP \fB\-h\fR 4
.IX Item "-h"
.PD 0
.IP \fB\-\-human\-readable\fR 4
.IX Item "--human-readable"
.PD
نمایش اندازهٔ فایل‌ها در قالبی خوانا برای انسان.
.Sp
این گزینه تنها در حالت خروجی \fI\-lR\fR اثر دارد. بخش «RECURSIVE LONG LISTING» را در بالا ببینید.
.IP "\fB\-\-key\fR SELECTOR" 4
.IX Item "--key SELECTOR"
تعیین کلید برای LUKS، جهت بازگشایی خودکار دستگاه LUKS هنگام استفاده از بازرسی (inspection).
.RS 4
.IP "\fB\-\-key\fR NAME\fB:key:\fRKEY_STRING" 4
.IX Item "--key NAME:key:KEY_STRING"
.PD 0
.IP "\fB\-\-key\fR UUID\fB:key:\fRKEY_STRING" 4
.IX Item "--key UUID:key:KEY_STRING"
.IP "\fB\-\-key\fR \fBall:key:\fRKEY_STRING" 4
.IX Item "--key all:key:KEY_STRING"
.PD
\&\f(CW\*(C`NAME\*(C'\fR نام دستگاه در libguestfs است (مانند \f(CW\*(C`/dev/sda1\*(C'\fR). عبارت \f(CW\*(C`UUID\*(C'\fR شناسهٔ یکتای دستگاه است. مقدار \f(CW\*(C`all\*(C'\fR به معنای امتحان کردن کلید روی تمامی دستگاه‌های رمزگذاری‌شده است.
.Sp
از \f(CW\*(C`KEY_STRING\*(C'\fR ارائه‌شده به عنوان عبارت عبور استفاده می‌کند.
.IP "\fB\-\-key\fR NAME\fB:file:\fRFILENAME" 4
.IX Item "--key NAME:file:FILENAME"
.PD 0
.IP "\fB\-\-key\fR UUID\fB:file:\fRFILENAME" 4
.IX Item "--key UUID:file:FILENAME"
.IP "\fB\-\-key\fR \fBall:file:\fRFILENAME" 4
.IX Item "--key all:file:FILENAME"
.PD
خواندن عبارت عبور از \fIFILENAME\fR.
.IP "\fB\-\-key\fR NAME\fB:clevis\fR" 4
.IX Item "--key NAME:clevis"
.PD 0
.IP "\fB\-\-key\fR UUID\fB:clevis\fR" 4
.IX Item "--key UUID:clevis"
.IP "\fB\-\-key\fR \fBall:clevis\fR" 4
.IX Item "--key all:clevis"
.PD
تلاش برای قفل‌گشایی بدون عبارت عبور برای دستگاه از طریق شبکه به‌وسیلهٔ Clevis. لطفاً برای اطلاعات بیشتر دربارهٔ رمزگذاری دیسک وابسته به شبکه (NBDE) به بخش «ENCRYPTED DISKS» در \fBguestfs\fR\|(3) مراجعه کنید.
.Sp
توجه داشته باشید که اگر چنین گزینه‌ای در خط فرمان داده شود، شبکهٔ کاربری QEMU به‌طور خودکار برای محیط libguestfs فعال خواهد شد.
.RE
.RS 4
.RE
.IP \fB\-\-keys\-from\-stdin\fR 4
.IX Item "--keys-from-stdin"
خواندن پارامترهای کلید یا عبارت عبور از stdin. حالت پیش‌فرض تلاش برای خواندن عبارت عبور از کاربر با باز کردن \fI/dev/tty\fR است.
.Sp
اگر چندین دستگاه رمزگذاری‌شده وجود دارد، ممکن است لازم باشد چندین کلید را از طریق stdin وارد کنید، هر کدام در یک خط مجزا.
.IP "\fB\-m\fR dev[:mountpoint[:options[:fstype]]]" 4
.IX Item "-m dev[:mountpoint[:options[:fstype]]]"
.PD 0
.IP "\fB\-\-mount\fR dev[:mountpoint[:options[:fstype]]]" 4
.IX Item "--mount dev[:mountpoint[:options[:fstype]]]".PD
پارتیشن یا حجم منطقیِ (logical volume) نام‌برده را روی نقطهٔ اتصال (mountpoint) داده‌شده سوار (mount) می‌کند.
.Sp
اگر نقطهٔ اتصال ذکر نشود، مقدار پیش‌فرض \fI/\fR خواهد بود.
.Sp
مشخص کردن هر نقطهٔ اتصالی، بازرسی ماشین مهمان و سوار کردن ریشهٔ آن و تمام نقاط اتصالش را غیرفعال می‌کند؛ بنابراین اطمینان حاصل کنید که تمام نقاط اتصال لازم برای کار با نام فایل‌های ارائه‌شده به عنوان آرگومان را سوار کرده‌اید.
.Sp
اگر نمی‌دانید یک ایمیج دیسک شامل چه سیستم‌های فایلی است، می‌توانید guestfish را بدون این گزینه اجرا کرده و پارتیشن‌ها، سیستم‌های فایل و LVهای موجود را فهرست کنید (دستورهای "list\-partitions"، "list\-filesystems" و "lvs" را ببینید)، یا از برنامهٔ \&\fBvirt\-filesystems\fR\|(1) استفاده نمایید.
.Sp
بخش سوم (و به‌ندرت استفاده‌شده) از پارامتر mount، فهرستی از گزینه‌های اتصال است که برای سوار کردن سیستم فایل زیربنایی به کار می‌رود. اگر این بخش داده نشود، گزینه‌های اتصال یا یک رشتهٔ خالی و یا \f(CW\*(C`ro\*(C'\fR خواهند بود (دومی در صورتی است که پرچم \fI\-\-ro\fR استفاده شده باشد). با تعیین گزینه‌های اتصال، این انتخاب پیش‌فرض لغو و بازنویسی می‌شود. احتمالاً تنها زمانی از این قابلیت استفاده می‌کنید که بخواهید در صورت پشتیبانی سیستم فایل، ACLها و/یا صفت‌های گسترش‌یافته (extended attributes) را فعال کنید:
.Sp
.Vb 1
\& \-m /dev/sda1:/:acl,user_xattr
.Ve
.Sp
استفاده از این پرچم معادل استفاده از دستور \f(CW\*(C`mount\-options\*(C'\fR است.
.Sp
بخش چهارم پارامتر، درایور سیستم فایل مورد استفاده مانند \f(CW\*(C`ext3\*(C'\fR یا \f(CW\*(C`ntfs\*(C'\fR است. این بخش به‌ندرت نیاز می‌شود، اما در صورتی که چندین درایور برای یک سیستم فایل معتبر باشند (برای نمونه: \f(CW\*(C`ext2\*(C'\fR و \f(CW\*(C`ext3\*(C'\fR)، یا اگر libguestfs نوع سیستم فایل را اشتباه شناسایی کند، می‌تواند مفید باشد.
.IP \fB\-l\fR 4
.IX Item "-l"
.PD 0
.IP \fB\-\-long\fR 4
.IX Item "--long"
.IP \fB\-R\fR 4
.IX Item "-R"
.IP \fB\-\-recursive\fR 4
.IX Item "--recursive"
.PD
انتخاب حالت. بدون هیچ‌یک از این گزینه‌ها، \f(CW\*(C`virt\-ls\*(C'\fR یک فهرست ساده و تخت از فایل‌های موجود در دایرکتوری نام‌برده تولید می‌کند. بخش "SIMPLE LISTING" را ببینید.
.Sp
دستور \&\f(CW\*(C`virt\-ls \-l\*(C'\fR یک «فهرست‌بندی بلند» تولید می‌کند که جزئیات بیشتری را نشان می‌دهد. بخش "LONG LISTING" را ببینید.
.Sp
دستور \&\f(CW\*(C`virt\-ls \-R\*(C'\fR یک فهرست بازگشتی از فایل‌ها را با شروع از دایرکتوری نام‌برده تولید می‌کند. بخش "RECURSIVE LISTING" را ببینید.
.Sp
دستور \&\f(CW\*(C`virt\-ls \-lR\*(C'\fR یک فهرست‌بندی بلندِ بازگشتی تولید می‌کند که تجزیه (parse) کردن آن ساده‌تر است. بخش "RECURSIVE LONG LISTING" را ببینید.
.IP \fB\-\-times\fR 4
.IX Item "--times"
نمایش فیلدهای زمان.
.Sp
این گزینه تنها در حالت خروجی \fI\-lR\fR تأثیر دارد. بخش "RECURSIVE LONG LISTING" در بالا را ببینید.
.IP \fB\-\-time\-days\fR 4
.IX Item "--time-days"
نمایش فیلدهای زمان به صورت روزهای پیش از اکنون (اگر در آینده باشد، منفی است).
.Sp
توجه داشته باشید که \f(CW0\fR در خروجی به معنای «حداکثر ۱ روز پیش از اکنون» است، یا اینکه عمر فایل بین ۰ تا ۸۶۳۹۹ ثانیه است.
.Sp
این گزینه تنها در حالت خروجی \fI\-lR\fR تأثیر دارد. بخش "RECURSIVE LONG LISTING" در بالا را ببینید.
.IP \fB\-\-time\-relative\fR 4
.IX Item "--time-relative"
نمایش فیلدهای زمان به صورت ثانیه‌های پیش از اکنون (اگر در آینده باشد، منفی است).
.Sp
این گزینه تنها در حالت خروجی \fI\-lR\fR تأثیر دارد. بخش "RECURSIVE LONG LISTING" در بالا را ببینید.
.IP \fB\-\-time\-t\fR 4
.IX Item "--time-t"
نمایش فیلدهای زمان به صورت ثانیه‌های سپری‌شده از مبدأ یونیکس (Unix epoch).
.Sp
این گزینه تنها در حالت خروجی \fI\-lR\fR تأثیر دارد. بخش "RECURSIVE LONG LISTING" در بالا را ببینید.
.IP \fB\-\-uids\fR 4
.IX Item "--uids"
نمایش فیلدهای UID و GID.
.Sp
این گزینه تنها در حالت خروجی \fI\-lR\fR تأثیر دارد. بخش "RECURSIVE LONG LISTING" در بالا را ببینید.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.PD
فعال‌سازی پیام‌های پرگو (verbose) برای اشکال‌زدایی.
.IP \fB\-V\fR 4
.IX Item "-V"
.PD 0
.IP \fB\-\-version\fR 4
.IX Item "--version"
.PD
نمایش شمارهٔ نسخه و خروج.
.IP \fB\-x\fR 4
.IX Item "-x"
فعال‌سازی ردگیری (tracing) فراخوانی‌های API مربوط به libguestfs..SH "آرگومان‌های خط فرمان به سبک قدیمی (OLD\-STYLE COMMAND LINE ARGUMENTS)"
.IX Header "OLD-STYLE COMMAND LINE ARGUMENTS"
نسخه‌های پیشین virt\-ls به شما اجازه می‌دادند که بنویسید یا:
.PP
.Vb 1
\& virt\-ls disk.img [disk.img ...] /dir
.Ve
.PP
یا
.PP
.Vb 1
\& virt\-ls guestname /dir
.Ve
.PP
در حالی که در این نسخه باید به ترتیب از \fI\-a\fR یا \fI\-d\fR استفاده کنید
تا از حالت گیج‌کننده‌ای که در آن ممکن است یک تصویر دیسک هم‌نام با
یک ماشین مهمان باشد، جلوگیری شود.
.PP
جهت سازگاری، سبک قدیمی همچنان پشتیبانی می‌شود.
.SH "نکته‌ای درباره قالب CSV (NOTE ABOUT CSV FORMAT)"
.IX Header "NOTE ABOUT CSV FORMAT"
مقادیر جداشده با کاما (CSV) قالبی فریبنده است. \fIبه نظر می‌رسد\fR
که تجزیه آن باید آسان باشد، اما مسلماً تجزیه آن آسان نیست.
.PP
باور غلط: فقط فیلدها را در محل کاماها جدا کنید. واقعیت: این روش به طور
مطمئن کار \fIنمی‌کند\fR. این مثال دارای دو ستون است:
.PP
.Vb 1
\& "foo,bar",baz
.Ve
.PP
باور غلط: فایل را خط به خط بخوانید. واقعیت: این روش به طور مطمئن
کار \fIنمی‌کند\fR. این مثال دارای یک سطر است:
.PP
.Vb 2
\& "foo
\& bar",baz
.Ve
.PP
برای اسکریپت‌های پوسته، از \f(CW\*(C`csvtool\*(C'\fR استفاده کنید (https://github.com/Chris00/ocaml\-csv
که در توزیع‌های اصلی لینوکس نیز بسته‌بندی شده است).
.PP
برای زبان‌های دیگر، از یک کتابخانه پردازش CSV استفاده کنید (مانند \f(CW\*(C`Text::CSV\*(C'\fR
برای Perl یا کتابخانه توکار csv در Python).
.PP
اکثر نرم‌افزارهای صفحه‌گسترده و پایگاه‌های داده می‌توانند CSV را مستقیماً درون‌ریزی کنند.
.SH "وضعیت خروج (EXIT STATUS)"
.IX Header "EXIT STATUS"
این برنامه در صورت موفقیت 0، و در صورت بروز خطا مقداری غیر صفر برمی‌گرداند.
.SH "همچنین ببینید (SEE ALSO)"
.IX Header "SEE ALSO"
\&\fBguestfs\fR\|(3),
\&\fBguestfish\fR\|(1),
\&\fBvirt\-cat\fR\|(1),
\&\fBvirt\-copy\-out\fR\|(1),
\&\fBvirt\-diff\fR\|(1),
\&\fBvirt\-tar\-out\fR\|(1),
http://libguestfs.org.
.SH "نویسندگان (AUTHORS)"
.IX Header "AUTHORS"
Richard W.M. Jones http://people.redhat.com/~rjones
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2025 Red Hat Inc.
.SH "مجوز (LICENSE)"
.IX Header "LICENSE"
این برنامه یک نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط «مجوز عمومی همگانی گنو» (GNU General Public License) همان‌طور که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، بازتوزیع کرده یا تغییر دهید؛ چه نسخه ۲ مجوز یا (به انتخاب خودتان) هر نسخه بعدی آن.
.PP
این برنامه به این امید توزیع شده است که مفید واقع شود، اما بدون هرگونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف خاص. برای جزئیات بیشتر به مجوز عمومی همگانی گنو مراجعه کنید.
.PP
شما باید به همراه این برنامه نسخه‌ای از مجوز عمومی همگانی گنو را دریافت کرده باشید؛ در غیر این صورت، به نشانی زیر مکاتبه کنید:
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110\-1301 USA..SH "گزارش باگ‌ها (BUGS)"
.IX Header "BUGS"
برای دریافت فهرستی از باگ‌های مربوط به libguestfs، از این پیوند استفاده کنید:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
.PP
برای گزارش یک باگ جدید در libguestfs، از این پیوند استفاده کنید:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
هنگام گزارش باگ، لطفاً موارد زیر را ارائه دهید:
.IP \(bu 4
نسخهٔ libguestfs.
.IP \(bu 4
محل دریافت libguestfs (مثلاً از کدام توزیع لینوکس، کامپایل‌شده از کد منبع و غیره).
.IP \(bu 4
باگ را به‌دقت شرح دهید و روشی برای بازتولید آن ارائه دهید.
.IP \(bu 4
دستور \fBlibguestfs\-test\-tool\fR\|(1) را اجرا کرده و خروجی \fBکامل و ویرایش‌نشدهٔ\fR
آن را در گزارش باگ قرار دهید.