به عنوان پوسته تعاملی (As an interactive shell)

$ guestfish
Welcome to guestfish, the guest filesystem shell for
editing virtual machine filesystems.
Type: 'help' for a list of commands
      'man' to read the manual
      'quit' to quit the shell
><fs> add-ro disk.img
><fs> run
><fs> list-filesystems
/dev/sda1: ext4
/dev/vg_guest/lv_root: ext4
/dev/vg_guest/lv_swap: swap
><fs> mount /dev/vg_guest/lv_root /
><fs> cat /etc/fstab
# /etc/fstab
# Created by anaconda
[...]
><fs> exit

از طریق اسکریپت‌های شل (From shell scripts)

ایجاد یک فایل /etc/motd جدید در یک سیستم مهمان یا ایمیج دیسک:

guestfish <<_EOF_
add disk.img
run
mount /dev/vg_guest/lv_root /
write /etc/motd "Welcome, new users"
_EOF_

فهرست کردن حجم‌های منطقی LVM در یک ایمیج دیسک:

guestfish -a disk.img --ro <<_EOF_
run
lvs
_EOF_

فهرست کردن تمام سیستم‌فایل‌ها در یک ایمیج دیسک:

guestfish -a disk.img --ro <<_EOF_
run
list-filesystems
_EOF_

در یک خط فرمان (On one command line)

به‌روزرسانی /etc/resolv.conf در یک سیستم مهمان:

guestfish \
  add disk.img : run : mount /dev/vg_guest/lv_root / : \
  write /etc/resolv.conf "nameserver 1.2.3.4"

ویرایش تعاملی /boot/grub/grub.conf:

guestfish --rw --add disk.img \
  --mount /dev/vg_guest/lv_root \
  --mount /dev/sda1:/boot \
  edit /boot/grub/grub.conf

مونت خودکار دیسک‌ها (Mount disks automatically)

از گزینه -i برای مونت خودکار دیسک‌های یک ماشین مجازی استفاده کنید:

guestfish --ro -a disk.img -i cat /etc/group
guestfish --ro -d libvirt-domain -i cat /etc/group

یک روش دیگر برای ویرایش تعاملی /boot/grub/grub.conf:

guestfish --rw -a disk.img -i edit /boot/grub/grub.conf

به عنوان مفسر اسکریپت (As a script interpreter)

ایجاد یک دیسک ۱۰۰ مگابایتی شامل یک پارتیشن با قالب‌بندی ext2:

#!/usr/bin/guestfish -f
sparse test1.img 100M
run
part-disk /dev/sda mbr
mkfs ext2 /dev/sda1

شروع با یک دیسک آماده‌شده (Start with a prepared disk)

ایجاد یک دیسک ۱ گیگابایتی به نام test1.img شامل یک پارتیشن با قالب‌بندی ext2:

guestfish -N fs

برای مشاهده موارد موجود اجرا کنید:

guestfish -N help | less

درایوهای راه دور (Remote drives)

دسترسی به دیسک راه دور با استفاده از ssh:

guestfish -a ssh://example.com/path/to/disk.img

کنترل از راه دور (Remote control)

eval "`guestfish --listen`"
guestfish --remote add-ro disk.img
guestfish --remote run
guestfish --remote lvs

توالی‌های گریز در آرگومان‌های با نقل‌قول دوتایی (ESCAPE SEQUENCES IN DOUBLE QUOTED ARGUMENTS)

تنها در آرگومان‌های با نقل‌قول دوتایی، از بک‌اسلش برای درج نویسه‌های ویژه استفاده کنید:

"\a"

نویسه هشدار یا زنگ (Alert/bell).

"\b"

نویسه پس‌بر (Backspace).

"\f"

نویسه فرم‌فید (Form feed).

"\n"

نویسه خط جدید (Newline).

"\r"

نویسه بازگشت به ابتدای سطر (Carriage return).

"\t"

نویسه تب افقی (Horizontal tab).

"\v"

نویسه تب عمودی (Vertical tab).

"\""

یک نویسه نقل‌قول دوتایی واقعی.

"\ooo"

یک نویسه با مقدار هشت‌هشتی (اکتال) ooo. دقیقاً باید ۳ رقم هشت‌هشتی وجود داشته باشد (برخلاف C).

"\xhh"

یک نویسه با مقدار شانزده‌شانزدهی (هگزادسیمال) hh. دقیقاً باید ۲ رقم شانزده‌شانزدهی وجود داشته باشد.

در پیاده‌سازی فعلی، "\000" و "\x00" نمی‌توانند در رشته‌ها استفاده شوند.

"\\"

یک نویسه بک‌اسلش واقعی.

پسوند اندازه (SIZE SUFFIX)

هنگامی که دستور پارامتری با واحد بایت دریافت می‌کند، می‌توانید از یکی از پسوندهای زیر برای تعیین کیلوبایت، مگابایت و اندازه‌های بزرگ‌تر استفاده کنید:

k یا K یا KiB

اندازه بر حسب کیلوبایت (ضرب در ۱۰۲۴).

KB

اندازه در واحدهای استاندارد SI بر حسب ۱۰۰۰ بایت.

M یا MiB

اندازه بر حسب مگابایت (ضرب در ۱۰۴۸۵۷۶).

MB

اندازه در واحدهای استاندارد SI بر حسب ۱۰۰۰۰۰۰ بایت.

G یا GiB

اندازه بر حسب گیگابایت (ضرب در ۲ به توان ۳۰).

GB

اندازه در واحدهای استاندارد SI بر حسب ۱۰ به توان ۹ بایت.

T یا TiB

اندازه بر حسب ترابایت (ضرب در ۲ به توان ۴۰).

TB

اندازه در واحدهای استاندارد SI بر حسب ۱۰ به توان ۱۲ بایت.

P یا PiB

اندازه بر حسب پتابایت (ضرب در ۲ به توان ۵۰).

PB

اندازه در واحدهای استاندارد SI بر حسب ۱۰ به توان ۱۵ بایت.

E یا EiB

اندازه بر حسب اگزابایت (ضرب در ۲ به توان ۶۰).

EB

اندازه در واحدهای استاندارد SI بر حسب ۱۰ به توان ۱۸ بایت.

Z یا ZiB

اندازه بر حسب زتابایت (ضرب در ۲ به توان ۷۰).

ZB

اندازه در واحدهای استاندارد SI بر حسب ۱۰ به توان ۲۱ بایت.

Y یا YiB

اندازه بر حسب یوتابایت (ضرب در ۲ به توان ۸۰).

YB

اندازه در واحدهای استاندارد SI بر حسب ۱۰ به توان ۲۴ بایت.

برای مثال:

truncate-size /file 1G

فایل را به اندازه ۱ گیگابایت کوتاه یا بریده (truncate) می‌کند.

دقت کنید زیرا برخی دستورات اندازه‌ها را بر حسب کیلوبایت یا مگابایت دریافت می‌کنند (برای مثال پارامتر "memsize" از قبل بر حسب مگابایت مشخص شده است). افزودن پسوند احتمالاً کاری را که انتظار دارید انجام نخواهد داد.

اعداد هشت‌هشتی و شانزده‌شانزدهی (OCTAL AND HEXADECIMAL NUMBERS)

برای تعیین مبنا (radix)، از قرارداد زبان C استفاده کنید: پیشوند 0 برای یک عدد هشت‌هشتی (octal) یا پیشوند "0x" برای یک عدد شانزده‌شانزدهی (hexadecimal). برای مثال:

1234      decimal number 1234
02322     octal number, equivalent to decimal 1234
0x4d2     hexadecimal number, equivalent to decimal 1234

هنگام استفاده از دستور "chmod"، تقریباً همیشه می‌خواهید یک عدد هشت‌هشتی را برای حالت (mode) مشخص کنید، و باید پیشوند 0 را قبل از آن قرار دهید (برخلاف برنامه chmod(1) یونیکس):

chmod 0777 /public  # OK
chmod 777 /public   # WRONG! This is mode 777 decimal = 01411 octal.

دستوراتی که اعداد را برمی‌گردانند معمولاً آن‌ها را در مبنای ۱۰ (ده‌دهی) چاپ می‌کنند، اما برخی دستورات اعداد را در مبناهای دیگر چاپ می‌کنند (برای مثال "umask" حالت را در مبنای هشت، همراه با پیشوند 0 چاپ می‌کند).

دستورات محلی با اجرای درون‌خطی (LOCAL COMMANDS WITH INLINE EXECUTION)

اگر خطی با <! شروع شود، دستور شل اجرا می‌شود (همانند !)، اما متعاقباً هر خروجی (stdout) از دستور شل تجزیه شده و به عنوان دستورات guestfish اجرا می‌شود.

بنابراین می‌توانید از اسکریپت شل برای ساخت دستورات دلخواه guestfish استفاده کنید که سپس توسط guestfish تجزیه و اجرا شوند.

برای مثال، ایجاد دنباله‌ای از فایل‌ها (مانند /foo.1 تا /foo.100) صرفاً با استفاده از دستورات guestfish خسته‌کننده است. با این حال، اگر از یک اسکریپت شل برای ایجاد دستورات guestfish برای ما استفاده شود، این کار ساده خواهد بود:

<! for n in `seq 1 100`; do echo write /foo.$n $n; done

یا با نام‌هایی مانند /foo.001:

<! for n in `seq 1 100`; do printf "write /foo.%03d %d\n" $n $n; done

هنگام استفاده تعاملی از guestfish، اجرای اولیه خود اسکریپت شل می‌تواند مفید باشد (یعنی حذف کاراکتر ابتدایی "<" به طوری که فقط یک دستور محلی ساده ! باشد)، تا مشاهده کنید چه دستورات guestfish اجرا خواهند شد، و وقتی از آن‌ها راضی بودید، کاراکتر "<" را در ابتدا قرار دهید تا دستورات guestfish به‌طور واقعی اجرا شوند.

کنترل چندین فرایند GUESTFISH (CONTROLLING MULTIPLE GUESTFISH PROCESSES)

عبارت "eval" متغیر محیطی $GUESTFISH_PID را تنظیم می‌کند که از طریق آن گزینه --remote متوجه می‌شود دستورات را به کجا ارسال کند. می‌توانید چندین فرایند شنونده guestfish را با استفاده از دستورات زیر اجرا کنید:

eval "`guestfish --listen`"
pid1=$GUESTFISH_PID
eval "`guestfish --listen`"
pid2=$GUESTFISH_PID
...
guestfish --remote=$pid1 cmd
guestfish --remote=$pid2 cmd

کنترل از راه دور و CSH (REMOTE CONTROL AND CSH)

هنگام استفاده از پوسته‌های شبه csh (مانند csh، tcsh و غیره) باید گزینه --csh را اضافه کنید:

eval "`guestfish --listen --csh`"

جزئیات کنترل از راه دور (REMOTE CONTROL DETAILS)

کنترل از راه دور از طریق یک سوکت دامنه یونیکس (Unix domain socket) به نام /tmp/.guestfish-$UID/socket-$PID انجام می‌شود، که در آن $UID شناسه کاربری مؤثر فرایند و $PID شناسه فرایند سرور است.

نسخه‌های کلاینت و سرور guestfish باید کاملاً یکسان باشند.

نسخه‌های قدیمی‌تر guestfish در برابر آسیب‌پذیری CVE-2013-4419 آسیب‌پذیر بودند (بخش "CVE-2013-4419" در guestfs(3) را ببینید). این مورد در نسخه جاری برطرف شده است.

استفاده مطمئن از کنترل از راه دور در اسکریپت‌های پوسته (USING REMOTE CONTROL ROBUSTLY FROM SHELL SCRIPTS)

در Bash می‌توانید از کد زیر استفاده کنید که یک نمونه guestfish ایجاد کرده، خط فرمان را به درستی نقل‌قول‌گذاری می‌کند، خطای راه‌اندازی را مدیریت کرده و هنگام خروج اسکریپت فرایند guestfish را پاکسازی می‌کند:

#!/bin/bash -
set -e
guestfish[0]="guestfish"
guestfish[1]="--listen"
guestfish[2]="--ro"
guestfish[3]="-a"
guestfish[4]="disk.img"
GUESTFISH_PID=
eval $("${guestfish[@]}")
if [ -z "$GUESTFISH_PID" ]; then
    echo "error: guestfish didn't start up, see error messages above"
    exit 1
fi
cleanup_guestfish ()
{
    guestfish --remote -- exit >/dev/null 2>&1 ||:
}
trap cleanup_guestfish EXIT ERR
guestfish --remote -- run
# ...

عدم کارکرد کنترل از راه دور با گزینه‌هایی نظیر -a (REMOTE CONTROL DOES NOT WORK WITH -a ETC. OPTIONS)

گزینه‌هایی مانند -a، --add، -N، --new و غیره تعامل مناسبی با پشتیبانی راه دور ندارند. آن‌ها به صورت محلی پردازش می‌شوند و به guestfish راه دور ارسال نمی‌شوند. به طور خاص، دستور زیر آنچه انتظار دارید را انجام نخواهد داد:

guestfish --remote --add disk.img

از این گزینه‌ها استفاده نکنید. در عوض از دستورات معادل آن‌ها استفاده کنید، برای مثال:

guestfish --remote add-drive disk.img

یا:

guestfish --remote
><fs> add disk.img

قفل شدن دستور RUN در کنترل از راه دور (REMOTE CONTROL RUN COMMAND HANGING)

استفاده از دستور "run" (یا "launch") از راه دور در زمینه جایگزینی دستور (command substitution) باعث قفل شدن (hang) می‌شود، یعنی این کار را انجام ندهید (به بک‌تیک‌ها توجه کنید):

a=`guestfish --remote run`

از آنجا که دستور "run" هیچ خروجی‌ای در stdout تولید نمی‌کند، این کار در هر صورت فایده‌ای ندارد. برای اطلاعات بیشتر پیوند https://bugzilla.redhat.com/show_bug.cgi?id=592910 را ببینید.

مثال‌ها (EXAMPLES)

ایجاد یک دیسک ۱ گیگابایتی با پارتیشن فرمت‌شده با ext4 به نام test1.img در دایرکتوری جاری:

guestfish -N fs:ext4

ایجاد یک دیسک ۳۲ مگابایتی با پارتیشن فرمت‌شده با VFAT و سوار کردن آن:

guestfish -N fs:vfat:32M -m /dev/sda1

ایجاد یک دیسک خالی ۲۰۰ مگابایتی:

guestfish -N disk:200M

ایجاد یک دیسک خالی ۲۰۰ مگابایتی به نام blankdisk.img (به جای test1.img):

guestfish -N blankdisk.img=disk:200M

-N disk - ایجاد یک دیسک خام

"guestfish -N [filename=]disk[:size]"

ایجاد یک دیسک خام، با اندازه پیش‌فرض 1G.

اندازه پیش‌فرض را می‌توان با ارائه یک پارامتر اختیاری تغییر داد.

پارامترهای اختیاری عبارتند از:

Name          Default value
size          1G            the size of the disk image

-N part - ایجاد یک دیسک پارتیشن‌بندی‌شده

"guestfish -N [filename=]part[:size[:partition]]"

ایجاد دیسک با یک پارتیشن منفرد. به طور پیش‌فرض اندازه دیسک 1G است (فضای در دسترس در پارتیشن کمی کوچکتر خواهد بود) و جدول پارتیشن از نوع MBR (به سبک قدیمی DOS) خواهد بود.

این مقادیر پیش‌فرض را می‌توان با ارائه پارامترهای اختیاری تغییر داد.

پارامترهای اختیاری عبارتند از:

Name          Default value
size          1G            the size of the disk image
partition     mbr           partition table type

-N fs - ایجاد یک سیستم‌فایل

"guestfish -N [filename=]fs[:filesystem[:size[:partition]]]"

ایجاد یک دیسک با یک پارتیشن منفرد، به‌طوری‌که پارتیشن حاوی یک سیستم‌فایل خالی باشد. به صورت پیش‌فرض یک دیسک 1G (فضای در دسترس سیستم‌فایل کمی کوچکتر خواهد بود) با جدول پارتیشن MBR (سبک قدیمی DOS) و سیستم‌فایل ext2 ایجاد می‌شود.

این مقادیر پیش‌فرض را می‌توان با ارائه پارامترهای اختیاری تغییر داد.

پارامترهای اختیاری عبارتند از:

Name          Default value
filesystem    ext2          the type of filesystem to use
size          1G            the size of the disk image
partition     mbr           partition table type

-N lv - ایجاد یک دیسک با حجم منطقی

"guestfish -N [filename=]lv[:name[:size[:partition]]]"

ایجاد یک دیسک با یک پارتیشن منفرد، تنظیم پارتیشن به عنوان یک حجم فیزیکی LVM2، و قرار دادن یک گروه حجم (volume group) و حجم منطقی (logical volume) روی آن. به طور پیش‌فرض یک دیسک 1G با VG و LV به نام "/dev/VG/LV" ایجاد می‌شود. می‌توانید نام VG و LV را با ارائه نامی دیگر به عنوان اولین پارامتر اختیاری تغییر دهید.

توجه داشته باشید که این دستور سیستم‌فایل ایجاد نمی‌کند. برای این کار از 'lvfs' استفاده کنید.

پارامترهای اختیاری عبارتند از:

Name          Default value
name          /dev/VG/LV    the name of the VG and LV to use
size          1G            the size of the disk image
partition     mbr           partition table type

-N lvfs - ایجاد یک دیسک با حجم منطقی و سیستم‌فایل

"guestfish -N [filename=]lvfs[:name[:filesystem[:size[:partition]]]]"

ایجاد یک دیسک با یک پارتیشن منفرد، تنظیم پارتیشن به عنوان یک حجم فیزیکی LVM2، و قرار دادن یک گروه حجم و حجم منطقی روی آن. سپس قالب‌بندی LV با یک سیستم‌فایل. به طور پیش‌فرض یک دیسک 1G با VG و LV به نام "/dev/VG/LV" همراه با سیستم‌فایل ext2 ایجاد می‌شود.

پارامترهای اختیاری عبارتند از:

Name          Default value
name          /dev/VG/LV    the name of the VG and LV to use
filesystem    ext2          the type of filesystem to use
size          1G            the size of the disk image
partition     mbr           partition table type

-N bootroot - ایجاد یک سیستم‌فایل بوت و ریشه

"guestfish -N [filename=]bootroot[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]"

ایجاد یک دیسک با دو پارتیشن، برای سیستم‌فایل‌های بوت (boot) و ریشه (root). هر دو سیستم‌فایل به طور مستقل قالب‌بندی می‌شوند. چندین پارامتر اختیاری وجود دارد که چینش دقیق و انواع سیستم‌فایل را کنترل می‌کنند.

پارامترهای اختیاری عبارتند از:

Name          Default value
bootfs        ext2          the type of filesystem to use for boot
rootfs        ext2          the type of filesystem to use for root
size          1G            the size of the disk image
bootsize      128M          the size of the boot filesystem
partition     mbr           partition table type

-N bootrootlv - ایجاد سیستم‌فایل بوت و ریشه با استفاده از LVM

"guestfish -N [filename=]bootrootlv[:name[:bootfs[:rootfs[:size[:bootsize[:partition]]]]]]"

این مورد مشابه "bootroot" است اما (فقط) سیستم‌فایل ریشه روی یک حجم منطقی قرار می‌گیرد که به طور پیش‌فرض "/dev/VG/LV" نام دارد. چندین پارامتر اختیاری چینش دقیق را کنترل می‌کنند.

پارامترهای اختیاری عبارتند از:

Name          Default value
name          /dev/VG/LV    the name of the VG and LV for root
bootfs        ext2          the type of filesystem to use for boot
rootfs        ext2          the type of filesystem to use for root
size          1G            the size of the disk image
bootsize      128M          the size of the boot filesystem
partition     mbr           partition table type

-a disk.img

-a file:///path/to/disk.img

افزودن تصویر دیسک محلی (یا دستگاه) به نام disk.img.

-a ftp://[user@]example.com[:port]/disk.img

-a ftps://[user@]example.com[:port]/disk.img

http://[user@]example.com[:port]/disk.img'>-a http://[user@]example.com[:port]/disk.img

https://[user@]example.com[:port]/disk.img'>-a https://[user@]example.com[:port]/disk.img

افزودن یک دیسک واقع روی یک سرور راه دور FTP یا HTTP.

دستور معادل API به این صورت خواهد بود:

><fs> add /disk.img protocol:(ftp|...) server:tcp:example.com

-a iscsi://example.com[:port]/target-iqn-name[/lun]

افزودن دیسک واقع روی یک سرور iSCSI.

دستور معادل API به این صورت خواهد بود:

><fs> add target-iqn-name/lun protocol:iscsi server:tcp:example.com

-a nbd://example.com[:port]

-a nbd://example.com[:port]/exportname

-a nbd://?socket=/socket

-a nbd:///exportname?socket=/socket

افزودن یک دیسک واقع روی ذخیره‌ساز Network Block Device (nbd).

بخش exportname در URI یک نام اکسپورت NBD را مشخص می‌کند، اما معمولاً خالی رها می‌شود.

پارامتر اختیاری ?socket را می‌توان برای مشخص کردن یک سوکت دامنه یونیکس که از طریق آن با سرور NBD ارتباط برقرار می‌کنیم استفاده کرد. توجه داشته باشید که نمی‌توانید نام سرور (یعنی TCP/IP) و مسیر سوکت را با هم ترکیب کنید.

دستور معادل API به صورت زیر خواهد بود (بدون نام اکسپورت):

><fs> add "" protocol:nbd server:[tcp:example.com|unix:/socket]

-a rbd:///pool/disk

-a rbd://example.com[:port]/pool/disk

افزودن یک تصویر دیسک واقع روی یک حجم ذخیره‌سازی Ceph (RBD/librbd).

اگرچه libguestfs و Ceph از چندین سرور پشتیبانی می‌کنند، اما هنگام استفاده از این نحو URI تنها یک سرور واحد را می‌توان مشخص کرد.

دستور معادل API به این صورت خواهد بود:

><fs> add pool/disk protocol:rbd server:tcp:example.com:port

-a ssh://[user@]example.com[:port]/disk.img

افزودن یک تصویر دیسک واقع روی یک سرور راه دور، با دسترسی از طریق پروتکل SFTP پوسته امن (ssh). پروتکل SFTP به طور پیش‌فرض توسط تمامی سرورهای اصلی SSH پشتیبانی می‌شود.

دستور معادل API به این صورت خواهد بود:

><fs> add /disk protocol:ssh server:tcp:example.com [username:user]

توجه داشته باشید که شناسه‌های URI از نحو RFC 3986 پیروی می‌کنند: به ویژه، محدودیت‌هایی روی کاراکترهای مجاز برای اجزای مختلف URI وجود دارد. کاراکترهایی مانند ":"، "@" و "/" باید کدگذاری درصدی (percent-encoded) شوند:

$ guestfish -a ssh://user:pass%40word@example.com/disk.img

در این حالت، گذرواژه "pass@word" است.

مثال‌هایی از اعلان ورودی (EXAMPLES OF PROMPTS)

توجه داشته باشید که این مثال‌ها به ترمینالی نیاز دارند که از کدهای گریز ANSI پشتیبانی کند.

• GUESTFISH_PS1='\[\e[1;30m\]><fs>\[\e[0;30m\] '

  نسخه مشکی پررنگ (bold) از اعلان معمولی.

• GUESTFISH_PS1='\[\e[1;32m\]><fs>\[\e[0;31m\] '
  GUESTFISH_OUTPUT='\e[0m'
  GUESTFISH_RESTORE="$GUESTFISH_OUTPUT"
  GUESTFISH_INIT='\e[1;34m'

  متن خوش‌آمدگویی آبی، اعلان ورودی سبز، دستورات قرمز، خروجی دستور مشکی.

help

help
help cmd
help -l|--list

بدون هیچ پارامتری، راهنمای کلی را ارائه می‌دهد.

با پارامتر "cmd"، راهنمای تفصیلی آن دستور را نمایش می‌دهد.

با -l یا --list، تمام دستورات را فهرست می‌کند.

exit

quit

از guestfish خارج می‌شود. همچنین می‌توانید از کلید "^D" استفاده کنید.

alloc

allocate

alloc filename size

این دستور یک فایل خالی (صفرشده) با اندازه داده شده ایجاد کرده و سپس آن را اضافه می‌کند تا بتوان آن را بیشتر بررسی کرد.

برای ایجاد پیشرفته‌تر تصویر، "disk-create" را ببینید.

اندازه را می‌توان با استفاده از پسوندهای استاندارد مشخص کرد، مانند "1M".

برای ایجاد یک فایل کم‌حجم (sparse)، به جای آن از "sparse" استفاده کنید. برای ایجاد یک تصویر دیسک آماده، بخش "تصاویر دیسک آماده (PREPARED DISK IMAGES)" را ببینید.

copy-in

copy-in local [local ...] /remotedir

دستور "copy-in" فایل‌ها یا دایرکتوری‌های محلی را به صورت بازگشتی در تصویر دیسک کپی کرده و آن‌ها را در دایرکتوری به نام /remotedir (که باید وجود داشته باشد) قرار می‌دهد. این فرافرمان (meta-command) در guestfish در صورت نیاز به دنباله‌ای از دستورات "tar-in" و سایر دستورات تبدیل می‌شود.

چندین فایل و دایرکتوری محلی را می‌توان مشخص کرد، اما آخرین پارامتر همیشه باید یک دایرکتوری راه دور باشد. نویسه‌های عام (wildcards) قابل استفاده نیستند.

copy-out

copy-out remote [remote ...] localdir

دستور "copy-out" فایل‌ها یا دایرکتوری‌های راه دور را به صورت بازگشتی از تصویر دیسک به بیرون کپی کرده و آن‌ها را روی دیسک میزبان در یک دایرکتوری محلی به نام "localdir" (که باید وجود داشته باشد) قرار می‌دهد. این فرافرمان در guestfish در صورت نیاز به دنباله‌ای از دستورات "download"، "tar-out" و سایر دستورات تبدیل می‌شود.

چندین فایل و دایرکتوری راه دور را می‌توان مشخص کرد، اما آخرین پارامتر همیشه باید یک دایرکتوری محلی باشد. برای دانلود در دایرکتوری جاری، از "." مانند زیر استفاده کنید:

copy-out /home .

نویسه‌های عام در دستور معمولی قابل استفاده نیستند، اما می‌توانید با کمک "glob" به شکل زیر از آن‌ها استفاده کنید:

glob copy-out /home/* .

delete-event

delete-event name

گرداننده رویدادی (event handler) که قبلاً به نام "name" ثبت شده بود را حذف می‌کند. اگر چندین گرداننده رویداد با همین نام ثبت شده باشند، همه آن‌ها حذف می‌شوند.

همچنین دستورات guestfish به نام‌های "event" و "list-events" را ببینید.

display

display filename

از "display" (یک برنامه نمایش گرافیکی) برای نمایش یک فایل تصویر استفاده کنید. این دستور فایل را دانلود کرده و "display" را روی آن اجرا می‌کند.

برای استفاده از یک برنامه جایگزین، متغیر محیطی "GUESTFISH_DISPLAY_IMAGE" را تنظیم کنید. به عنوان مثال برای استفاده از برنامه نمایش تصاویر گنوم:

export GUESTFISH_DISPLAY_IMAGE=eog

همچنین display(1) را ببینید.

echo

echo [params ...]

این دستور پارامترها را در ترمینال چاپ (echo) می‌کند.

edit

vi

emacs

edit filename

برای ویرایش یک فایل استفاده می‌شود. فایل را دانلود کرده، با استفاده از ویرایشگر شما به صورت محلی ویرایش می‌کند، سپس نتیجه را بارگذاری می‌نماید.

ویرایشگر همان $EDITOR است. با این حال اگر از دستورات جایگزین "vi" یا "emacs" استفاده کنید، ویرایشگرهای متناظر آن‌ها را دریافت خواهید کرد.

event

event name eventset "shell script ..."

ثبت یک قطعه اسکریپت پوسته که هنگام رخ دادن یک رویداد اجرا می‌شود. برای بررسی API رویداد در libguestfs، بخش "guestfs_set_event_callback" در guestfs(3) را ببینید.

پارامتر "name" نامی است که به این گرداننده رویداد می‌دهید. می‌تواند هر رشته‌ای (حتی رشته خالی) باشد و صرفاً برای این است که بتوانید با استفاده از دستور "delete-event" در guestfish گرداننده را حذف کنید.

پارامتر "eventset" یک فهرست جدا شده با کاما از یک یا چند رویداد است، به عنوان مثال "close" یا "close,trace". مقدار ویژه "*" به معنای همه رویدادها است.

پارامتر سوم و نهایی قطعه اسکریپت پوسته (یا هر دستور خارجی) است که هنگام وقوع هر یک از رویدادهای موجود در eventset اجرا می‌شود. این اسکریپت با استفاده از "$SHELL -c" اجرا می‌شود، یا اگر $SHELL تنظیم نشده باشد با /bin/sh -c.

قطعه اسکریپت پوسته، پارامترهای بازفراخوانی (callback) را به صورت آرگومان‌های $1، $2 و غیره دریافت می‌کند. رویداد واقعی فراخوانی‌شده در متغیر محیطی $EVENT در دسترس است.

event "" close "echo closed"
event messages appliance,library,trace "echo $@"
event "" progress "echo progress: $3/$4"
event "" * "echo $EVENT $@"

همچنین دستورات guestfish به نام‌های "delete-event" و "list-events" را ببینید.

glob

glob command args...

گسترش نویسه‌های عام در هر یک از مسیرهای موجود در فهرست args، و اجرای مکرر "command" روی هر مسیر منطبق.

بخش "WILDCARDS AND GLOBBING" را ببینید.

hexedit

hexedit <filename|device>
hexedit <filename|device> <max>
hexedit <filename|device> <start> <max>

استفاده از hexedit (ویرایشگر هگز) برای ویرایش تمام یا بخشی از یک فایل باینری یا دستگاه بلوکی.

این دستور با دانلود کل فایل یا دستگاه، ویرایش محلی آن و سپس بارگذاری مجدد آن کار می‌کند. اگر فایل یا دستگاه بزرگ باشد، باید با استفاده از پارامترهای "max" و/یا "start" "max" مشخص کنید که کدام بخش را می‌خواهید ویرایش کنید. "start" و "max" بر حسب بایت مشخص می‌شوند و پسوندهای معمول مانند "1M" (یک مگابایت) مجاز هستند.

برای مثال، برای ویرایش چند سکتور اول یک دیسک می‌توانید دستور زیر را اجرا کنید:

hexedit /dev/sda 1M

که به شما امکان می‌دهد در هر نقطه‌ای از مگابایت اول دیسک ویرایش انجام دهید.

برای ویرایش سوپربلاک یک سیستم‌فایل ext2 روی /dev/sda1 دستور زیر را اجرا کنید:

hexedit /dev/sda1 0x400 0x400

(با فرض اینکه سوپربلاک در مکان استاندارد قرار دارد).

این دستور به برنامه خارجی hexedit(1) نیاز دارد. می‌توانید با تنظیم متغیر محیطی "HEXEDITOR" برنامه دیگری را برای استفاده مشخص کنید.

همچنین "hexdump" را ببینید.

lcd

lcd directory

تغییر دایرکتوری محلی، یعنی دایرکتوری جاری خود guestfish.

توجه داشته باشید که "!cd" آن کاری که ممکن است انتظار داشته باشید را انجام نمی‌دهد.

list-events

list-events

فهرست کردن گرداننده‌های رویداد ثبت‌شده با استفاده از دستور "event" در guestfish.

man

manual

man

صفحه راهنمای guestfish را باز می‌کند.

more

less

more filename
less filename

برای مشاهده محتوای یک فایل استفاده می‌شود.

نمایش‌دهنده پیش‌فرض $PAGER است. با این حال اگر از دستور جایگزین "less" استفاده کنید، به طور خاص از دستور "less" استفاده خواهد شد.

not

not command [args...]

یک دستور موجود در guestfish را اجرا کرده و کد خروج را نقیض (معکوس) می‌کند؛ بنابراین اگر دستور با شکست مواجه شود، "not command" موفق خواهد شد.

توجه داشته باشید که این دستور مفهوم دستوراتی که مقادیر بولی برمی‌گردانند را معکوس نمی‌کند (برای مثال "not exists /foo" آن کاری که فکر می‌کنید را انجام نمی‌دهد).

برای مثال، "not cat /foo" بررسی خواهد کرد که فایل وجود ندارد.

reopen

reopen

بستن و بازگشایی مجدد هندل libguestfs. استفاده از این دستور در حالت عادی ضروری نیست، زیرا هندل به درستی هنگام خروج guestfish بسته می‌شود. با این حال این دستور گاهی برای آزمایش مفید است.

setenv

setenv VAR value

تنظیم متغیر محیطی "VAR" روی رشته "value".

برای چاپ مقدار یک متغیر محیطی از یک دستور پوسته مانند زیر استفاده کنید:

!echo $VAR

sparse

sparse filename size

یک فایل کم‌حجم (sparse) خالی با اندازه داده شده ایجاد کرده و سپس اضافه می‌کند تا بتوان آن را بیشتر بررسی کرد.

از همه جهات مانند دستور "alloc" کار می‌کند، به جز اینکه فایل تصویر به صورت کم‌حجم تخصیص می‌یابد؛ به این معنی که بلوک‌های دیسک تا زمانی که مورد نیاز نباشند به فایل اختصاص داده نمی‌شوند. فایل‌های دیسک کم‌حجم فقط هنگام نوشتن فضا مصرف می‌کنند، اما کندتر هستند و این خطر وجود دارد که در حین عملیات نوشتن، فضای واقعی دیسک شما تمام شود.

برای ایجاد پیشرفته‌تر تصویر دیسک، "disk-create" را ببینید.

اندازه را می‌توان با استفاده از پسوندهای استاندارد مشخص کرد، مانند "1M".

همچنین دستور "scratch" در guestfish را ببینید.

supported

supported

این دستور فهرستی از گروه‌های اختیاری شناخته‌شده برای دیمن (daemon) را برمی‌گرداند و مشخص می‌کند کدام‌یک توسط این بیلد از ابزارک libguestfs پشتیبانی می‌شوند.

همچنین بخش "AVAILABILITY" در guestfs(3) را ببینید.

time

time command args...

دستور را طبق معمول اجرا می‌کند، اما زمان سپری شده را پس از آن چاپ می‌نماید. این کار می‌تواند برای محک‌زدن (benchmarking) عملیات مفید باشد.

unsetenv

unsetenv VAR

حذف "VAR" از محیط.

acl-delete-def-file

acl-delete-def-file dir

این تابع لیست کنترل دسترسی (ACL) پیش‌فرض POSIX متصل به دایرکتوری "dir" را حذف می‌کند.

این دستور به ویژگی "acl" وابسته است. همچنین "feature-available" را ببینید.

acl-get-file

acl-get-file path acltype

این تابع لیست کنترل دسترسی (ACL) پازیکس پیوست‌شده به "path" را برمی‌گرداند. مقدار ACL در قالب «متن بلند» بازگردانده می‌شود (نگاه کنید به acl(5)).

پارامتر "acltype" می‌تواند یکی از مقادیر زیر باشد:

"access"

برگرداندن ACL معمولی (access) برای هر فایل، دایرکتوری یا شیء دیگر فایل‌سیستم.

"default"

برگرداندن ACL پیش‌فرض. معمولاً این گزینه تنها زمانی کاربرد دارد که "path" یک دایرکتوری باشد.

این دستور به ویژگی "acl" وابسته است. همچنین نگاه کنید به "feature-available".

acl-set-file

acl-set-file path acltype acl

این تابع لیست کنترل دسترسی (ACL) پازیکس پیوست‌شده به "path" را تنظیم می‌کند.

پارامتر "acltype" می‌تواند یکی از مقادیر زیر باشد:

"access"

تنظیم ACL معمولی (access) برای هر فایل، دایرکتوری یا شیء دیگر فایل‌سیستم.

"default"

تنظیم ACL پیش‌فرض. معمولاً این گزینه تنها زمانی کاربرد دارد که "path" یک دایرکتوری باشد.

پارامتر "acl" عبارت است از ACL جدید در قالب «متن بلند» یا «متن کوتاه» (نگاه کنید به acl(5)). مقدار جدید ACL به‌طور کامل جایگزین هرگونه ACL قبلی روی فایل می‌شود. این ACL باید شامل تمام مجوزهای کامل یونیکس باشد (مانند "u::rwx,g::rx,o::rx").

اگر کاربران یا گروه‌های مجزایی را مشخص می‌کنید، فیلد mask نیز الزامی است (مانند "m::rwx")، که به دنبال آن فیلد(های) "u:ID:..." و/یا "g:ID:..." می‌آید. بنابراین یک رشته کامل ACL ممکن است به این شکل باشد:

u::rwx,g::rwx,o::rwx,m::rwx,u:500:rwx,g:500:rwx
\ Unix permissions / \mask/ \      ACL        /

باید از شناسه کاربری عددی (UID) و شناسه گروهی عددی (GID) استفاده کنید. برای نگاشت نام‌های کاربری و نام‌های گروهی به شناسه‌های عددی متناظر در بستر سیستم مهمان، از توابع Augeas استفاده نمایید (نگاه کنید به "aug-init").

این دستور به ویژگی "acl" وابسته است. همچنین نگاه کنید به "feature-available".

add-cdrom

add-cdrom filename

این تابع یک ایمیج دیسک CD-ROM مجازی را به مهمان اضافه می‌کند.

این ایمیج به عنوان درایو فقط‌خواندنی افزوده می‌شود، بنابراین این تابع معادل "add-drive-ro" است.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "add-drive-ro" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

add-domain

domain

add-domain dom [libvirturi:..] [readonly:true|false] [iface:..] [live:true|false] [allowuuid:true|false] [readonlydisk:..] [cachemode:..] [discard:..] [copyonread:true|false]

این تابع دیسک(های) متصل به دامین نام‌برده libvirt یعنی "dom" را اضافه می‌کند. نحوه کار آن به این صورت است که به libvirt متصل شده، دامین و XML دامین را از libvirt درخواست می‌کند، آن را برای یافتن دیسک‌ها پردازش می‌نماید، و برای هر دیسک دستور "add-drive-opts" را فراخوانی می‌کند.

تعداد دیسک‌های اضافه شده برگردانده می‌شود. این عملیات اتمیک است: در صورت بازگشت خطا، هیچ دیسکی اضافه نمی‌شود.

این تابع بررسی‌های اولیه‌ای انجام می‌دهد تا مطمئن شود دامین libvirt در حال اجرا نیست (مگر اینکه "readonly" برابر true باشد). در نسخه‌های آینده سعی خواهیم کرد قفل libvirt را روی هر دیسک به دست آوریم.

دیسک‌ها باید به صورت محلی در دسترس باشند. این اغلب به این معنی است که افزودن دیسک‌ها از طریق یک اتصال راه دور libvirt (نگاه کنید به https://libvirt.org/remote.html) شکست خواهد خورد مگر اینکه آن دیسک‌ها از طریق همان مسیر دستگاه در سیستم محلی نیز قابل دسترسی باشند.

پارامتر اختیاری "libvirturi" شناسه URI مربوط به libvirt را تعیین می‌کند (نگاه کنید به https://libvirt.org/uri.html). اگر این مقدار تنظیم نشود، به URI پیش‌فرض libvirt متصل می‌شویم (یا مقداری که از طریق یک متغیر محیطی تنظیم شده است، برای جزئیات کامل به مستندات libvirt مراجعه کنید).

فلگ اختیاری "live" در نسخه‌های libguestfs ≥ 1.48 نادیده گرفته می‌شود.

اگر فلگ "allowuuid" برابر true باشد (پیش‌فرض false است)، آنگاه می‌توان به جای نام دامین یک UUID پاس داد. رشته "dom" ابتدا به عنوان UUID در نظر گرفته و جستجو می‌شود، و در صورت عدم موفقیت در جستجو، با "dom" طبق روال معمول به عنوان یک نام رفتار می‌شود.

پارامتر اختیاری "readonlydisk" کنترل می‌کند که در مواجهه با دیسک‌هایی که دارای علامت <readonly/> در ساختار XML مربوط به libvirt هستند، چه رفتاری صورت گیرد. مقادیر مجاز عبارتند از:

readonlydisk = "error"

اگر "readonly" برابر false باشد:

در صورت یافتن هر دیسکی با فلگ <readonly/>، کل فراخوانی با یک خطا لغو می‌شود.

اگر "readonly" برابر true باشد:

دیسک‌های دارای فلگ <readonly/> به صورت فقط‌خواندنی اضافه می‌شوند.

readonlydisk = "read"

اگر "readonly" برابر false باشد:

دیسک‌های دارای فلگ <readonly/> به صورت فقط‌خواندنی اضافه می‌شوند. سایر دیسک‌ها به صورت خواندنی/نوشتنی اضافه می‌شوند.

اگر "readonly" برابر true باشد:

دیسک‌های دارای فلگ <readonly/> به صورت فقط‌خواندنی اضافه می‌شوند.

readonlydisk = "write" (default)

اگر "readonly" برابر false باشد:

دیسک‌های دارای فلگ <readonly/> به صورت خواندنی/نوشتنی اضافه می‌شوند.

اگر "readonly" برابر true باشد:

دیسک‌های دارای فلگ <readonly/> به صورت فقط‌خواندنی اضافه می‌شوند.

readonlydisk = "ignore"

اگر "readonly" برابر true یا false باشد:

از دیسک‌های دارای فلگ <readonly/> صرف‌نظر می‌شود.

در صورت وجود، مقدار ویژگی "logical_block_size" از تگ <blockio/> در XML مربوط به libvirt به عنوان پارامتر "blocksize" به "add-drive-opts" پاس داده می‌شود.

سایر پارامترهای اختیاری مستقیماً به "add-drive-opts" ارسال می‌شوند.

این دستور دارای یک یا چند آرگومان اختیاری است. نگاه کنید به "OPTIONAL ARGUMENTS".

add-drive

add

add-drive-opts

add-drive filename [readonly:true|false] [format:..] [iface:..] [name:..] [label:..] [protocol:..] [server:..] [username:..] [secret:..] [cachemode:..] [discard:..] [copyonread:true|false] [blocksize:N]

این تابع یک ایمیج دیسک به نام filename را به هندل اضافه می‌کند. filename می‌تواند یک فایل معمولی میزبان یا یک دستگاه میزبان باشد.

هنگامی که این تابع قبل از "launch" (حالت معمول) فراخوانی شود، در اولین فراخوانی دیسک به صورت /dev/sda، در بار دوم به صورت /dev/sdb و به همین ترتیب در API ظاهر می‌شود.

برای استفاده از libguestfs لزوماً نیازی به کاربر ریشه (root) بودن نیست. اما بدیهی است که برای انجام هرگونه عملیات مورد نظر، به مجوزهای دسترسی کافی روی فایل نیاز دارید (یعنی دسترسی خواندن برای خواندن ایمیج یا دسترسی نوشتن برای ویرایش ایمیج).

این فراخوانی وجود filename را بررسی می‌کند.

filename می‌تواند رشته ویژه "/dev/null" باشد. به "NULL DISKS" در guestfs(3) مراجعه کنید.

آرگومان‌های اختیاری عبارتند از:

"readonly"

اگر true باشد، با ایمیج به صورت فقط‌خواندنی رفتار می‌شود. نوشتن همچنان مجاز است، اما تغییرات در یک لایه همپوشان اسنپ‌شات موقت ذخیره شده و در انتها دور ریخته می‌شوند. دیسک اضافه شده تغییر نخواهد کرد.

"format"

این گزینه فرمت ایمیج را تحمیل می‌کند. اگر این گزینه را حذف کنید (یا از "add-drive" یا "add-drive-ro" استفاده کنید)، فرمت به صورت خودکار تشخیص داده می‌شود. فرمت‌های ممکن شامل "raw" و "qcow2" هستند.

تشخیص خودکار فرمت هنگام کار با ایمیج‌های غیرقابل اعتماد با فرمت خام (raw) ممکن است روزنه امنیتی ایجاد کند. به CVE-2010-3851 و RHBZ#642934 مراجعه کنید. تعیین صریح فرمت این روزنه امنیتی را مسدود می‌کند.

"iface"

این گزینه که به ندرت استفاده می‌شود، امکان شبیه‌سازی رفتار فراخوانی منسوخ‌شده "add-drive-with-if" را فراهم می‌کند (به آن مراجعه کنید).

"name"

این فیلد قبلاً به عنوان راهنما برای بررسی و بازرسی مهمان ارسال می‌شد، اما دیگر استفاده نمی‌شود.

"label"

یک برچسب به دیسک اختصاص می‌دهد. برچسب باید یک رشته کوتاه و یکتا باشد که فقط از کاراکترهای اسکی "[a-zA-Z]" استفاده کند. علاوه بر نام معمول آن در API (مانند /dev/sda)، درایو همچنین با نام /dev/disk/guestfs/label شناخته خواهد شد.

به "DISK LABELS" در guestfs(3) مراجعه کنید.

"protocol"

آرگومان اختیاری پروتکل می‌تواند برای انتخاب یک پروتکل مبدأ جایگزین استفاده شود.

همچنین نگاه کنید به: "REMOTE STORAGE" در guestfs(3).

"server"

برای پروتکل‌هایی که نیاز به دسترسی به یک سرور راه دور دارند، این پارامتر فهرستی از سرور(ها) است.

Protocol       Number of servers required
--------       --------------------------
file           List must be empty or param not used at all
ftp|ftps|http|https  Exactly one
iscsi          Exactly one
nbd            Exactly one
rbd            Zero or more
ssh            Exactly one

هر عنصر فهرست یک رشته مشخص‌کننده سرور است. این رشته باید در یکی از فرمت‌های زیر باشد:

hostname
hostname:port
tcp:hostname
tcp:hostname:port
unix:/path/to/socket

در صورت حذف شماره پورت، پورت استاندارد مربوط به پروتکل استفاده می‌شود (نگاه کنید به /etc/services).

"username"

برای پروتکل‌های "ftp"، "ftps"، "http"، "https"، "iscsi"، "rbd" و "ssh"، نام کاربری راه دور را مشخص می‌کند.

در صورت عدم تعیین، برای "ssh" نام کاربری محلی استفاده می‌شود و برای ceph هیچ احراز هویتی انجام نمی‌گیرد. اما توجه داشته باشید که این موضوع گاهی اوقات ممکن است نتایج غیرمنتظره‌ای به همراه داشته باشد، برای مثال هنگام استفاده از بک‌اند libvirt در حالتی که برای راه‌اندازی ابزار qemu با یک کاربر ویژه مانند "qemu.qemu" پیکربندی شده است. در صورت تردید، نام کاربری راه دور مورد نظر را صریحاً مشخص کنید.

"secret"

فقط برای پروتکل "rbd"، رمز مخفی («secret») مورد استفاده برای اتصال به دستگاه راه دور را مشخص می‌کند. این مقدار باید با فرمت base64 کدگذاری شده باشد.

در صورت عدم تعیین، یک secret منطبق با نام کاربری ارائه‌شده در مکان‌های پیش‌فرض جاکلیدی جستجو می‌شود، یا اگر نام کاربری ارائه نشده باشد، هیچ احراز هویتی انجام نمی‌شود.

"cachemode"

تعیین می‌کند که آیا libguestfs از عملیات همگام‌سازی (sync) تبعیت کند (امن اما کند) یا خیر (ناامن اما سریع). مقادیر ممکن برای این رشته عبارتند از:

"discard"

فعال یا غیرفعال کردن پشتیبانی از آزادسازی بلوک‌ها (یا همان trim / unmap / discard) روی این درایو. در صورت فعال بودن، عملیاتی مانند "fstrim" می‌توانند بلوک‌ها را در فایل یا دستگاه زیرین میزبان آزاد کرده، کم‌حجم سازند یا در آن سوراخ ایجاد کنند (punch holes).

تنظیمات ممکن برای discard عبارتند از:

"copyonread"

پارامتر بولی "copyonread" پشتیبانی از کپی هنگام خواندن (copy-on-read) را فعال می‌کند. این گزینه فقط بر فرمت‌های دیسکی تأثیر می‌گذارد که دارای فایل‌های پشتیبان (backing files) هستند و باعث می‌شود خواندن‌ها در لایه همپوشان ذخیره شوند، که سرعت خواندن‌های مکرر از یک ناحیه دیسک را افزایش می‌دهد.

پیش‌فرض false است.

"blocksize"

این پارامتر اندازه سکتور دیسک را تنظیم می‌کند. مقادیر ممکن عبارتند از 512 (پیش‌فرض در صورت حذف پارامتر) یا 4096. هنگام کار با دیسک‌های «فرمت پیشرفته» (Advanced Format) که از اندازه سکتور 4K استفاده می‌کنند، از 4096 استفاده کنید (https://en.wikipedia.org/wiki/Advanced_Format).

تنها زیرمجموعه‌ای از بک‌اندها از این پارامتر پشتیبانی می‌کنند (در حال حاضر فقط بک‌اندهای libvirt و مستقیم).

این دستور دارای یک یا چند آرگومان اختیاری است. نگاه کنید به "OPTIONAL ARGUMENTS".

add-drive-ro

add-ro

add-drive-ro filename

این تابع معادل فراخوانی "add-drive-opts" با تنظیم پارامتر اختیاری "GUESTFS_ADD_DRIVE_OPTS_READONLY" روی مقدار 1 است، بنابراین دیسک به صورت فقط‌خواندنی اضافه شده و فرمت آن به طور خودکار تشخیص داده می‌شود.

add-drive-ro-with-if

add-drive-ro-with-if filename iface

این تابع مشابه "add-drive-ro" است اما به شما امکان می‌دهد نوع شبیه‌سازی رابط QEMU را در زمان اجرا مشخص کنید. هر دو بک‌اند مستقیم و libvirt پارامتر "iface" را نادیده می‌گیرند.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "add-drive" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

add-drive-scratch

scratch

add-drive-scratch size [name:..] [label:..] [blocksize:N]

این دستور یک درایو موقت چرک‌نویس (scratch) را به هندل اضافه می‌کند. پارامتر "size" اندازه مجازی (به بایت) است. درایو چرک‌نویس در ابتدا خالی است (تمام خواندن‌ها بایت‌های صفر برمی‌گردانند تا زمانی که شروع به نوشتن روی آن کنید). هنگام بسته شدن هندل، درایو حذف می‌شود.

آرگومان‌های اختیاری "name"، "label" و "blocksize" به "add-drive-opts" پاس داده می‌شوند.

این دستور دارای یک یا چند آرگومان اختیاری است. نگاه کنید به "OPTIONAL ARGUMENTS".

add-drive-with-if

add-drive-with-if filename iface

این دستور مشابه "add-drive" است اما به شما امکان می‌دهد نوع شبیه‌سازی رابط QEMU را در زمان اجرا مشخص کنید. هر دو بک‌اند مستقیم و libvirt پارامتر "iface" را نادیده می‌گیرند.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "add-drive" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

aug-clear

aug-clear augpath

مقدار مرتبط با "path" را روی "NULL" تنظیم می‌کند. این معادل دستور "clear" در augtool(1) است.

aug-close

aug-close

هندل جاری Augeas را بسته و تمام منابع مورد استفاده آن را آزاد می‌کند. پس از فراخوانی این تابع، قبل از استفاده از هر تابع دیگر Augeas باید مجدداً "aug-init" را فراخوانی کنید.

aug-defnode

aug-defnode name expr val

متغیر "name" را تعریف می‌کند که مقدار آن حاصل ارزیابی "expr" است.

اگر "expr" به یک مجموعه گره (nodeset) خالی ارزیابی شود، یک گره ایجاد می‌شود که معادل فراخوانی "aug-set" با آرگومان‌های "expr" و "val" است. "name" مجموعه گره‌ای شامل همان تک گره خواهد بود.

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

aug-defvar

aug-defvar name expr

یک متغیر Augeas به نام "name" تعریف می‌کند که مقدار آن حاصل ارزیابی "expr" است. اگر "expr" برابر NULL باشد، "name" تعریف‌نشده باقی می‌ماند.

در صورت موفقیت، این دستور تعداد گره‌های درون "expr" را برمی‌گرداند، یا اگر "expr" به چیزی غیر از مجموعه گره ارزیابی شود، مقدار 0 برگردانده می‌شود.

aug-get

aug-get augpath

مقدار مرتبط با "path" را جستجو می‌کند. اگر "path" دقیقاً با یک گره مطابقت داشته باشد، مقدار "value" برگردانده می‌شود.

aug-init

aug-init root flags

یک هندل جدید Augeas برای ویرایش فایل‌های پیکربندی ایجاد می‌کند. اگر هندل قبلی Augeas مرتبط با این نشست guestfs وجود داشته باشد، بسته می‌شود.

قبل از استفاده از هر یک از دستورات دیگر "aug-*" باید این تابع را فراخوانی کنید.

"root" ریشه فایل‌سیستم است. "root" نباید NULL باشد، به جای آن از / استفاده کنید.

فلگ‌ها همان فلگ‌های تعریف‌شده در <augeas.h> هستند که عبارتند از ترکیب منطقی or اعداد صحیح زیر:

"AUG_SAVE_BACKUP" = 1

نگهداری فایل اصلی با پسوند ".augsave".

"AUG_SAVE_NEWFILE" = 2

ذخیره تغییرات در فایلی با پسوند ".augnew" و بازنویسی نکردن فایل اصلی. بر "AUG_SAVE_BACKUP" تقدم دارد.

"AUG_TYPE_CHECK" = 4

بررسی نوع لنزها (lens).

این گزینه فقط هنگام عیب‌یابی لنزهای Augeas مفید است. استفاده از این گزینه ممکن است به حافظه اضافی برای ماشین مجازی libguestfs نیاز داشته باشد. ممکن است نیاز باشد متغیر محیطی "LIBGUESTFS_MEMSIZE" را تنظیم کنید یا "set-memsize" را فراخوانی نمایید.

"AUG_NO_STDINC" = 8

از مسیر بارگذاری استاندارد برای ماژول‌ها استفاده نکند.

"AUG_SAVE_NOOP" = 16

عملیات ذخیره‌سازی را بدون اثر (no-op) کند و تنها مواردی را که تغییر می‌کردند ثبت نماید.

"AUG_NO_LOAD" = 32

بارگذاری نکردن درخت در "aug-init".

برای بستن هندل، می‌توانید "aug-close" را فراخوانی کنید.

برای کسب اطلاعات بیشتر درباره Augeas، به http://augeas.net مراجعه کنید.

aug-insert

aug-insert augpath label true|false

یک برچسب هم‌سطح (sibling) جدید به نام "label" برای "path" ایجاد می‌کند و آن را قبل یا بعد از "path" (بسته به فلگ بولی "before") در درخت درج می‌نماید.

"path" باید دقیقاً با یک گره موجود در درخت مطابقت داشته باشد، و "label" باید یک برچسب باشد، یعنی نباید حاوی /، "*" باشد یا با یک نمایه درون قلاب "[N]" پایان یابد.

aug-label

aug-label augpath

برچسب (نام آخرین عنصر) عبارت مسیر Augeas یعنی "augpath" برگردانده می‌شود. "augpath" باید دقیقاً با یک گره مطابقت داشته باشد، در غیر این صورت این تابع خطا برمی‌گرداند.

aug-load

aug-load

بارگذاری فایل‌ها در درخت.

برای جزئیات کامل به "aug_load" در مستندات Augeas مراجعه کنید.

aug-ls

aug-ls augpath

این دستور تنها یک میانبر برای اجرای "aug-match" روی "path/*" و مرتب‌سازی گره‌های حاصل به ترتیب الفبایی است.

aug-match

aug-match augpath

فهرستی از مسیرهایی که با عبارت مسیر "path" مطابقت دارند را برمی‌گرداند. مسیرهای بازگردانده شده به اندازه کافی واجد شرایط هستند تا دقیقاً با یک گره در درخت فعلی مطابقت داشته باشند.

aug-mv

aug-mv src dest

انتقال گره "src" به "dest". گره "src" باید دقیقاً با یک گره مطابقت داشته باشد. اگر "dest" وجود داشته باشد، بازنویسی می‌شود.

aug-rm

aug-rm augpath

حذف "path" و تمامی فرزندان آن.

در صورت موفقیت، تعداد مدخل‌هایی که حذف شده‌اند بازگردانده می‌شود.

aug-save

aug-save

تمام تغییرات معلق را روی دیسک می‌نویسد.

فلگ‌هایی که به "aug-init" ارسال شده‌اند، دقیقاً نحوه ذخیره فایل‌ها را تعیین می‌کنند.

aug-set

aug-set augpath val

مقدار مرتبط با "augpath" را روی "val" تنظیم می‌کند.

در API مربوط به Augeas، امکان پاک کردن یک گره با تنظیم مقدار آن به NULL وجود دارد. به دلیل یک نقص جزئی در API مربوط به libguestfs، نمی‌توانید این کار را با این فراخوانی انجام دهید. در عوض باید از فراخوانی "aug-clear" استفاده کنید.

aug-setm

aug-setm base sub val

تغییر چندین گره Augeas در یک عملیات واحد. "base" عبارتی است که با چندین گره مطابقت دارد. "sub" یک عبارت مسیر نسبت به "base" است. تمام گره‌های منطبق با "base" یافت می‌شوند و سپس برای هر گره، "sub" به "val" تغییر می‌یابد. "sub" همچنین می‌تواند "NULL" باشد که در این صورت گره‌های "base" اصلاح می‌شوند.

این تابع تعداد گره‌های اصلاح‌شده را برمی‌گرداند.

aug-transform

aug-transform lens file [remove:true|false]

یک تبدیل Augeas برای "lens" مشخص‌شده اضافه می‌کند تا بتواند "file" را مدیریت کند.

اگر "remove" برابر true باشد (پیش‌فرض "false" است)، تبدیل حذف می‌شود.

این دستور دارای یک یا چند آرگومان اختیاری است. نگاه کنید به "OPTIONAL ARGUMENTS".

available

available 'groups ...'

این دستور برای بررسی در دسترس بودن برخی از گروه‌های عملکردی در ماشین مجازی استفاده می‌شود، که ممکن است همه ساخت‌های ماشین مجازی libguestfs قادر به ارائه آن‌ها نباشند.

گروه‌های libguestfs و توابع متناظر با آن‌ها در "AVAILABILITY" در guestfs(3) فهرست شده‌اند. همچنین می‌توانید این فهرست را در زمان اجرا با فراخوانی "available-all-groups" دریافت کنید.

آرگومان "groups" فهرستی از نام‌های گروه‌ها است، به عنوان مثال: "["inotify", "augeas"]" در دسترس بودن توابع inotify لینوکس و توابع Augeas (ویرایش فایل‌های پیکربندی) را بررسی می‌کند.

اگر همه گروه‌های درخواستی در دسترس باشند، این دستور هیچ خطایی برنمی‌گرداند.

اگر یک یا چند گروه از گروه‌های درخواستی در ماشین مجازی در دسترس نباشند، با خطا مواجه می‌شود.

اگر یک نام گروه نامعتبر یا ناشناخته در فهرست گروه‌ها گنجانده شود، همیشه خطا برگردانده می‌شود.

نکات:

• "feature-available" مشابه این فراخوانی است، اما با یک API کمی ساده‌تر: آن فراخوانی به جای ایجاد خطا، یک مقدار بولی true/false برمی‌گرداند.
• قبل از فراخوانی این تابع باید "launch" را فراخوانی کنید.

  دلیل این است که تا زمان اجرا شدن دیمون/ماشین مجازی و امکان استعلام از آن، نمی‌دانیم چه گروه‌هایی پشتیبانی می‌شوند.

• در دسترس بودن یک گروه از توابع لزوماً به این معنی نیست که آن‌ها حتماً کار خواهند کرد. حتی در صورت در دسترس بودن، همچنان باید هنگام فراخوانی تک‌تک توابع API خطاهای احتمالی را بررسی کنید.
• معمولاً وظیفه بسته‌سازهای توزیع است که قابلیت‌های کامل را در ماشین مجازی libguestfs بسازند. libguestfs بالادستی، در صورتی که با برآورده شدن همه نیازمندی‌ها از سورس کامپایل شود، از همه چیز پشتیبانی خواهد کرد.
• این فراخوانی در نسخه 1.0.80 اضافه شده است. در نسخه‌های قبلی libguestfs تنها کاری که می‌توانستید انجام دهید اجرای آزمایشی یک دستور بود تا متوجه شوید آیا دیمون آن را پیاده‌سازی کرده است یا خیر. همچنین نگاه کنید به "version".

همچنین نگاه کنید به "filesystem-available".

available-all-groups

available-all-groups

این دستور فهرستی از تمام گروه‌های اختیاری که این دیمون از آن‌ها آگاه است را برمی‌گرداند. توجه داشته باشید که این دستور هر دو گروه پشتیبانی‌شده و پشتیبانی‌نشده را بازمی‌گرداند. برای فهمیدن اینکه دیمون واقعاً از کدام‌یک پشتیبانی می‌کند، باید "available" / "feature-available" را روی هر یک از اعضای فهرست بازگردانده‌شده فراخوانی کنید.

همچنین نگاه کنید به "available"، "feature-available" و "AVAILABILITY" در guestfs(3).

base64-in

base64-in (base64file|-) filename

این دستور داده‌های کدگذاری‌شده با base64 را از "base64file" در filename بارگذاری می‌کند.

از "-" به جای نام فایل برای خواندن/نوشتن از stdin/stdout استفاده کنید.

base64-out

base64-out filename (base64file|-)

این دستور محتویات filename را دانلود کرده و آن را به صورت کدگذاری base64 در فایل محلی "base64file" می‌نویسد.

از "-" به جای نام فایل برای خواندن/نوشتن از stdin/stdout استفاده کنید.

blkdiscard

blkdiscard device

این دستور تمام بلوک‌های روی دستگاه بلوکی "device" را دور می‌ریزد (discard می‌کند) و فضای آزاد را به میزبان پس می‌دهد.

این عملیات نیازمند پشتیبانی در libguestfs، فایل‌سیستم میزبان، qemu و کرنل میزبان است. اگر این پشتیبانی وجود نداشته باشد ممکن است خطا دهد یا حتی به ظاهر اجرا شود اما کاری انجام ندهد. همچنین باید ویژگی "discard" را روی درایو زیرین تنظیم کنید (نگاه کنید به "add-drive-opts").

این دستور به ویژگی "blkdiscard" وابسته است. همچنین نگاه کنید به "feature-available".

blkdiscardzeroes

blkdiscardzeroes device

این فراخوانی اگر بلوک‌های روی "device" که با فراخوانی "blkdiscard" آزاد شده‌اند، در زمان خواندن بعدی به عنوان بلوک‌هایی از بایت‌های صفر برگردانده شوند، مقدار true برمی‌گرداند.

اگر مقدار false برگرداند، ممکن است بلوک‌های آزاد شده به عنوان داده‌های قدیمی یا تصادفی خوانده شوند.

این دستور به ویژگی "blkdiscardzeroes" وابسته است. همچنین نگاه کنید به "feature-available".

blkid

blkid device

این دستور ویژگی‌های دستگاه بلوکی را برای "device" برمی‌گرداند. فیلدهای زیر معمولاً در جدول هش بازگردانده شده وجود دارند. فیلدهای دیگر نیز ممکن است وجود داشته باشند.

"UUID"

شناسه uuid این دستگاه.

"LABEL"

برچسب این دستگاه.

"VERSION"

نسخه دستور blkid.

"TYPE"

نوع فایل‌سیستم یا RAID این دستگاه.

"USAGE"

کاربرد این دستگاه، به عنوان مثال "filesystem" یا "raid".

blockdev-flushbufs

blockdev-flushbufs device

این دستور به کرنل اعلام می‌کند بافرهای داخلی مرتبط با "device" را تخلیه (flush) کند.

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-getbsz

blockdev-getbsz device

این دستور اندازه بلوک یک دستگاه را برمی‌گرداند.

نکته: این مقدار هم با اندازه در قالب بلوک‌ها و هم با اندازه بلوک فایل‌سیستم متفاوت است. همچنین این تنظیم واقعاً توسط چیزی استفاده نمی‌شود. احتمالاً نباید از آن برای کاری استفاده کنید. فایل‌سیستم‌ها ایده خود را درباره انتخاب اندازه بلوک دارند.

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-getro

blockdev-getro device

یک مقدار بولی برمی‌گرداند که نشان می‌دهد آیا دستگاه بلوکی فقط‌خواندنی است یا خیر (true در صورت فقط‌خواندنی بودن، false در غیر این صورت).

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-getsize64

blockdev-getsize64 device

این دستور اندازه دستگاه را به بایت برمی‌گرداند.

همچنین نگاه کنید به "blockdev-getsz".

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-getss

blockdev-getss device

این دستور اندازه سکتورها را روی یک دستگاه بلوکی برمی‌گرداند. معمولاً 512 است، اما در دستگاه‌های مدرن می‌تواند بزرگ‌تر باشد.

(توجه داشته باشید که این مقدار تعداد سکتورها نیست، برای آن از "blockdev-getsz" استفاده کنید).

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-getsz

blockdev-getsz device

این دستور اندازه دستگاه را بر حسب واحدهای سکتورهای 512 بایتی برمی‌گرداند (حتی اگر اندازه سکتور 512 بایت نباشد ... عجیب است).

همچنین برای اندازه واقعی سکتور دستگاه به "blockdev-getss" و برای اندازه بر حسب بایت که کاربردی‌تر است به "blockdev-getsize64" مراجعه کنید.

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-rereadpt

blockdev-rereadpt device

جدول پارتیشن را روی "device" مجدداً می‌خواند.

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-setbsz

blockdev-setbsz device blocksize

این فراخوانی هیچ کاری انجام نمی‌دهد و به دلیل وجود یک باگ در blockdev هرگز کاری انجام نداده است. از آن استفاده نکنید.

اگر نیاز به تنظیم اندازه بلوک فایل‌سیستم دارید، از گزینه "blocksize" در "mkfs" استفاده کنید.

این تابع منسوخ شده است. هیچ جایگزینی ندارد. برای اطلاعات بیشتر به مستندات API در guestfs(3) مراجعه کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

blockdev-setra

blockdev-setra device sectors

تنظیم پیش‌خوانی یا readahead (بر حسب سکتورهای 512 بایتی) برای دستگاه.

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-setro

blockdev-setro device

دستگاه بلوکی با نام "device" را در حالت فقط‌خواندنی قرار می‌دهد.

این دستور از دستور blockdev(8) استفاده می‌کند.

blockdev-setrw

blockdev-setrw device

دستگاه بلوکی با نام "device" را در حالت خواندنی/نوشتنی قرار می‌دهد.

این دستور از دستور blockdev(8) استفاده می‌کند.

btrfs-balance-cancel

btrfs-balance-cancel path

لغو عملیات بالانس (balance) در حال اجرا روی یک فایل‌سیستم btrfs.

این دستور به ویژگی "btrfs" وابسته است. همچنین نگاه کنید به "feature-available".

btrfs-balance-pause

btrfs-balance-pause path

مکث در عملیات بالانس (balance) در حال اجرا روی یک فایل‌سیستم btrfs.

این دستور به ویژگی "btrfs" وابسته است. همچنین نگاه کنید به "feature-available".

btrfs-balance-resume

btrfs-balance-resume path

ادامه عملیات بالانس (balance) متوقف‌شده روی یک فایل‌سیستم btrfs.

این دستور به ویژگی "btrfs" وابسته است. همچنین نگاه کنید به "feature-available".

btrfs-balance-status

btrfs-balance-status path

نمایش وضعیت یک عملیات توازن (balance) در حال اجرا یا متوقف‌شده روی یک سیستم‌فایل btrfs.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-device-add

btrfs-device-add 'devices ...' fs

افزودن فهرست دستگاه(ها) در "devices" به سیستم‌فایل btrfs مونت‌شده در "fs". اگر "devices" یک فهرست خالی باشد، هیچ کاری انجام نمی‌شود.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-device-delete

btrfs-device-delete 'devices ...' fs

حذف "devices" از سیستم‌فایل btrfs مونت‌شده در "fs". اگر "devices" یک فهرست خالی باشد، هیچ کاری انجام نمی‌شود.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-filesystem-balance

btrfs-balance

btrfs-filesystem-balance fs

توازن (balance) تکه‌ها (chunks) در سیستم‌فایل btrfs مونت‌شده در "fs" در سراسر دستگاه‌های زیربنایی.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-filesystem-defragment

btrfs-filesystem-defragment path [flush:true|false] [compress:..]

یکپارچه‌سازی (defragment) یک فایل یا دایرکتوری روی سیستم‌فایل btrfs. مقدار compress یکی از zlib یا lzo است.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-filesystem-resize

btrfs-filesystem-resize mountpoint [size:N]

این دستور اندازه یک سیستم‌فایل btrfs را تغییر می‌دهد.

توجه داشته باشید که بر خلاف سایر فراخوانی‌های تغییر اندازه، سیستم‌فایل باید مونت شده باشد و پارامتر مربوطه نقطه مونت است نه دستگاه (این یکی از الزامات خود btrfs است).

پارامترهای اختیاری عبارتند از:

"size"

اندازه جدید (به بایت) سیستم‌فایل. در صورت حذف، اندازه سیستم‌فایل به حداکثر اندازه ممکن تغییر می‌یابد.

همچنین ببینید btrfs(8).

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-filesystem-show

btrfs-filesystem-show device

نمایش تمام دستگاه‌هایی که سیستم‌فایل‌های موجود در "device" روی آن‌ها گسترده شده‌اند.

اگر تمام دستگاه‌های مربوط به سیستم‌فایل‌ها موجود نباشند، این تابع شکست خورده و "errno" برابر با "ENODEV" تنظیم می‌شود.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-filesystem-sync

btrfs-filesystem-sync fs

اجبار به همگام‌سازی (sync) روی سیستم‌فایل btrfs مونت‌شده در "fs".

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-fsck

btrfs-fsck device [superblock:N] [repair:true|false]

برای بررسی یک سیستم‌فایل btrfs استفاده می‌شود، "device" فایل دستگاهی است که سیستم‌فایل روی آن ذخیره شده است.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "btrfs-scrub-full" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-image

btrfs-image 'source ...' image [compresslevel:N]

این دستور برای ایجاد یک ایمیج از یک سیستم‌فایل btrfs استفاده می‌شود. تمام داده‌ها صفر می‌شوند، اما متادیتا و موارد مشابه حفظ می‌گردند.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-qgroup-assign

btrfs-qgroup-assign src dst path

افزودن qgroup با نام "src" به qgroup والد "dst". این دستور می‌تواند چندین qgroup را در یک qgroup والد گروه‌بندی کند تا محدودیت مشترک به اشتراک گذاشته شود.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-qgroup-create

btrfs-qgroup-create qgroupid subvolume

ایجاد یک گروه سهمیه‌بندی (qgroup) برای زیرحجم در "subvolume".

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-qgroup-destroy

btrfs-qgroup-destroy qgroupid subvolume

حذف یک گروه سهمیه‌بندی (quota group).

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-qgroup-limit

btrfs-qgroup-limit subvolume size

محدود کردن اندازه زیرحجم با مسیر "subvolume".

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-qgroup-remove

btrfs-qgroup-remove src dst path

حذف qgroup با نام "src" از qgroup والد "dst".

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-qgroup-show

btrfs-qgroup-show path

نمایش تمام گروه‌های سهمیه‌بندی زیرحجم در یک سیستم‌فایل btrfs، شامل میزان استفاده آن‌ها.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-quota-enable

btrfs-quota-enable fs true|false

فعال یا غیرفعال کردن پشتیبانی از سهمیه‌بندی زیرحجم برای سیستم‌فایلی که شامل "path" است.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-quota-rescan

btrfs-quota-rescan fs

دور ریختن تمام اعداد qgroup و اسکن مجدد متادیتا با پیکربندی فعلی.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-replace

btrfs-replace srcdev targetdev mntpoint

جایگزینی دستگاه در یک سیستم‌فایل btrfs. روی یک سیستم‌فایل فعال، داده‌هایی که در حال حاضر روی دستگاه مبدأ ذخیره شده‌اند روی دستگاه مقصد کپی می‌شوند. پس از اتمام عملیات، دستگاه مبدأ پاکسازی شده و از سیستم‌فایل حذف می‌شود.

اندازه "targetdev" باید برابر یا بزرگ‌تر از "srcdev" باشد. دستگاه‌هایی که در حال حاضر مونت هستند هرگز مجاز نیستند به عنوان "targetdev" استفاده شوند.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-rescue-chunk-recover

btrfs-rescue-chunk-recover device

بازیابی درخت تکه‌ها (chunk tree) در سیستم‌فایل btrfs از طریق اسکن تک‌تک دستگاه‌ها.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-rescue-super-recover

btrfs-rescue-super-recover device

بازیابی سوپربلاک‌های خراب از روی نسخه‌های سالم.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-scrub-cancel

btrfs-scrub-cancel path

لغو یک عملیات اسکراب (scrub) در حال اجرا روی سیستم‌فایل btrfs.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-scrub-full

btrfs-scrub-full path [readonly:true|false]

اجرای یک اسکراب کامل روی سیستم‌فایل btrfs و انتظار برای پایان یافتن آن. اگر سیستم‌فایل دارای خطا باشد، این دستور یک خطا برمی‌گرداند.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-scrub-resume

btrfs-scrub-resume path

ادامه دادن یک اسکراب که پیش‌تر لغو یا متوقف شده بود روی سیستم‌فایل btrfs.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-scrub-start

btrfs-scrub-start path

تمام داده‌ها و متادیتاهای روی سیستم‌فایل را می‌خواند و از چکسام‌ها و نسخه‌های رونوشت ذخیره‌سازی RAID برای شناسایی و ترمیم داده‌های فاسد استفاده می‌کند.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-scrub-status

btrfs-scrub-status path

نمایش وضعیت اسکراب در حال اجرا یا پایان‌یافته روی سیستم‌فایل btrfs.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-set-seeding

btrfs-set-seeding device true|false

فعال یا غیرفعال کردن قابلیت سیدینگ (seeding) برای دستگاهی که شامل یک سیستم‌فایل btrfs است.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-subvolume-create

btrfs-subvolume-create-opts

btrfs-subvolume-create dest [qgroupid:..]

ایجاد یک زیرحجم (subvolume) در btrfs. آرگومان "dest" دایرکتوری مقصد و نام زیرحجم است که به صورت /path/to/dest/name مشخص می‌شود. پارامتر اختیاری "qgroupid" مشخص‌کننده qgroup است که زیرحجم تازه ایجاد شده به آن اضافه خواهد شد.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-subvolume-delete

btrfs-subvolume-delete subvolume

حذف زیرحجم یا اسنپ‌شات نام‌برده شده در btrfs.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-subvolume-get-default

btrfs-subvolume-get-default fs

دریافت زیرحجم یا اسنپ‌شات پیش‌فرض سیستم‌فایل مونت‌شده در "mountpoint".

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-subvolume-list

btrfs-subvolume-list fs

فهرست کردن اسنپ‌شات‌ها و زیرحجم‌های سیستم‌فایل btrfs که در "fs" مونت شده است.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-subvolume-set-default

btrfs-subvolume-set-default id fs

تنظیم زیرحجم سیستم‌فایل btrfs با نام "fs" که به صورت پیش‌فرض مونت خواهد شد. برای دریافت فهرست زیرحجم‌ها، "btrfs-subvolume-list" را ببینید.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-subvolume-show

btrfs-subvolume-show subvolume

بازگرداندن اطلاعات تفصیلی درباره زیرحجم.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfs-subvolume-snapshot

btrfs-subvolume-snapshot-opts

btrfs-subvolume-snapshot source dest [ro:true|false] [qgroupid:..]

ایجاد یک اسنپ‌شات از زیرحجم btrfs با نام "source". آرگومان "dest" دایرکتوری مقصد و نام اسنپ‌شات است که به صورت /path/to/dest/name مشخص می‌شود. به صورت پیش‌فرض اسنپ‌شات ایجاد شده قابل نوشتن است، اما اگر مقدار پارامتر اختیاری "ro" برابر true باشد، اسنپ‌شات فقط‌خواندنی ایجاد می‌شود. پارامتر اختیاری "qgroupid" مشخص‌کننده qgroup است که اسنپ‌شات ایجاد شده به آن افزوده خواهد شد.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfstune-enable-extended-inode-refs

btrfstune-enable-extended-inode-refs device

این دستور ارجاعات گسترش‌یافته inode (extended inode refs) را فعال می‌کند.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfstune-enable-skinny-metadata-extent-refs

btrfstune-enable-skinny-metadata-extent-refs device

این دستور ارجاعات اکستنت متادیتای لاغر (skinny metadata extent refs) را فعال می‌کند.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

btrfstune-seeding

btrfstune-seeding device true|false

فعال کردن قابلیت سیدینگ برای یک دستگاه btrfs؛ این کار سیستم‌فایل را فقط‌خواندنی می‌کند تا بتوانید از آن برای ساخت سایر سیستم‌فایل‌ها استفاده نمایید.

این دستور به قابلیت "btrfs" وابسته است. همچنین ببینید "feature-available".

c-pointer

c-pointer

در اتصالات زبان‌های غیر C، این دستور به شما امکان می‌دهد اشاره‌گر C زیربنایی به هندل (یعنی "h *") را بازیابی کنید. هدف از این کار این است که به سایر کتابخانه‌ها امکان تعامل با libguestfs داده شود.

canonical-device-name

canonical-device-name device

این تابع ابزاری هنگام نمایش نام دستگاه‌ها به کاربر مفید است. این دستور تعدادی از نام‌های غیرمعمول دستگاه‌ها را دریافت کرده و آن‌ها را در قالبی سازگار و یکدست برمی‌گرداند:

/dev/hdX

/dev/vdX

این موارد به عنوان /dev/sdX بازگردانده می‌شوند. توجه داشته باشید که این دستور برای نام‌های دستگاه و نام‌های پارتیشن کار می‌کند. این تقریباً معکوس الگوریتم شرح داده شده در "BLOCK DEVICE NAMING" در guestfs(3) است.

/dev/mapper/VG-LV

/dev/dm-N

با استفاده از "lvm-canonical-lv-name" به شکل /dev/VG/LV تبدیل می‌شوند.

سایر رشته‌ها بدون تغییر بازگردانده می‌شوند.

cap-get-file

cap-get-file path

این تابع قابلیت‌های لینوکس (capabilities) متصل به "path" را برمی‌گرداند. مجموعه قابلیت‌ها به صورت متنی بازگردانده می‌شود (ببینید cap_to_text(3)).

اگر هیچ قابلیتی به فایل متصل نباشد، یک رشته خالی برگردانده می‌شود.

این دستور به قابلیت "linuxcaps" وابسته است. همچنین ببینید "feature-available".

cap-set-file

cap-set-file path cap

این تابع قابلیت‌های لینوکس متصل به "path" را تنظیم می‌کند. مجموعه قابلیت‌های "cap" باید به صورت متنی ارسال شود (ببینید cap_from_text(3)).

این دستور به قابلیت "linuxcaps" وابسته است. همچنین ببینید "feature-available".

case-sensitive-path

case-sensitive-path path

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

این دستور یکی از ویژگی‌های خاص درایور لینوکسی ntfs-3g (و احتمالاً درایورهای دیگر) را مدیریت می‌کند؛ با وجود این‌که سیستم‌فایل زیربنایی به حروف حساس نیست، این درایور سیستم‌فایل را به صورت حساس به حروف به لینوکس صادر می‌کند.

یک پیامد این موضوع آن است که دایرکتوری‌های ویژه مانند C:\windows ممکن است بسته به جزئیات دقیق نحوه ایجاد آن‌ها به صورت /WINDOWS یا /windows (یا موارد دیگر) ظاهر شوند. در خود ویندوز این مسئله مشکلی ایجاد نمی‌کرد.

باگ است یا قابلیت؟ قضاوت با شماست. مدخل مربوطه در پرسش‌های متداول ntfs-3g را ببینید: https://github.com/tuxera/ntfs-3g/wiki/NTFS-3G-FAQ

دستور "case-sensitive-path" تلاش می‌کند حالت حروف صحیح هر عنصر در مسیر را پیدا کند. اگر کل مسیر یا دایرکتوری والد آن وجود داشته باشد، مسیر حل‌شده را برمی‌گرداند. اگر دایرکتوری والد وجود داشته باشد ولی کل مسیر وجود نداشته باشد، حالت حروف دایرکتوری والد به درستی حل شده و بقیه مسیر بدون تغییر پیوست می‌شود. برای مثال، اگر فایل "/Windows/System32/netkvm.sys" موجود باشد:

"case-sensitive-path" ("/windows/system32/netkvm.sys")

"Windows/System32/netkvm.sys"

"case-sensitive-path" ("/windows/system32/NoSuchFile")

"Windows/System32/NoSuchFile"

"case-sensitive-path" ("/windows/system33/netkvm.sys")

ERROR

نکته: به دلیل رفتار فوق، نمی‌توان از "case-sensitive-path" برای بررسی وجود یک فایل استفاده کرد.

نکته: این تابع نام درایوها، بک‌اسلش‌ها و موارد مشابه را مدیریت نمی‌کند.

همچنین ببینید "realpath".

cat

cat path

محتویات فایل با نام "path" را برمی‌گرداند.

از آنجا که در زبان C این تابع یک "char *" برمی‌گرداند، راهی برای تمایز بین نویسه "\0" در فایل و پایان رشته وجود ندارد. برای کار با فایل‌های باینری، از توابع "read-file" یا "download" استفاده کنید.

checksum

checksum csumtype path

این فراخوانی چکسام MD5، SHAx یا CRC مربوط به فایل با نام "path" را محاسبه می‌کند.

نوع چکسام برای محاسبه با پارامتر "csumtype" مشخص می‌شود که باید یکی از مقادیر زیر را داشته باشد:

"crc"

محاسبه چکسام افزونگی چرخه‌ای (CRC) مشخص‌شده توسط استاندارد POSIX برای دستور "cksum".

"gost"

"gost12"

محاسبه چکسام با استفاده از خلاصه پیام GOST R34.11-94 یا GOST R34.11-2012.

"md5"

محاسبه هش MD5 (با استفاده از برنامه md5sum(1)).

"sha1"

محاسبه هش SHA1 (با استفاده از برنامه sha1sum(1)).

"sha224"

محاسبه هش SHA224 (با استفاده از برنامه sha224sum(1)).

"sha256"

محاسبه هش SHA256 (با استفاده از برنامه sha256sum(1)).

"sha384"

محاسبه هش SHA384 (با استفاده از برنامه sha384sum(1)).

"sha512"

محاسبه هش SHA512 (با استفاده از برنامه sha512sum(1)).

چکسام به عنوان یک رشته قابل چاپ بازگردانده می‌شود.

برای دریافت چکسام یک دستگاه، از "checksum-device" استفاده کنید.

برای دریافت چکسام چندین فایل، از "checksums-out" استفاده کنید.

checksum-device

checksum-device csumtype device

این فراخوانی چکسام MD5، SHAx یا CRC مربوط به محتویات دستگاه با نام "device" را محاسبه می‌کند. برای مشاهده انواع چکسام‌های پشتیبانی‌شده، دستور "checksum" را ببینید.

checksums-out

checksums-out csumtype directory (sumsfile|-)

این دستور چکسام تمام فایل‌های معمولی موجود در directory را محاسبه کرده و سپس فهرستی از آن چکسام‌ها را در فایل خروجی محلی "sumsfile" منتشر می‌کند.

این دستور می‌تواند برای اعتبارسنجی یکپارچگی یک ماشین مجازی استفاده شود. با این حال برای امنیت مناسب باید به خروجی دستور چکسام دقت کنید (این دستور از ابزارهای GNU coreutils استفاده می‌کند). به ویژه زمانی که نام فایل غیرقابل چاپ باشد، coreutils از سینتکس ویژه بک‌اسلش استفاده می‌نماید. برای اطلاعات بیشتر، فایل info مربوط به GNU coreutils را ببینید.

به جای نام فایل از "-" برای خواندن/نوشتن از stdin/stdout استفاده کنید.

chmod

chmod mode path

تغییر حالت (مجوزهای دسترسی) "path" به "mode". فقط حالت‌های عددی پشتیبانی می‌شوند.

نکته: هنگام استفاده از این دستور از طریق guestfish، مقدار "mode" به صورت پیش‌فرض در مبنای ده (دسیمال) خواهد بود، مگر اینکه پیشوند 0 را برای مبنای هشت (اکتال) به آن اضافه کنید؛ یعنی از 0700 استفاده کنید نه 700.

حالت دسترسی که واقعاً اعمال می‌شود تحت تأثیر umask قرار دارد.

chown

chown owner group path

تغییر مالک فایل به "owner" و گروه به "group".

تنها uid و gid عددی پشتیبانی می‌شوند. اگر می‌خواهید از نام‌ها استفاده کنید، باید فایل پسورد را خودتان یافته و پردازش کنید (پشتیبانی از Augeas این کار را نسبتاً آسان می‌کند).

clear-backend-setting

clear-backend-setting name

اگر رشته‌ای از تنظیمات بک‌اند مطابق با "name" یا شروع‌شونده با "name=" وجود داشته باشد، آن رشته از تنظیمات بک‌اند حذف می‌شود.

این فراخوانی تعداد رشته‌های حذف‌شده را برمی‌گرداند (که ممکن است 0، 1 یا بیشتر از 1 باشد).

ببینید "BACKEND" در guestfs(3)، "BACKEND SETTINGS" در guestfs(3).

clevis-luks-unlock

clevis-luks-unlock device mapname

این دستور یک دستگاه بلوکی رمزنگاری‌شده بر اساس استاندارد Linux Unified Key Setup (LUKS) را با استفاده از رمزنگاری دیسک متصل به شبکه (NBDE) بازگشایی می‌کند.

"device" دستگاه بلوکی رمزنگاری‌شده است.

اپلاینس به سرورهای Tang ذکر شده در درخت پین‌های Clevis که به یک keyslot از هدر LUKS متصل است، متصل خواهد شد. درخت پین‌های Clevis ممکن است شامل پین‌های "sss" (افزونگی) به عنوان گره‌های داخلی (اختیاری) و پین‌های "tang" به عنوان برگ‌ها باشد. پین‌های "tpm2" پشتیبانی نمی‌شوند. اپلاینس با ترکیب پاسخ‌های سرورهای Tang با متادیتای هدر LUKS قفل دستگاه بلوکی را باز می‌کند؛ پارامتر "key" وجود ندارد.

اگر شبکه برای اپلاینس فعال نشده باشد، این دستور با شکست مواجه می‌شود. به "set-network" مراجعه کنید.

این دستور یک دستگاه بلوکی جدید به نام /dev/mapper/mapname ایجاد می‌کند. خواندن و نوشتن در این دستگاه بلوکی به ترتیب از روی "device" زیربنایی رمزگشایی و روی آن رمزنگاری می‌شود. دستگاه بلوکی رمزگشایی‌شده را با "cryptsetup-close" ببندید.

مقدار "mapname" نمی‌تواند "control" باشد زیرا این نام توسط device-mapper رزرو شده است.

اگر این دستگاه بلوکی شامل گروه‌های حجم LVM باشد، فراخوانی "lvm-scan" با پارامتر "activate" برابر با "true" آن‌ها را قابل مشاهده می‌کند.

از "list-dm-devices" برای فهرست کردن تمام دستگاه‌های device mapper استفاده کنید.

این دستور به قابلیت "clevisluks" وابسته است. همچنین ببینید "feature-available".

command

command 'arguments ...'

این فراخوانی یک دستور را از درون سیستم‌فایل مهمان اجرا می‌کند. سیستم‌فایل باید مونت شده باشد و شامل یک سیستم‌عامل سازگار باشد (یعنی لینوکس، با معماری پردازنده یکسان یا سازگار).

تنها پارامتر، فهرستی از آرگومان‌ها به سبک argv است. عنصر اول نام برنامه برای اجرا است. عناصر بعدی پارامترها هستند. فهرست نباید خالی باشد (یعنی باید حداقل شامل یک نام برنامه باشد). توجه داشته باشید که دستور مستقیماً اجرا می‌شود و از طریق پوسته (shell) فراخوانی نمی‌شود (ببینید "sh").

مقدار بازگشتی هر آن چیزی است که توسط دستور در stdout چاپ شده است.

اگر دستور با وضعیت خروج غیر صفر پایان یابد، این تابع یک پیام خطا برمی‌گرداند. رشته پیام خطا همان محتوای stderr حاصل از دستور است.

متغیر محیطی $PATH حداقل شامل /usr/bin و /bin خواهد بود. اگر به برنامه‌ای از مکان دیگری نیاز دارید، باید مسیر کامل را در پارامتر اول مشخص کنید.

کتابخانه‌های مشترک و فایل‌های داده مورد نیاز برنامه باید در سیستم‌فایل‌هایی که در مکان‌های صحیح مونت شده‌اند در دسترس باشند. این مسئولیت فراخواننده است که اطمینان حاصل کند تمام سیستم‌فایل‌های مورد نیاز در مکان‌های مناسب مونت شده‌اند.

به دلیل پروتکل پیام‌رسانی، محدودیت انتقال بین ۲ مگابایت و ۴ مگابایت وجود دارد. ببینید "PROTOCOL LIMITS" در guestfs(3).

command-lines

command-lines 'arguments ...'

این دستور همانند "command" است، اما نتیجه را به فهرستی از خطوط تقسیم می‌کند.

همچنین ببینید: "sh-lines"

به دلیل پروتکل پیام‌رسانی، محدودیت انتقال بین ۲ مگابایت و ۴ مگابایت وجود دارد. ببینید "PROTOCOL LIMITS" در guestfs(3).

command-out

command-out 'arguments ...' (output|-)

این دستور همانند "command" است، اما خروجی را به صورت جریانی (stream) برمی‌گرداند و مواردی را که خروجی دستور از محدودیت پروتکل بزرگ‌تر است مدیریت می‌کند.

همچنین ببینید: "sh-out"

به جای نام فایل از "-" برای خواندن/نوشتن از stdin/stdout استفاده کنید.

compress-device-out

compress-device-out ctype device (zdevice|-) [level:N]

این دستور "device" را فشرده کرده و در فایل محلی "zdevice" می‌نویسد.

پارامتر "ctype" و پارامتر اختیاری "level" همان معنای موجود در "compress-out" را دارند.

به جای نام فایل از "-" برای خواندن/نوشتن از stdin/stdout استفاده کنید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

compress-out

compress-out ctype file (zfile|-) [level:N]

این دستور file را فشرده کرده و در فایل محلی zfile می‌نویسد.

برنامه فشرده‌سازی استفاده‌شده توسط پارامتر "ctype" کنترل می‌شود. در حال حاضر این مقادیر شامل موارد زیر است: "compress", "gzip", "bzip2", "xz" یا "lzop". برخی از انواع فشرده‌سازی ممکن است در ساخت‌های خاصی از libguestfs پشتیبانی نشوند، که در این صورت خطایی شامل زیررشته "not supported" دریافت خواهید کرد.

پارامتر اختیاری "level" سطح فشرده‌سازی را کنترل می‌کند. معنی و مقدار پیش‌فرض این پارامتر به برنامه فشرده‌سازی در حال استفاده بستگی دارد.

به جای نام فایل از "-" برای خواندن/نوشتن از stdin/stdout استفاده کنید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

config

config hvparam hvvalue

این دستور می‌تواند برای افزودن پارامترهای دلخواه هایپروایزر به فرم -param value استفاده شود. البته کاملاً دلخواه نیست - ما از تنظیم برخی پارامترها که با پارامترهای مورد استفاده ما تداخل دارند جلوگیری می‌کنیم.

کاراکتر اول رشته "hvparam" باید یک "-" (خط تیره) باشد.

مقدار "hvvalue" می‌تواند NULL باشد.

copy-attributes

copy-attributes src dest [all:true|false] [mode:true|false] [xattributes:true|false] [ownership:true|false]

کپی کردن ویژگی‌های یک مسیر (که می‌تواند فایل یا دایرکتوری باشد) به یک مسیر دیگر.

به صورت پیش‌فرض هیچ ویژگی کپی نمی‌شود، بنابراین مطمئن شوید که مورد نظر را مشخص کرده‌اید (یا "all" را برای کپی همه چیز تنظیم کنید).

آرگومان‌های اختیاری تعیین می‌کنند که چه ویژگی‌هایی کپی شوند:

"mode"

کپی بخشی از حالت فایل از "source" به "destination". فقط مجوزهای یونیکس و بیت‌های sticky/setuid/setgid قابل کپی هستند.

"xattributes"

کپی ویژگی‌های گسترش‌یافته لینوکس (xattrs) از "source" به "destination". اگر قابلیت linuxxattrs در دسترس نباشد این فلگ هیچ کاری انجام نمی‌دهد (ببینید "feature-available").

"ownership"

کپی مالک uid و گروه gid از "source" به "destination".

"all"

کپی تمام ویژگی‌ها از "source" به "destination". فعال کردن آن سایر فلگ‌ها را در صورت مشخص نشدن فعال می‌کند.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

copy-device-to-device

copy-device-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]

چهار فراخوانی "copy-device-to-device", "copy-device-to-file", "copy-file-to-device", و "copy-file-to-file" به شما امکان می‌دهند از یک مبدأ (دستگاه|فایل) به یک مقصد (دستگاه|فایل) کپی کنید.

کپی‌های جزئی را می‌توان انجام داد زیرا می‌توانید به دلخواه آفست مبدأ، آفست مقصد و اندازه برای کپی را مشخص کنید. این مقادیر همگی به بایت تعیین می‌شوند. در صورت مشخص نشدن، هر دو آفست به صورت پیش‌فرض صفر هستند و اندازه به طور پیش‌فرض تا جای ممکن تا رسیدن به انتهای مبدأ کپی می‌کند.

مبدأ و مقصد می‌توانند شیء یکسانی باشند. با این حال نواحی هم‌پوشان ممکن است به درستی کپی نشوند.

اگر مقصد یک فایل باشد، در صورت نیاز ایجاد می‌شود. اگر فایل مقصد به اندازه کافی بزرگ نباشد، گسترش داده می‌شود.

اگر مقصد یک فایل باشد و فلگ "append" تنظیم نشده باشد، فایل مقصد کوتاه (truncate) می‌شود. اگر فلگ "append" تنظیم شده باشد، عملیات کپی به انتهای فایل مقصد پیوست می‌شود. فلگ "append" در حال حاضر نمی‌تواند برای دستگاه‌ها تنظیم شود.

اگر فلگ "sparse" برابر true باشد، فراخوانی از نوشتن بلوک‌هایی که فقط شامل صفر هستند خودداری می‌کند که در برخی شرایط که دیسک پشتیبان دارای تخصیص پویا (thin-provisioned) است می‌تواند مفید باشد. توجه داشته باشید مگر اینکه مقصد از قبل صفر شده باشد، استفاده از این گزینه منجر به کپی نادرست خواهد شد.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

copy-device-to-file

copy-device-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]

برای بررسی کلی این فراخوانی، "copy-device-to-device" را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

copy-file-to-device

copy-file-to-device src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]

برای بررسی کلی این فراخوانی، "copy-device-to-device" را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

copy-file-to-file

copy-file-to-file src dest [srcoffset:N] [destoffset:N] [size:N] [sparse:true|false] [append:true|false]

برای بررسی کلی این فراخوانی، "copy-device-to-device" را ببینید.

این تابع، تابعی نیست که برای کپی فایل‌ها بخواهید. این تابع برای کپی بلوک‌ها درون فایل‌های موجود است. برای توابع عمومی کپی و انتقال فایل به "cp", "cp-a" و "mv" مراجعه کنید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

copy-size

copy-size src dest size

این دستور دقیقاً "size" بایت را از یک دستگاه یا فایل مبدأ "src" به دستگاه یا فایل مقصد دیگری به نام "dest" کپی می‌کند.

توجه داشته باشید اگر مبدأ خیلی کوتاه باشد یا مقصد به اندازه کافی بزرگ نباشد، این عملیات با شکست مواجه خواهد شد.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "copy-device-to-device" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

cp

cp src dest

این دستور فایلی را از "src" به "dest" کپی می‌کند که در آن "dest" یا نام فایل مقصد است یا دایرکتوری مقصد.

cp-a

cp-a src dest

این دستور یک فایل یا دایرکتوری را از "src" به "dest" به صورت بازگشتی با استفاده از دستور "cp -a" کپی می‌کند.

cp-r

cp-r src dest

این دستور یک فایل یا دایرکتوری را از "src" به "dest" به صورت بازگشتی با استفاده از دستور "cp -rP" کپی می‌کند.

بیشتر کاربران باید به جای آن از "cp-a" استفاده کنند. این دستور زمانی مفید است که نمی‌خواهید مجوزها حفظ شوند، زیرا سیستم‌فایل مقصد از آن پشتیبانی نمی‌کند (عمدتاً هنگام نوشتن روی سیستم‌فایل‌های DOS FAT).

cpio-out

cpio-out directory (cpiofile|-) [format:..]

این دستور محتویات directory را بسته‌بندی کرده و آن را در فایل محلی "cpiofile" دانلود می‌کند.

پارامتر اختیاری "format" می‌تواند برای انتخاب قالب استفاده شود. در حال حاضر تنها قالب‌های زیر مجاز هستند:

"newc"

قالب قابل حمل جدید (SVR4). این قالب تصادفاً با قالب cpio-گونه مورد استفاده هسته لینوکس برای initramfs سازگار است.

این قالب پیش‌فرض است.

"crc"

قالب قابل حمل جدید (SVR4) همراه با چکسام.

به جای نام فایل از "-" برای خواندن/نوشتن از stdin/stdout استفاده کنید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

cryptsetup-close

cryptsetup-close device

این دستور دستگاه رمزگذاری‌شده‌ای را که پیش‌تر توسط "cryptsetup-open" ایجاد شده است، می‌بندد. پارامتر "device" باید نام دستگاه نگاشت (یعنی /dev/mapper/mapname) باشد و نه نام دستگاه بلوکی زیرین.

این دستور به ویژگی "luks" وابسته است. همچنین "feature-available" را ببینید.

cryptsetup-open

cryptsetup-open device mapname [readonly:true|false] [crypttype:..] [cipher:..]

این دستور یک دستگاه بلوکی را باز می‌کند که طبق استاندارد Linux Unified Key Setup (LUKS)، Windows BitLocker، یا برخی انواع دیگر رمزگذاری شده است.

"device" دستگاه یا پارتیشن بلوکی رمزگذاری‌شده است.

فراخواننده باید یکی از کلیدهای مرتبط با دستگاه بلوکی رمزگذاری‌شده را در پارامتر "key" ارائه دهد.

این کار یک دستگاه بلوکی جدید به نام /dev/mapper/mapname ایجاد می‌کند. خواندن و نوشتن در این دستگاه بلوکی به‌ترتیب از و به "device" زیرین رمزگشایی و رمزگذاری می‌شود.

"mapname" نمی‌تواند "control" باشد زیرا این نام توسط device-mapper رزرو شده است.

اگر پارامتر اختیاری "crypttype" ارائه نشود، libguestfs تلاش می‌کند نوع صحیح را حدس بزند (برای مثال LUKS یا BitLocker). با این حال می‌توانید با مشخص کردن یکی از انواع زیر آن را لغو کنید:

"luks"

یک دستگاه لینوکسی LUKS.

"bitlk"

یک دستگاه Windows BitLocker.

پرچم اختیاری "readonly" اگر روی true تنظیم شود، یک نگاشت فقط‌خواندنی ایجاد می‌کند.

پارامتر اختیاری "cipher" امکان تعیین الگوریتم رمزنگاری (cipher) مورد استفاده را فراهم می‌کند.

اگر این دستگاه بلوکی حاوی گروه‌های حجم LVM باشد، فراخوانی "lvm-scan" با پارامتر "activate" برابر با "true" آن‌ها را قابل مشاهده می‌کند.

برای فهرست کردن تمام دستگاه‌های device mapper از "list-dm-devices" استفاده کنید.

این دستور دارای یک یا چند پارامتر کلید یا عبارت عبور است. Guestfish این موارد را جداگانه درخواست می‌کند.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به ویژگی "luks" وابسته است. همچنین "feature-available" را ببینید.

dd

dd src dest

این دستور از یک دستگاه یا فایل منبع "src" در یک دستگاه یا فایل مقصد دیگر "dest" کپی می‌کند. معمولاً از این برای کپی کردن به یا از یک دستگاه یا پارتیشن استفاده می‌کنید، برای مثال برای کپی کردن یک فایل‌سیستم.

اگر مقصد یک دستگاه باشد، باید به‌اندازه فایل یا دستگاه منبع یا بزرگ‌تر از آن باشد، در غیر این صورت عملیات کپی با شکست مواجه می‌شود. این دستور نمی‌تواند کپی‌های جزئی انجام دهد ("copy-device-to-device" را ببینید).

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "copy-device-to-device" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

device-index

device-index device

این تابع نام یک دستگاه (مثلاً "/dev/sdb") را دریافت کرده و شاخص آن دستگاه را در فهرست دستگاه‌ها برمی‌گرداند.

شماره‌های شاخص از 0 شروع می‌شوند. دستگاه نام‌برده باید وجود داشته باشد، برای مثال به‌عنوان رشته‌ای که از "list-devices" برگردانده شده است.

همچنین "list-devices"، "part-to-dev" و "device-name" را ببینید.

device-name

device-name index

این تابع شاخص یک دستگاه را دریافت کرده و نام دستگاه را برمی‌گرداند. برای مثال شاخص 0 رشته "/dev/sda" را برمی‌گرداند.

شاخص درایو باید قبلاً به هندل اضافه شده باشد.

همچنین "list-devices"، "part-to-dev" و "device-index" را ببینید.

df

df

این دستور برای گزارش فضای دیسک استفاده‌شده، دستور df(1) را اجرا می‌کند.

این دستور بیشتر برای نشست‌های تعاملی مفید است. قرار نیست رشته خروجی را در برنامه‌ها تجزیه کنید. از برنامه‌ها از "statvfs" استفاده کنید.

df-h

df-h

این دستور برای گزارش فضای دیسک استفاده‌شده با فرمت خوانا برای انسان، دستور "df -h" را اجرا می‌کند.

این دستور بیشتر برای نشست‌های تعاملی مفید است. قرار نیست رشته خروجی را در برنامه‌ها تجزیه کنید. از برنامه‌ها از "statvfs" استفاده کنید.

disk-create

disk-create filename format size [backingfile:..] [backingformat:..] [preallocation:..] [compat:..] [clustersize:N]

یک تصویر دیسک خالی به نام filename (یک فایل روی میزبان) با فرمت "format" (معمولاً "raw" یا "qcow2") ایجاد می‌کند. اندازه آن "size" بایت است.

اگر با پارامتر اختیاری "backingfile" استفاده شود، یک اسنپ‌شات روی فایل پشتیبان (backing file) ایجاد می‌شود. در این حالت، "size" باید به‌صورت -1 ارسال شود. اندازه اسنپ‌شات همان اندازه فایل پشتیبان است که به‌طور خودکار شناسایی می‌شود. توصیه می‌شود برای توصیف فرمت "backingfile"، پارامتر "backingformat" را نیز ارسال کنید.

اگر filename به یک دستگاه بلوکی اشاره کند، آن دستگاه فرمت می‌شود. مقدار "size" نادیده گرفته می‌شود زیرا دستگاه‌های بلوکی دارای اندازه ذاتی هستند.

سایر پارامترهای اختیاری عبارتند از:

"preallocation"

اگر فرمت "raw" باشد، این می‌تواند "off" (یا "sparse") یا "full" باشد تا به‌ترتیب یک فایل پراکنده (sparse) یا کاملاً تخصیص‌یافته ایجاد شود. مقدار پیش‌فرض "off" است.

اگر فرمت "qcow2" باشد، این مقدار می‌تواند "off" (یا "sparse")، "metadata" یا "full" باشد. پیش‌تخصیص متادیتا هنگام انجام نوشتن‌های فراوان می‌تواند سریع‌تر باشد، اما فضای بیشتری مصرف می‌کند. مقدار پیش‌فرض "off" است.

"compat"

فقط برای "qcow2": رشته 1.1 را ارسال کنید تا از فرمت پیشرفته qcow2 پشتیبانی‌شده در qemu ≥ 1.1 استفاده شود.

"clustersize"

فقط برای "qcow2": تغییر اندازه کلاستر qcow2. مقدار پیش‌فرض 65536 (بایت) است و این تنظیم می‌تواند هر توانی از دو بین 512 و 2097152 باشد.

توجه داشته باشید که این فراخوانی دیسک جدید را به هندل اضافه نمی‌کند. ممکن است لازم باشد "add-drive-opts" را جداگانه فراخوانی کنید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

disk-format

disk-format filename

فرمت تصویر دیسک به نام filename را شناسایی کرده و برمی‌گرداند. filename می‌تواند یک دستگاه میزبان و غیره نیز باشد. اگر فرمت تصویر قابل شناسایی نباشد، مقدار "unknown" برگردانده می‌شود.

توجه داشته باشید که تشخیص فرمت دیسک در برخی شرایط ممکن است ناامن باشد. بخش "CVE-2010-3851" در guestfs(3) را ببینید.

همچنین ببینید: "DISK IMAGE FORMATS" در guestfs(3)

disk-has-backing-file

disk-has-backing-file filename

بررسی و بازگرداندن اینکه آیا تصویر دیسک filename دارای فایل پشتیبان (backing file) است یا خیر.

توجه داشته باشید که تشخیص ویژگی‌های دیسک در برخی شرایط ممکن است ناامن باشد. بخش "CVE-2010-3851" در guestfs(3) را ببینید.

disk-virtual-size

disk-virtual-size filename

اندازه مجازی تصویر دیسک به نام filename را به بایت شناسایی کرده و برمی‌گرداند.

توجه داشته باشید که تشخیص ویژگی‌های دیسک در برخی شرایط ممکن است ناامن باشد. بخش "CVE-2010-3851" در guestfs(3) را ببینید.

dmesg

dmesg

پیام‌های هسته (خروجی dmesg(1)) را از هسته مهمان برمی‌گرداند. این مورد گاهی برای عیب‌یابی پیشرفته مشکلات مفید است.

روش دیگر برای دریافت همین اطلاعات، فعال کردن پیام‌های پرجزئیات با "set-verbose" یا تنظیم متغیر محیطی "LIBGUESTFS_DEBUG=1" پیش از اجرای برنامه است.

download

download remotefilename (filename|-)

فایل remotefilename را دانلود کرده و آن را به‌عنوان filename روی ماشین محلی ذخیره می‌کند.

filename می‌تواند یک لوله نام‌گذاری‌شده (named pipe) نیز باشد.

همچنین "upload" و "cat" را ببینید.

برای خواندن/نوشتن از stdin/stdout از "-" به‌جای نام فایل استفاده کنید.

download-blocks

download-blocks device start stop (filename|-) [unallocated:true|false]

واحدهای داده را از آدرس start تا stop از پارتیشن دیسک (مثلاً /dev/sda1) دانلود کرده و آن‌ها را به‌عنوان filename روی ماشین محلی ذخیره می‌کند.

استفاده از این API روی فرمت‌های تصاویر دیسک پراکنده مانند QCOW، ممکن است منجر به دانلود فایل‌های حجیم پر از صفر روی میزبان شود.

اندازه یک واحد داده در پیاده‌سازی‌های مختلف فایل‌سیستم متفاوت است. در فایل‌سیستم‌های NTFS واحدهای داده کلاستر (cluster) نامیده می‌شوند در حالی که در فایل‌سیستم‌های ExtX فرگمنت (fragment) نام دارند.

اگر پرچم اختیاری "unallocated" برابر با true باشد (پیش‌فرض false است)، فقط بلوک‌های تخصیص‌نیافته استخراج می‌شوند. این برای شناسایی داده‌های پنهان یا بازیابی فایل‌های حذف‌شده‌ای که واحدهای داده آن‌ها هنوز رونویسی نشده‌اند، مفید است.

برای خواندن/نوشتن از stdin/stdout از "-" به‌جای نام فایل استفاده کنید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به ویژگی "sleuthkit" وابسته است. همچنین "feature-available" را ببینید.

download-inode

download-inode device inode (filename|-)

یک فایل را با توجه به اینود (inode) آن از پارتیشن دیسک (مثلاً /dev/sda1) دانلود کرده و آن را به‌عنوان filename روی ماشین محلی ذخیره می‌کند.

برای اجرای این دستور نیازی به مانت کردن دیسک نیست.

این دستور قادر به دانلود فایل‌های حذف‌شده یا غیرقابل دسترس است.

برای خواندن/نوشتن از stdin/stdout از "-" به‌جای نام فایل استفاده کنید.

این دستور به ویژگی "sleuthkit" وابسته است. همچنین "feature-available" را ببینید.

download-offset

download-offset remotefilename (filename|-) offset size

فایل remotefilename را دانلود کرده و آن را به‌عنوان filename روی ماشین محلی ذخیره می‌کند.

فایل remotefilename به میزان "size" بایت با شروع از "offset" خوانده می‌شود (این ناحیه باید داخل فایل یا دستگاه قرار داشته باشد).

توجه داشته باشید که برخلاف "pread"، هیچ محدودیتی در مقدار داده‌ای که می‌تواند با این فراخوانی دانلود شود وجود ندارد و این فراخوانی همیشه مقدار کامل را می‌خواند مگر اینکه خطایی رخ دهد.

همچنین "download" و "pread" را ببینید.

برای خواندن/نوشتن از stdin/stdout از "-" به‌جای نام فایل استفاده کنید.

drop-caches

drop-caches whattodrop

این دستور به هسته مهمان دستور می‌دهد که حافظه نهان صفحات (page cache) و/یا حافظه نهان dentryها و اینودها را پاک کند. پارامتر "whattodrop" دقیقاً به هسته می‌گوید چه چیزی را پاک کند، ببینید https://linux-mm.org/Drop_Caches

تنظیم "whattodrop" بر روی 3 باید همه‌چیز را پاک کند.

این دستور به‌طور خودکار پیش از عملیات تابع sync(2) را فراخوانی می‌کند تا بیشترین مقدار حافظه مهمان آزاد شود.

du

du path

این دستور برای تخمین میزان فضای استفاده‌شده فایل در "path"، دستور "du -s" را اجرا می‌کند.

"path" می‌تواند یک فایل یا یک دایرکتوری باشد. اگر "path" یک دایرکتوری باشد، تخمین شامل محتویات دایرکتوری و تمام زیردایرکتوری‌ها (به‌صورت بازگشتی) می‌شود.

نتیجه، اندازه تخمینی به کیلوبایت (یعنی مضاربی از ۱۰۲۴ بایت) است.

e2fsck

e2fsck device [correct:true|false] [forceall:true|false] [forceno:true|false]

بررسی‌کننده فایل‌سیستم ext2/ext3 را روی "device" اجرا می‌کند. این دستور می‌تواند آرگومان‌های اختیاری زیر را دریافت کند:

"correct"

تعمیر خودکار فایل‌سیستم. این گزینه باعث می‌شود e2fsck هرگونه مشکل فایل‌سیستم را که بتوان بدون دخالت انسان به‌صورت ایمن برطرف کرد، خودکار اصلاح کند.

این گزینه نمی‌تواند هم‌زمان با گزینه‌های "forceall" یا "forceno" مشخص شود.

"forceall"

فرض پاسخ «بله» به تمام پرسش‌ها؛ امکان استفاده از e2fsck را به‌صورت غیرتعاملی فراهم می‌کند.

این گزینه نمی‌تواند هم‌زمان با گزینه‌های "correct" یا "forceno" مشخص شود.

"forceno"

باز کردن فایل‌سیستم به‌صورت فقط‌خواندنی و فرض پاسخ «خیر» به تمام پرسش‌ها؛ امکان استفاده از e2fsck را به‌صورت غیرتعاملی فراهم می‌کند.

این گزینه نمی‌تواند هم‌زمان با گزینه‌های "correct" یا "forceall" مشخص شود.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

e2fsck-f

e2fsck-f device

دستور "e2fsck -p -f device"; را اجرا می‌کند، یعنی بررسی‌کننده فایل‌سیستم ext2/ext3 را روی "device" به‌صورت غیرتعاملی (-p) اجرا می‌کند، حتی اگر فایل‌سیستم سالم به نظر برسد (-f).

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "e2fsck" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

echo-daemon

echo-daemon 'words ...'

این دستور فهرست "words" ارسال‌شده را با قرار دادن یک فاصله میان آن‌ها ادغام کرده و رشته حاصل را برمی‌گرداند.

می‌توانید از این دستور برای آزمایش اتصال به دیمن استفاده کنید.

همچنین "ping-daemon" را ببینید.

egrep

egrep regex path

برنامه خارجی egrep(1) را فراخوانی کرده و خطوط منطبق را برمی‌گرداند.

به‌دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. بخش "PROTOCOL LIMITS" در guestfs(3) را ببینید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "grep" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

egrepi

egrepi regex path

برنامه خارجی "egrep -i" را فراخوانی کرده و خطوط منطبق را برمی‌گرداند.

به‌دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. بخش "PROTOCOL LIMITS" در guestfs(3) را ببینید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "grep" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

equal

equal file1 file2

دو فایل file1 و file2 را مقایسه می‌کند و اگر محتوای آن‌ها کاملاً برابر باشد مقدار true و در غیر این صورت false برمی‌گرداند.

برای مقایسه از برنامه خارجی cmp(1) استفاده می‌شود.

exists

exists path

اگر و تنها اگر یک فایل، دایرکتوری (یا هر چیز دیگری) با نام "path" داده‌شده وجود داشته باشد، مقدار "true" را برمی‌گرداند.

همچنین "is-file"، "is-dir" و "stat" را ببینید.

extlinux

extlinux directory

بوت‌لودر SYSLINUX را روی دستگاه مانت‌شده در directory نصب می‌کند. برخلاف "syslinux" که نیازمند یک فایل‌سیستم FAT است، این دستور می‌تواند روی فایل‌سیستم‌های ext2/3/4 یا btrfs استفاده شود.

پارامتر directory می‌تواند یک نقطه مانت، یا یک دایرکتوری درون نقطه مانت باشد.

همچنین باید پارتیشن را به‌عنوان «فعال» ("part-set-bootable") علامت‌گذاری کنید و یک Master Boot Record (مثلاً با استفاده از "pwrite-device") روی اولین سکتور کل دیسک نصب شده باشد. بسته SYSLINUX همراه با چند Master Boot Record مناسب ارائه می‌شود. برای اطلاعات بیشتر صفحه راهنمای extlinux(1) را ببینید.

پیکربندی اضافی را می‌توان با قرار دادن فایلی به نام extlinux.conf روی فایل‌سیستم در مسیر directory به SYSLINUX ارائه داد. برای اطلاعات بیشتر در مورد محتوای این فایل، extlinux(1) را ببینید.

همچنین "syslinux" را ببینید.

این دستور به ویژگی "extlinux" وابسته است. همچنین "feature-available" را ببینید.

f2fs-expand

f2fs-expand device

این دستور یک فایل‌سیستم f2fs را گسترش می‌دهد تا با اندازه دستگاه زیرین مطابقت پیدا کند.

این دستور به ویژگی "f2fs" وابسته است. همچنین "feature-available" را ببینید.

fallocate

fallocate path len

این دستور فایلی (حاوی بایت‌های صفر) به نام "path" و با اندازه "len" بایت پیش‌تخصیص می‌دهد. اگر فایل از قبل وجود داشته باشد، رونویسی می‌شود.

این دستور را با دستور مخصوص guestfish یعنی "alloc" که فایلی را در میزبان تخصیص داده و آن را به‌عنوان دستگاه متصل می‌کند اشتباه نگیرید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "fallocate64" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

fallocate64

fallocate64 path len

این دستور فایلی (حاوی بایت‌های صفر) به نام "path" و با اندازه "len" بایت پیش‌تخصیص می‌دهد. اگر فایل از قبل وجود داشته باشد، رونویسی می‌شود.

توجه داشته باشید که این فراخوانی بلوک‌های دیسک را برای فایل تخصیص می‌دهد. برای ایجاد یک فایل پراکنده (sparse) به‌جای آن از "truncate-size" استفاده کنید.

فراخوانی منسوخ‌شده "fallocate" همین کار را انجام می‌دهد، اما به‌دلیل یک اشتباه سهوی، تنها اجازه می‌داد طول‌های ۳۰ بیتی مشخص شوند و حداکثر اندازه فایل‌های ایجادشده از طریق آن فراخوانی را به ۱ گیگابایت محدود می‌کرد.

این دستور را با دستورهای مخصوص guestfish یعنی "alloc" و "sparse" که فایلی را در میزبان ایجاد کرده و آن را به‌عنوان دستگاه متصل می‌کنند اشتباه نگیرید.

feature-available

feature-available 'groups ...'

این دستور همانند "available" است، اما برخلاف آن فراخوانی که در صورت پیدا نشدن ویژگی استثنا پرتاب می‌کند، یک نتیجه بولی ساده true/false برمی‌گرداند. برای مستندات دیگر "available" را ببینید.

fgrep

fgrep pattern path

برنامه خارجی fgrep(1) را فراخوانی کرده و خطوط منطبق را برمی‌گرداند.

به‌دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. بخش "PROTOCOL LIMITS" در guestfs(3) را ببینید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "grep" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

fgrepi

fgrepi pattern path

برنامه خارجی "fgrep -i" را فراخوانی کرده و خطوط منطبق را برمی‌گرداند.

به‌دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. بخش "PROTOCOL LIMITS" در guestfs(3) را ببینید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "grep" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

file

file path

این فراخوانی از دستور استاندارد file(1) برای تعیین نوع یا محتوای فایل استفاده می‌کند.

این فراخوانی همچنین به‌صورت شفاف درون انواع مختلف فایل‌های فشرده‌شده را بررسی می‌کند.

نام فایل در ابتدای خروجی اضافه نمی‌شود (مانند گزینه -b در دستور file).

خروجی به خروجی دستور زیرین file(1) بستگی دارد و ممکن است در آینده به‌گونه‌ای تغییر کند که خارج از کنترل ما باشد. به عبارت دیگر، خروجی توسط ABI تضمین نمی‌شود.

همچنین ببینید: file(1)، "vfs-type"، "lstat"، "is-file"، "is-blockdev" (و غیره)، "is-zero".

file-architecture

file-architecture filename

معماری فایل باینری filename را شناسایی کرده و در صورت شناخته شدن برمی‌گرداند.

معماری‌های تعریف‌شده فعلی عبارتند از:

"aarch64"

معماری ۶۴ بیتی ARM.

"arm"

معماری ۳۲ بیتی ARM.

"i386"

این رشته برای تمام باینری‌های ۳۲ بیتی i386، i486، i586 و i686 صرف‌نظر از نیازمندی‌های دقیق پردازنده باینری بازگردانده می‌شود.

"ia64"

اینتل ایتانیوم (Intel Itanium).

"ppc"

معماری ۳۲ بیتی Power PC.

"ppc64"

معماری ۶۴ بیتی Power PC (بزرگ‌پایان / big endian).

"ppc64le"

معماری ۶۴ بیتی Power PC (کوچک‌پایان / little endian).

"loongarch64"

معماری ۶۴ بیتی LoongArch64 (کوچک‌پایان / little endian).

"riscv32"

"riscv64"

"riscv128"

گونه‌های ۳۲، ۶۴ یا ۱۲۸ بیتی RISC-V.

"s390"

معماری ۳۱ بیتی IBM S/390.

"s390x"

معماری ۶۴ بیتی IBM S/390.

"sparc"

معماری ۳۲ بیتی SPARC.

"sparc64"

معماری ۶۴ بیتی SPARC V9 و بالاتر.

"x86_64"

معماری ۶۴ بیتی x86-64.

ممکن است Libguestfs در آینده رشته‌های معماری دیگری را برگرداند.

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

• بسیاری از انواع باینری‌های یونیکس و لینوکس
• بسیاری از انواع کتابخانه‌های اشتراکی یونیکس و لینوکس
• باینری‌های Win32 و Win64 ویندوز
• فایل‌های DLL ویندوز Win32 و Win64

  باینری‌ها و DLLهای Win32 مقدار "i386" را برمی‌گردانند.

  باینری‌ها و DLLهای Win64 مقدار "x86_64" را برمی‌گردانند.

• ماژول‌های هسته لینوکس
• تصاویر initrd سبک جدید لینوکس
• برخی هسته‌های vmlinuz لینوکس غیر x86

کارهایی که در حال حاضر نمی‌تواند انجام دهد:

• کتابخانه‌های ایستا (libfoo.a)
• تصاویر initrd سبک قدیمی لینوکس به‌عنوان فایل‌سیستم فشرده ext2 (در RHEL 3)
• هسته‌های vmlinuz لینوکس x86

  تصاویر vmlinuz در x86 (فرمت bzImage) از ترکیبی از کدهای ۱۶ بیتی، ۳۲ بیتی و فشرده تشکیل شده‌اند و باز کردن آن‌ها بسیار دشوار است. اگر می‌خواهید معماری یک هسته را بیابید، به‌جای آن از معماری initrd یا ماژول(های) هسته مرتبط استفاده کنید.

filesize

filesize file

این دستور اندازه file را به بایت برمی‌گرداند.

برای دریافت سایر مشخصات درباره یک فایل از "stat"، "lstat"، "is-dir"، "is-file" و غیره استفاده کنید. برای دریافت اندازه دستگاه‌های بلوکی از "blockdev-getsize64" استفاده کنید.

filesystem-available

filesystem-available filesystem

بررسی می‌کند که آیا libguestfs از فایل‌سیستم نام‌برده پشتیبانی می‌کند یا خیر. آرگومان "filesystem" یک نام فایل‌سیستم مانند "ext3" است.

پیش از استفاده از این دستور باید "launch" را فراخوانی کنید.

این دستور عمدتاً به‌عنوان یک آزمایش منفی کاربرد دارد. اگر این مقدار true برگرداند، به این معنی نیست که یک فایل‌سیستم خاص حتماً می‌تواند ایجاد یا مانت شود، زیرا فایل‌سیستم‌ها ممکن است به دلایل دیگری مانند نسخه جدیدتر فایل‌سیستم، داشتن ویژگی‌های ناسازگار، یا نداشتن ابزار مناسب mkfs.<fs> با شکست مواجه شوند.

همچنین "available"، "feature-available" و "AVAILABILITY" در guestfs(3) را ببینید.

filesystem-walk

filesystem-walk device

پیمایش ساختارهای داخلی یک پارتیشن دیسک (مثلاً /dev/sda1) به‌منظور بازگرداندن فهرستی از تمام فایل‌ها و دایرکتوری‌های ذخیره‌شده در آن.

برای اجرای این دستور نیازی به مانت کردن پارتیشن دیسک نیست.

تمام مدخل‌های درون فایل‌سیستم بازگردانده می‌شوند. این تابع می‌تواند فایل‌های حذف‌شده یا غیرقابل دسترس را نیز فهرست کند. مدخل‌ها مرتب‌سازی نشده‌اند.

ساختار "tsk_dirent" شامل فیلدهای زیر است:

"tsk_inode"

شماره مرجع فایل‌سیستم برای گره (node). اگر گره حذف شده باشد ممکن است 0 باشد.

"tsk_type"

اطلاعات پایه نوع فایل. برای فهرست دقیق مقادیر، بخش زیر را ببینید.

"tsk_size"

اندازه فایل به بایت. اگر گره حذف شده باشد ممکن است -1 باشد.

"tsk_name"

مسیر فایل نسبت به دایرکتوری آن.

"tsk_flags"

فیلد بیتی حاوی اطلاعات اضافی در مورد مدخل. این فیلد شامل OR منطقی مقادیر زیر است:

"tsk_atime_sec"

"tsk_atime_nsec"

"tsk_mtime_sec"

"tsk_mtime_nsec"

"tsk_ctime_sec"

"tsk_ctime_nsec"

"tsk_crtime_sec"

"tsk_crtime_nsec"

به‌ترتیب زمان دسترسی، ویرایش، آخرین تغییر وضعیت و ایجاد در فرمت یونیکس به ثانیه و نانوثانیه.

"tsk_nlink"

تعداد نام‌های فایل اشاره‌کننده به این مدخل.

"tsk_link"

اگر مدخل یک پیوند نمادین (symlink) باشد، این فیلد شامل مسیر به فایل مقصد خواهد بود.

فیلد "tsk_type" شامل یکی از کاراکترهای زیر خواهد بود:

'b'

دستگاه ویژه بلوکی (Block special)

'c'

دستگاه ویژه نویسه‌ای (Char special)

'd'

دایرکتوری (Directory)

'f'

صف لوله‌ای FIFO (لوله نام‌گذاری‌شده)

'l'

پیوند نمادین (Symbolic link)

'r'

فایل معمولی (Regular file)

's'

سوکت (Socket)

'h'

اینود سایه / Shadow inode (سولاریس)

'w'

اینود وایت‌اوت / Whiteout inode (بی‌اس‌دی)

'u'

نوع فایل نامشخص

این دستور به ویژگی "libtsk" وابسته است. همچنین "feature-available" را ببینید.

fill

fill c len path

این دستور یک فایل جدید به نام "path" ایجاد می‌کند. محتوای اولیه فایل شامل "len" بایت از "c" است، که در آن "c" باید عددی در محدوده "[0..255]" باشد.

برای پر کردن یک فایل با بایت‌های صفر (به‌صورت پراکنده / sparse)، استفاده از "truncate-size" بسیار کارآمدتر است. برای ایجاد فایلی با الگویی از بایت‌های تکرارشونده از "fill-pattern" استفاده کنید.

fill-dir

fill-dir dir nr

این تابع که برای آزمایش فایل‌سیستم‌ها کاربرد دارد، تعداد "nr" فایل خالی در دایرکتوری "dir" با نام‌های 00000000 تا "nr-1" ایجاد می‌کند (یعنی هر نام فایل ۸ رقمی است که با صفر پر شده است).

fill-pattern

fill-pattern pattern len path

این تابع مانند "fill" است، با این تفاوت که فایل جدیدی با طول "len" حاوی الگوی تکرارشونده بایت‌ها در "pattern" ایجاد می‌کند. در صورت لزوم الگو بریده می‌شود تا اطمینان حاصل شود که طول فایل دقیقاً "len" بایت است.

find

find directory

این دستور تمام فایل‌ها و دایرکتوری‌ها را به‌صورت بازگشتی با شروع از directory فهرست می‌کند. این دستور اساساً معادل اجرای دستور شل "find directory -print" است، اما برخی پس‌پردازش‌ها روی خروجی انجام می‌شود که در زیر توضیح داده شده است.

این دستور فهرستی از رشته‌ها را بدون هیچ پیشوندی برمی‌گرداند. بنابراین اگر ساختار دایرکتوری به‌صورت زیر باشد:

/tmp/a
/tmp/b
/tmp/c/d

آنگاه فهرست بازگردانده‌شده از "find" روی /tmp دارای ۴ عنصر خواهد بود:

a
b
c
c/d

اگر directory یک دایرکتوری نباشد، این دستور یک خطا برمی‌گرداند.

فهرست بازگردانده‌شده مرتب شده است.

find0

find0 directory (files|-)

این دستور تمام فایل‌ها و دایرکتوری‌ها را به‌صورت بازگشتی با شروع از directory فهرست کرده و فهرست حاصل را در فایل خارجی به نام files قرار می‌دهد.

این دستور مانند "find" کار می‌کند، با استثناهای زیر:

• فهرست حاصل در یک فایل خارجی نوشته می‌شود.
• آیتم‌ها (نام فایل‌ها) در نتیجه با نویسه‌های "\0" از یکدیگر جدا می‌شوند. گزینه -print0 در find(1) را ببینید.
• فهرست نتیجه مرتب‌سازی نشده است.

برای خواندن/نوشتن از stdin/stdout از "-" به‌جای نام فایل استفاده کنید.

find-inode

find-inode device inode

تمام مدخل‌های مرتبط با اینود داده‌شده را جستجو می‌کند.

برای هر مدخل، یک ساختار "tsk_dirent" برگردانده می‌شود. برای اطلاعات بیشتر درباره ساختارهای "tsk_dirent"، بخش "filesystem_walk" را ببینید.

این دستور به ویژگی "libtsk" وابسته است. همچنین "feature-available" را ببینید.

findfs-label

findfs-label label

این دستور فایل‌سیستم‌ها را جستجو کرده و فایل‌سیستمی را که برچسب (label) داده‌شده را دارد برمی‌گرداند. اگر چنین فایل‌سیستمی یافت نشود، خطا برگردانده می‌شود.

برای یافتن برچسب یک فایل‌سیستم، از "vfs-label" استفاده کنید.

findfs-partlabel

findfs-partlabel label

این دستور پارتیشن‌ها را جستجو کرده و پارتیشنی را که برچسب داده‌شده را دارد برمی‌گرداند. اگر چنین پارتیشنی یافت نشود، خطا برگردانده می‌شود.

برای یافتن برچسب یک پارتیشن، از "blkid" ("PART_ENTRY_NAME") استفاده کنید.

findfs-partuuid

findfs-partuuid uuid

این دستور پارتیشن‌ها را جستجو کرده و پارتیشنی را که دارای UUID پارتیشن داده‌شده است برمی‌گرداند. در صورتی که چنین پارتیشنی یافت نشود، یک خطا برگردانده می‌شود.

برای یافتن UUID یک پارتیشن، از "blkid" ("PART_ENTRY_UUID") استفاده کنید.

findfs-uuid

findfs-uuid uuid

این دستور سیستم‌های فایل را جستجو کرده و سیستم فایلی را که دارای UUID داده‌شده است برمی‌گرداند. در صورتی که چنین سیستم فایلی یافت نشود، یک خطا برگردانده می‌شود.

برای یافتن UUID یک سیستم فایل، از "vfs-uuid" استفاده کنید.

fsck

fsck fstype device

این دستور ابزار بررسی سیستم فایل (fsck) را روی "device" که باید دارای نوع سیستم فایل "fstype" باشد اجرا می‌کند.

عدد صحیح برگردانده‌شده وضعیت خروجی است. برای مشاهده فهرست کدهای وضعیت "fsck"، به fsck(8) مراجعه کنید.

نکات:

• چندین کد وضعیت می‌توانند با یکدیگر جمع شوند.
• یک کد بازگشتی غیرصفر می‌تواند به معنای «موفقیت» باشد؛ برای نمونه اگر خطاهایی روی سیستم فایل اصلاح شده باشند.
• بررسی یا تعمیر حجم‌های NTFS (توسط linux-ntfs) پشتیبانی نمی‌شود.

این دستور کاملاً معادل اجرای "fsck -a -t fstype device"; است.

fstrim

fstrim mountpoint [offset:N] [length:N] [minimumfreeextent:N]

فضای خالی موجود در سیستم فایل سوارشده در "mountpoint" را آزادسازی (trim) می‌کند. سیستم فایل باید به‌صورت خواندن-نوشتن (read-write) سوار شده باشد.

محتوای سیستم فایل تحت تأثیر قرار نمی‌گیرد، اما هر فضای خالی در سیستم فایل «آزادسازی» می‌شود، یعنی به دستگاه میزبان پس داده می‌شود؛ بدین ترتیب تصاویر دیسک خلوت‌تر (sparse) شده و امکان استفاده مجدد از فضای استفاده‌نشده در فایل‌های qcow2 فراهم می‌گردد و غیره.

این عملیات نیازمند پشتیبانی در libguestfs، سیستم فایل سوارشده، سیستم فایل میزبان، qemu و هسته میزبان است. اگر این پشتیبانی وجود نداشته باشد، ممکن است خطا دهد یا حتی به نظر برسد که اجرا شده اما هیچ کاری انجام ندهد.

در صورتی که درایور vfs هسته از آزادسازی پشتیبانی نکند، این فراخوانی با تنظیم errno روی "ENOTSUP" شکست خواهد خورد. در حال حاضر این حالت هنگام تلاش برای آزادسازی سیستم‌های فایل FAT رخ می‌دهد.

همچنین ببینید "zero-free-space". آن یک عملیات کمی متفاوت است که فضای خالی سیستم فایل را به صفر تبدیل می‌کند. فراخوانی "fstrim" به‌جای "zero-free-space" یا پس از فراخوانی آن مجاز است.

این دستور یک یا چند آرگومان اختیاری دارد. به "OPTIONAL ARGUMENTS" مراجعه کنید.

این دستور به ویژگی "fstrim" وابسته است. همچنین ببینید "feature-available".

get-append

get-append

گزینه‌های اضافی هسته را که به خط فرمان هسته اپلاینس libguestfs اضافه می‌شوند برمی‌گرداند.

اگر "NULL" باشد، هیچ گزینه‌ای اضافه نمی‌شود.

get-attach-method

get-attach-method

بک‌اند فعلی را برمی‌گرداند.

به "set-backend" و "BACKEND" در guestfs(3) مراجعه کنید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "get-backend" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

get-autosync

get-autosync

پرچم همگام‌سازی خودکار (autosync) را دریافت می‌کند.

get-backend

get-backend

بک‌اند فعلی را برمی‌گرداند.

این ویژگی هندل قبلاً «روش پیوست» (attach method) نامیده می‌شد.

به "set-backend" و "BACKEND" در guestfs(3) مراجعه کنید.

get-backend-setting

get-backend-setting name

یک رشته تنظیمات بک‌اند را پیدا می‌کند که یا "name" است یا با "name=" شروع می‌شود. اگر "name" باشد، رشته "1" را برمی‌گرداند. اگر "name=" باشد، بخش بعد از علامت مساوی را برمی‌گرداند (که ممکن است یک رشته خالی باشد).

اگر چنین تنظیمی یافت نشود، این تابع یک خطا صادر می‌کند. در این حالت errno (ببینید "last-errno") برابر با "ESRCH" خواهد بود.

به "BACKEND" در guestfs(3) و "BACKEND SETTINGS" در guestfs(3) مراجعه کنید.

get-backend-settings

get-backend-settings

تنظیمات فعلی بک‌اند را برمی‌گرداند.

این فراخوانی تمامی رشته‌های تنظیمات بک‌اند را برمی‌گرداند. اگر می‌خواهید یک تنظیم بک‌اند منفرد را بیابید، "get-backend-setting" را ببینید.

به "BACKEND" در guestfs(3) و "BACKEND SETTINGS" در guestfs(3) مراجعه کنید.

get-cachedir

get-cachedir

دایرکتوری مورد استفاده توسط هندل را برای ذخیره حافظه پنهان اپلاینس دریافت می‌کند.

get-direct

get-direct

پرچم حالت مستقیم اپلاینس (direct appliance mode) را برمی‌گرداند.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "internal-get-console-socket" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

get-e2attrs

get-e2attrs file

ویژگی‌های فایل مرتبط با file را برمی‌گرداند.

ویژگی‌ها مجموعه‌ای از بیت‌های مرتبط با هر inode هستند که بر رفتار فایل تأثیر می‌گذارند. ویژگی‌ها به‌صورت رشته‌ای از حروف (شرح داده‌شده در زیر) برگردانده می‌شوند. این رشته ممکن است خالی باشد، که نشان می‌دهد هیچ ویژگی فایلی برای این فایل تنظیم نشده است.

این ویژگی‌ها فقط زمانی وجود دارند که فایل روی یک سیستم فایل ext2/3/4 قرار داشته باشد. استفاده از این فراخوانی روی سایر انواع سیستم فایل منجر به خطا خواهد شد.

نویسه‌ها (ویژگی‌های فایل) در رشته برگردانده‌شده در حال حاضر عبارتند از:

'A'

هنگام دسترسی به فایل، atime آن اصلاح نمی‌شود.

'a'

فایل فقط‌افزودنی (append-only) است.

'c'

فایل روی دیسک فشرده شده است.

'D'

(فقط دایرکتوری‌ها.) تغییرات این دایرکتوری به‌صورت همگام (synchronous) روی دیسک نوشته می‌شوند.

'd'

فایل کاندیدای پشتیبان‌گیری نیست (به dump(8) مراجعه کنید).

'E'

فایل دارای خطاهای فشرده‌سازی است.

'e'

فایل از extentها استفاده می‌کند.

'h'

فایل بلوک‌های خود را به‌جای سکتورها در واحدهای اندازه بلوک سیستم فایل ذخیره می‌کند.

'I'

(فقط دایرکتوری‌ها.) دایرکتوری از درخت‌های درهم‌سازی‌شده (hashed trees) استفاده می‌کند.

'i'

فایل تغییرناپذیر (immutable) است. نمی‌توان آن را تغییر داد، حذف کرد یا نام آن را تغییر داد. هیچ پیوندی نمی‌توان به این فایل ایجاد کرد.

'j'

فایل داده‌ژورنال‌شده (data-journaled) است.

's'

هنگامی که فایل حذف شود، تمام بلوک‌های آن صفر خواهند شد.

'S'

تغییرات این فایل به‌صورت همگام روی دیسک نوشته می‌شوند.

'T'

(فقط دایرکتوری‌ها.) این یک راهنمایی به تخصیص‌دهنده بلوک است که زیردایرکتوری‌های موجود در این دایرکتوری باید در میان بلوک‌ها پخش شوند. اگر وجود نداشته باشد، تخصیص‌دهنده بلوک تلاش خواهد کرد زیردایرکتوری‌ها را در کنار یکدیگر گروه‌بندی کند.

't'

برای یک فایل، ادغام دنباله (tail-merging) را غیرفعال می‌کند. (توسط پیاده‌سازی‌های بالادستی ext2 استفاده نمی‌شود.)

'u'

هنگامی که فایل حذف شود، بلوک‌های آن ذخیره خواهند شد و امکان بازیابی فایل (undelete) فراهم می‌شود.

'X'

محتوای خام فایل فشرده‌شده قابل دسترسی است.

'Z'

فایل فشرده‌شده کثیف (dirty) است.

ویژگی‌های فایل بیشتری ممکن است بعداً به این فهرست اضافه شوند. همه ویژگی‌های فایل ممکن است برای همه انواع فایل‌ها تنظیم نشوند. برای اطلاعات دقیق، به صفحه راهنمای chattr(1) مراجعه کنید.

همچنین ببینید "set-e2attrs".

این ویژگی‌ها را با ویژگی‌های گسترش‌یافته اشتباه نگیرید (ببینید "getxattr").

get-e2generation

get-e2generation file

نسل فایل (file generation) در ext2 را برای یک فایل برمی‌گرداند. نسل (که قبلاً «نسخه» نامیده می‌شد) یک عدد مرتبط با یک inode است. این مورد اغلب توسط سرورهای NFS استفاده می‌شود.

نسل تنها زمانی وجود دارد که فایل روی یک سیستم فایل ext2/3/4 قرار داشته باشد. استفاده از این فراخوانی روی سایر انواع سیستم فایل منجر به خطا خواهد شد.

ببینید "set-e2generation".

get-e2label

get-e2label device

برچسب سیستم فایل ext2/3/4 را برای سیستم فایل روی "device" برمی‌گرداند.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "vfs-label" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

get-e2uuid

get-e2uuid device

شناسه UUID سیستم فایل ext2/3/4 را برای سیستم فایل روی "device" برمی‌گرداند.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "vfs-uuid" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

get-hv

get-hv

باینری هایپروایزر فعلی را برمی‌گرداند.

اگر قبلاً تنظیم نشده باشد، نام باینری پیش‌فرض qemu را برمی‌گرداند.

برای برخی بک‌اندها، اگر این تابع قبل از راه‌اندازی فراخوانی شود ممکن است خطایی برگرداند، زیرا ممکن است دریافت هایپروایزر پیش‌فرض قبل از راه‌اندازی اپلاینس امکان‌پذیر نباشد.

get-identifier

get-identifier

شناسه هندل را دریافت می‌کند. ببینید "set-identifier".

get-libvirt-requested-credential-challenge

get-libvirt-requested-credential-challenge index

چالش (ارائه‌شده توسط libvirt) را برای "index"امین اعتبار درخواستی دریافت می‌کند. اگر libvirt چالشی ارائه نکرده باشد، این تابع رشته خالی "" را برمی‌گرداند.

برای مستندات و کدهای نمونه، به "LIBVIRT AUTHENTICATION" در guestfs(3) مراجعه کنید.

get-libvirt-requested-credential-defresult

get-libvirt-requested-credential-defresult index

نتیجه پیش‌فرض (ارائه‌شده توسط libvirt) را برای "index"امین اعتبار درخواستی دریافت می‌کند. اگر libvirt نتیجه پیش‌فرضی ارائه نکرده باشد، این تابع رشته خالی "" را برمی‌گرداند.

برای مستندات و کدهای نمونه، به "LIBVIRT AUTHENTICATION" در guestfs(3) مراجعه کنید.

get-libvirt-requested-credential-prompt

get-libvirt-requested-credential-prompt index

اعلان درخواست (ارائه‌شده توسط libvirt) را برای "index"امین اعتبار درخواستی دریافت می‌کند. اگر libvirt درخواستی ارائه نکرده باشد، این تابع رشته خالی "" را برمی‌گرداند.

برای مستندات و کدهای نمونه، به "LIBVIRT AUTHENTICATION" در guestfs(3) مراجعه کنید.

get-libvirt-requested-credentials

get-libvirt-requested-credentials

این تابع فقط باید در طول callback رویداد برای رویدادهای از نوع "GUESTFS_EVENT_LIBVIRT_AUTH" فراخوانی شود.

فهرست اعتبارهای درخواست‌شده توسط libvirt را برمی‌گرداند. مقادیر ممکن زیرمجموعه‌ای از رشته‌های ارائه‌شده هنگام فراخوانی "set-libvirt-supported-credentials" هستند.

برای مستندات و کدهای نمونه، به "LIBVIRT AUTHENTICATION" در guestfs(3) مراجعه کنید.

get-memsize

get-memsize

میزان حافظه بر حسب مگابایت تخصیص‌یافته به هایپروایزر را دریافت می‌کند.

اگر "set-memsize" روی این هندل فراخوانی نشده باشد، و اگر "LIBGUESTFS_MEMSIZE" تنظیم نشده باشد، مقدار پیش‌فرض کامپایل‌شده برای memsize برگردانده می‌شود.

برای اطلاعات بیشتر در مورد معماری libguestfs، به guestfs(3) مراجعه کنید.

get-network

get-network

پرچم فعال بودن شبکه را برمی‌گرداند.

get-path

get-path

مسیر جستجوی فعلی را برمی‌گرداند.

این مقدار همیشه غیر-NULL است. اگر قبلاً تنظیم نشده باشد، مسیر پیش‌فرض را برمی‌گرداند.

get-pgroup

get-pgroup

پرچم گروه فرایند (process group) را برمی‌گرداند.

get-pid

pid

get-pid

شناسه فرایند (PID) هایپروایزر را برمی‌گرداند. اگر هیچ هایپروایزری در حال اجرا نباشد، یک خطا برمی‌گرداند.

این یک فراخوانی داخلی است که برای اشکال‌زدایی و آزمایش استفاده می‌شود.

get-program

get-program

نام برنامه را دریافت می‌کند. ببینید "set-program".

get-qemu

get-qemu

باینری هایپروایزر فعلی (معمولاً qemu) را برمی‌گرداند.

این مقدار همیشه غیر-NULL است. اگر قبلاً تنظیم نشده باشد، نام باینری پیش‌فرض qemu را برمی‌گرداند.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "get-hv" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

get-recovery-proc

get-recovery-proc

پرچم فعال بودن فرایند بازیابی را برمی‌گرداند.

get-selinux

get-selinux

تنظیمات فعلی پرچم selinux را که در زمان بوت به اپلاینس منتقل می‌شود برمی‌گرداند. ببینید "set-selinux".

برای اطلاعات بیشتر در مورد معماری libguestfs، به guestfs(3) مراجعه کنید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "selinux-relabel" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

get-smp

get-smp

تعداد CPUهای مجازی اختصاص‌یافته به اپلاینس را برمی‌گرداند.

get-sockdir

get-sockdir

دایرکتوری مورد استفاده توسط هندل برای ذخیره سوکت‌های موقت و فایل‌های PID را دریافت می‌کند.

این با "get-tmpdir" متفاوت است، زیرا ما برای سوکت‌ها به مسیرهای کوتاه‌تری نیاز داریم (به دلیل بافرهای محدود نام فایل‌ها برای سوکت‌های UNIX)، و "get-tmpdir" ممکن است برای آن‌ها بیش از حد طولانی باشد. علاوه بر این، سوکت‌ها و فایل‌های PID باید برای سرویس‌های پس‌زمینه‌ای که توسط libguestfs راه‌اندازی می‌شوند و ممکن است مجوز دسترسی به دایرکتوری موقت برگردانده‌شده توسط "get-tmpdir" را نداشته باشند، قابل دسترسی باشند.

متغیر محیطی "XDG_RUNTIME_DIR" مقدار پیش‌فرض را کنترل می‌کند: اگر "XDG_RUNTIME_DIR" تنظیم شده باشد، آن مقدار پیش‌فرض است. در غیر این صورت /tmp پیش‌فرض خواهد بود.

get-tmpdir

get-tmpdir

دایرکتوری مورد استفاده توسط هندل برای ذخیره فایل‌های موقت را دریافت می‌کند.

get-trace

get-trace

پرچم ردیابی دستور (command trace) را برمی‌گرداند.

get-umask

get-umask

ماسک umask فعلی را برمی‌گرداند. به‌طور پیش‌فرض umask برابر با 022 است مگر اینکه با فراخوانی "umask" تنظیم شده باشد.

get-verbose

get-verbose

پرچم پیام‌های پرجزئیات (verbose messages) را برمی‌گرداند.

getcon

getcon

زمینه امنیتی SELinux مربوط به دیمن را دریافت می‌کند.

به مستندات مربوط به SELINUX در guestfs(3) و "setcon" مراجعه کنید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "selinux-relabel" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

این دستور به ویژگی "selinux" وابسته است. همچنین ببینید "feature-available".

getxattr

getxattr path name

یک ویژگی گسترش‌یافته منفرد را از فایل "path" با نام "name" دریافت می‌کند. این فراخوانی پیوندهای نمادین را دنبال می‌کند. اگر می‌خواهید یک ویژگی گسترش‌یافته را برای خود پیوند نمادین جستجو کنید، از "lgetxattr" استفاده کنید.

به‌طور معمول بهتر است همه ویژگی‌های گسترش‌یافته یک فایل را یک‌باره با فراخوانی "getxattrs" دریافت کنید. با این حال، برخی از پیاده‌سازی‌های سیستم فایل لینوکس دارای باگ هستند و روشی برای فهرست کردن ویژگی‌ها ارائه نمی‌دهند. برای این سیستم‌های فایل (به‌ویژه ntfs-3g) باید نام ویژگی‌های گسترش‌یافته مورد نظر خود را از قبل بدانید و این تابع را فراخوانی کنید.

مقادیر ویژگی‌های گسترش‌یافته داده‌های باینری (blob) هستند. اگر هیچ ویژگی گسترش‌یافته‌ای با نام "name" وجود نداشته باشد، این تابع یک خطا برمی‌گرداند.

همچنین ببینید: "getxattrs"، "lgetxattr"، attr(5).

این دستور به ویژگی "linuxxattrs" وابسته است. همچنین ببینید "feature-available".

getxattrs

getxattrs path

این فراخوانی ویژگی‌های گسترش‌یافته فایل یا دایرکتوری "path" را فهرست می‌کند.

در سطح فراخوانی سیستمی، این ترکیبی از فراخوانی‌های listxattr(2) و getxattr(2) است.

همچنین ببینید: "lgetxattrs"، attr(5).

این دستور به ویژگی "linuxxattrs" وابسته است. همچنین ببینید "feature-available".

glob-expand

glob-expand-opts

glob-expand pattern [directoryslash:true|false]

این دستور تمام مسیرهای منطبق بر "pattern" را بر اساس قوانین گسترش حروف عام (wildcard) که توسط شل استفاده می‌شود جستجو می‌کند.

اگر هیچ مسیری مطابقت نداشته باشد، یک فهرست خالی برمی‌گرداند (توجه: خطا نیست).

این فقط یک پوشش پیرامون تابع glob(3) در C با پرچم‌های "GLOB_MARK|GLOB_BRACE" است. برای جزئیات بیشتر به آن صفحه راهنما مراجعه کنید.

"directoryslash" مشخص می‌کند که آیا از پرچم "GLOB_MARK" برای glob(3) استفاده شود یا خیر، و مقدار پیش‌فرض آن true است. می‌توان آن را صراحتاً غیرفعال کرد تا هیچ اسلش پایانی در نام فایل‌های دایرکتوری‌ها برگردانده نشود.

توجه داشته باشید که هیچ دستور معادلی برای گسترش نام یک دستگاه (مانند /dev/sd*) وجود ندارد. به‌جای آن از توابع "list-devices"، "list-partitions" و غیره استفاده کنید.

این دستور یک یا چند آرگومان اختیاری دارد. به "OPTIONAL ARGUMENTS" مراجعه کنید.

grep

grep-opts

grep regex path [extended:true|false] [fixed:true|false] [insensitive:true|false] [compressed:true|false]

این برنامه خارجی grep(1) را فراخوانی کرده و خطوط منطبق را برمی‌گرداند.

پرچم‌های اختیاری عبارتند از:

"extended"

استفاده از عبارات منظم گسترش‌یافته. این معادل استفاده از پرچم -E است.

"fixed"

تطبیق ثابت (عدم استفاده از عبارات منظم). این معادل استفاده از پرچم -F است.

"insensitive"

تطبیق بدون حساسیت به حروف بزرگ و کوچک. این معادل استفاده از پرچم -i است.

"compressed"

استفاده از zgrep(1) به‌جای grep(1). این به ورودی امکان می‌دهد که با compress یا gzip فشرده شده باشد.

این دستور یک یا چند آرگومان اختیاری دارد. به "OPTIONAL ARGUMENTS" مراجعه کنید.

به دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

grepi

grepi regex path

این برنامه خارجی "grep -i" را فراخوانی کرده و خطوط منطبق را برمی‌گرداند.

به دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "grep" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

grub-install

grub-install root device

این دستور GRUB 1 (گرند یونایفاید بوت‌لودر) را روی "device" با دایرکتوری ریشه "root" نصب می‌کند.

نکات:

• در حال حاضر روشی در API برای نصب grub2، که توسط اکثر مهمان‌های لینوکس مدرن استفاده می‌شود، وجود ندارد. امکان اجرای دستور grub2 از درون مهمان وجود دارد، هرچند هشدارهای موجود در "RUNNING COMMANDS" در guestfs(3) را ببینید.
• این از grub-install(8) از میزبان استفاده می‌کند. متأسفانه grub همیشه با خودش سازگار نیست، بنابراین این فقط در شرایط نسبتاً محدودی کار می‌کند. آزمایش دقیق با هر نسخه مهمان توصیه می‌شود.
• اگر grub-install خطای "No suitable drive was found in the generated device map." را گزارش کند، ممکن است لازم باشد ابتدا یک فایل /boot/grub/device.map ایجاد کنید که حاوی نگاشت بین نام‌های دستگاه grub و نام‌های دستگاه لینوکس باشد. معمولاً ایجاد فایلی حاوی موارد زیر کافی است:

  (hd0) /dev/vda

  که در آن /dev/vda با نام دستگاه نصب جایگزین می‌شود.

این دستور به ویژگی "grub" وابسته است. همچنین ببینید "feature-available".

head

head path

این دستور تا ۱۰ خط اول یک فایل را به‌صورت فهرستی از رشته‌ها برمی‌گرداند.

به دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

head-n

head-n nrlines path

اگر پارامتر "nrlines" یک عدد مثبت باشد، "nrlines" خط اول فایل "path" را برمی‌گرداند.

اگر پارامتر "nrlines" یک عدد منفی باشد، خطوط فایل "path" را به استثنای "nrlines" خط آخر برمی‌گرداند.

اگر پارامتر "nrlines" صفر باشد، یک فهرست خالی برمی‌گرداند.

به دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

hexdump

hexdump path

این دستور "hexdump -C" را روی "path" داده‌شده اجرا می‌کند. نتیجه، دامپ هگز استاندارد و خوانا برای انسان از فایل است.

به دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

hivex-close

hivex-close

هندل فعلی hivex را می‌بندد.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-commit

hivex-commit filename

تغییرات را در هایو (hive) ثبت (ذخیره) می‌کند.

اگر پارامتر اختیاری filename برابر با null باشد، تغییرات در همان هایوی که باز شده بود بازنویسی می‌شوند. اگر null نباشد، تغییرات در نام فایل جایگزین داده‌شده نوشته شده و هایوی اصلی دست‌نخورده باقی می‌ماند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-add-child

hivex-node-add-child parent name

یک گره فرزند به "parent" با نام "name" اضافه می‌کند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-children

hivex-node-children nodeh

فهرست گره‌هایی را که زیرکلیدهای "nodeh" هستند برمی‌گرداند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-delete-child

hivex-node-delete-child nodeh

گره "nodeh" را در صورت لزوم به‌صورت بازگشتی حذف می‌کند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-get-child

hivex-node-get-child nodeh name

فرزند "nodeh" را با نام "name" در صورت وجود برمی‌گرداند. این می‌تواند 0 را برگرداند که به معنی پیدا نشدن نام است.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-get-value

hivex-node-get-value nodeh key

مقدار متصل به "nodeh" را که دارای نام "key" است در صورت وجود برمی‌گرداند. این می‌تواند 0 را برگرداند که به معنی پیدا نشدن کلید است.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-name

hivex-node-name nodeh

نام "nodeh" را برمی‌گرداند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-parent

hivex-node-parent nodeh

گره والد "nodeh" را برمی‌گرداند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-set-value

hivex-node-set-value nodeh key t val

یک مقدار منفرد را زیر گره "nodeh" تنظیم یا جایگزین می‌کند. "key" نام، "t" نوع، و "val" داده است.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-node-values

hivex-node-values nodeh

آرایه‌ای از تاپل‌های (key, datatype, data) متصل به "nodeh" را برمی‌گرداند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-open

hivex-open filename [verbose:true|false] [debug:true|false] [write:true|false] [unsafe:true|false]

فایل هایو رجیستری ویندوز با نام filename را باز می‌کند. اگر هرگونه هندل قبلی hivex مرتبط با این نشست guestfs وجود داشته باشد، بسته می‌شود.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور یک یا چند آرگومان اختیاری دارد. به "OPTIONAL ARGUMENTS" مراجعه کنید.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-root

hivex-root

گره ریشه هایو را برمی‌گرداند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-value-key

hivex-value-key valueh

فیلد کلید (نام) یک تاپل (key, datatype, data) را برمی‌گرداند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-value-string

hivex-value-string valueh

این تابع "hivex-value-value" را فراخوانی می‌کند (که فیلد داده را از یک تاپل مقدار hivex برمی‌گرداند). سپس فرض می‌کند که فیلد یک رشته UTF-16LE است و نتیجه را به UTF-8 تبدیل می‌کند (یا اگر این امکان‌پذیر نباشد، یک خطا برمی‌گرداند).

این برای خواندن رشته‌ها از رجیستری ویندوز مفید است. با این حال کاملاً بدون خطا نیست زیرا رجیستری به شدت دارای نوع‌بندی قوی نیست و فیلدها می‌توانند حاوی داده‌های دلخواه یا غیرمنتظره باشند.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-value-type

hivex-value-type valueh

فیلد نوع داده را از یک تاپل (key, datatype, data) برمی‌گرداند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-value-utf8

hivex-value-utf8 valueh

این تابع "hivex-value-value" را فراخوانی می‌کند (که فیلد داده را از یک تاپل مقدار hivex برمی‌گرداند). سپس فرض می‌کند که فیلد یک رشته UTF-16LE است و نتیجه را به UTF-8 تبدیل می‌کند (یا اگر این امکان‌پذیر نباشد، یک خطا برمی‌گرداند).

این برای خواندن رشته‌ها از رجیستری ویندوز مفید است. با این حال کاملاً بدون خطا نیست زیرا رجیستری به شدت دارای نوع‌بندی قوی نیست و فیلدها می‌توانند حاوی داده‌های دلخواه یا غیرمنتظره باشند.

این تابع منسوخ شده است. در کدهای جدید، به‌جای آن از فراخوانی "hivex-value-string" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

hivex-value-value

hivex-value-value valueh

فیلد داده یک تاپل (key, datatype, data) را برمی‌گرداند.

این یک پوشش پیرامون فراخوانی هم‌نام در hivex(3) است.

همچنین ببینید: "hivex-value-utf8".

این دستور به ویژگی "hivex" وابسته است. همچنین ببینید "feature-available".

initrd-cat

initrd-cat initrdpath filename

این دستور فایل filename را از فایل initrd با نام initrdpath استخراج می‌کند. نام فایل باید بدون نویسه اولیه / داده شود.

برای مثال، در guestfish می‌توانید از دستور زیر برای بررسی اسکریپت بوت (که معمولاً /init نامیده می‌شود) موجود در یک ایمیج initrd یا initramfs لینوکس استفاده کنید:

initrd-cat /boot/initrd-<version>.img init

همچنین ببینید "initrd-list".

به دلیل پروتکل پیام، یک محدودیت انتقال بین ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

initrd-list

initrd-list path

این دستور فایل‌های موجود در یک initrd را فهرست می‌کند.

فایل‌ها بدون هیچ کاراکتر ابتدایی / فهرست می‌شوند. فایل‌ها به همان ترتیبی که ظاهر می‌شوند (نه لزوماً بر اساس حروف الفبا) فهرست می‌گردند. نام دایرکتوری‌ها به عنوان موارد جداگانه فهرست می‌شوند.

هسته‌های قدیمی لینوکس (۲.۴ و قبل از آن) از یک فایل‌سیستم فشرده ext2 به عنوان initrd استفاده می‌کردند. ما فقط از قالب جدیدتر initramfs (فایل‌های cpio فشرده) پشتیبانی می‌کنیم.

inotify-add-watch

inotify-add-watch path mask

مسیر "path" را برای رویدادهای فهرست‌شده در "mask" پایش کنید.

توجه داشته باشید که اگر "path" یک دایرکتوری باشد، رویدادهای درون آن دایرکتوری پایش می‌شوند، اما این کار به‌صورت بازگشتی (در زیردایرکتوری‌ها) رخ نمی‌دهد.

نکته برای فراخوان‌های غیر C یا غیر لینوکس: رویدادهای inotify توسط ABI هسته لینوکس تعریف شده‌اند و در /usr/include/sys/inotify.h فهرست شده‌اند.

این دستور به ویژگی "inotify" وابسته است. همچنین ببینید "feature-available".

inotify-close

inotify-close

این دستور هندل inotify را که قبلاً توسط inotify_init باز شده بود می‌بندد. این کار تمام پایش‌ها را حذف می‌کند، هر رویداد در انتظار را دور می‌ریزد و تمام منابع را آزاد می‌کند.

این دستور به ویژگی "inotify" وابسته است. همچنین ببینید "feature-available".

inotify-files

inotify-files

این تابع یک پوشش کمکی پیرامون "inotify-read" است که فقط فهرستی از نام مسیرهای اشیایی را که لمس شده‌اند (تغییر یافته‌اند) برمی‌گرداند. نام مسیرهای بازگردانده‌شده مرتب‌شده و یکتا هستند.

این دستور به ویژگی "inotify" وابسته است. همچنین ببینید "feature-available".

inotify-init

inotify-init maxevents

این دستور یک هندل جدید inotify ایجاد می‌کند. زیرسیستم inotify را می‌توان برای اطلاع از رویدادهایی که برای اشیاء در فایل‌سیستم مهمان رخ می‌دهند استفاده کرد.

"maxevents" حداکثر تعداد رویدادهایی است که بین فراخوانی‌های "inotify-read" یا "inotify-files" در صف قرار می‌گیرند. اگر این مقدار به عنوان 0 ارسال شود، از پیش‌فرض هسته (یا مقدار تنظیم‌شده قبلی) استفاده می‌شود. برای لینوکس 2.6.29 مقدار پیش‌فرض ۱۶۳۸۴ رویداد بود. فراتر از این حد، هسته رویدادها را دور می‌ریزد، اما ثبت می‌کند که آن‌ها را با تنظیم پرچم "IN_Q_OVERFLOW" در فهرست ساختار بازگردانده‌شده دور ریخته است (ببینید "inotify-read").

پیش از اینکه هرگونه رویدادی تولید شود، باید پایش‌هایی را به فهرست پایش داخلی اضافه کنید. ببینید: "inotify-add-watch" و "inotify-rm-watch".

رویدادهای درون صف باید با فراخوانی دوره‌ای "inotify-read" (یا "inotify-files" که صرفاً یک پوشش کمکی پیرامون "inotify-read" است) خوانده شوند. اگر رویدادها را به اندازه کافی نخوانید، خطر سرریز صف داخلی وجود دارد.

هندل باید پس از استفاده با فراخوانی "inotify-close" بسته شود. این کار همچنین تمام پایش‌ها را به‌طور خودکار حذف می‌کند.

همچنین برای یک نمای کلی از رابط inotify همان‌گونه که توسط هسته لینوکس ارائه شده است، inotify(7) را ببینید که تقریباً همان چیزی است که ما از طریق libguestfs ارائه می‌دهیم. توجه داشته باشید که به ازای هر نمونه libguestfs یک هندل سراسری inotify وجود دارد.

این دستور به ویژگی "inotify" وابسته است. همچنین ببینید "feature-available".

inotify-read

inotify-read

صف کامل رویدادهایی را که از زمان فراخوانی خواندن قبلی رخ داده‌اند برمی‌گرداند.

اگر هیچ رویدادی رخ نداده باشد، این دستور یک فهرست خالی برمی‌گرداند.

نکته: برای اطمینان از اینکه تمام رویدادها خوانده شده‌اند، باید این تابع را مکرراً فراخوانی کنید تا زمانی که یک فهرست خالی برگرداند. دلیل این امر آن است که فراخوانی رویدادها را تا حداکثر اندازه پیام appliance-to-host می‌خواند و رویدادهای باقی‌مانده را در صف رها می‌کند.

این دستور به ویژگی "inotify" وابسته است. همچنین ببینید "feature-available".

inotify-rm-watch

inotify-rm-watch wd

یک پایش inotify تعریف‌شده قبلی را حذف می‌کند. ببینید "inotify-add-watch".

این دستور به ویژگی "inotify" وابسته است. همچنین ببینید "feature-available".

inspect-get-arch

inspect-get-arch root

این دستور معماری سیستم‌عامل بازرسی‌شده را برمی‌گرداند. مقادیر بازگشتی ممکن در زیر "file-architecture" فهرست شده‌اند.

اگر معماری قابل تشخیص نباشد، رشته "unknown" برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-build-id

inspect-get-build-id root

این دستور شناسه ساخت (Build ID) سیستم را برمی‌گرداند، یا اگر سیستم شناسه ساخت نداشته باشد، رشته "unknown" را برمی‌گرداند.

برای ویندوز، این دستور شماره ساخت را دریافت می‌کند. اگرچه به عنوان یک رشته برگردانده می‌شود، اما (تاکنون) همیشه یک عدد است. برای برخی از مقادیر ممکن، https://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions را ببینید.

برای لینوکس، این رشته "BUILD_ID" را از /etc/os-release برمی‌گرداند، اگرچه این مورد اغلب استفاده نمی‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-distro

inspect-get-distro root

این دستور توزیع (distribution) سیستم‌عامل بازرسی‌شده را برمی‌گرداند.

توزیع‌های تعریف‌شده در حال حاضر عبارتند از:

"alpinelinux"

آلپاین لینوکس (Alpine Linux).

"altlinux"

آلت لینوکس (ALT Linux).

"archlinux"

آرچ لینوکس (Arch Linux).

"buildroot"

توزیع مشتق‌شده از Buildroot، اما نه توزیعی که به‌طور خاص شناسایی کنیم.

"centos"

سنت‌او‌اس (CentOS).

"circle"

سیرکل لینوکس (Circle Linux).

"cirros"

سیروس (Cirros).

"coreos"

کوراو‌اس (CoreOS).

"debian"

دبیان (Debian).

"fedora"

فدورا (Fedora).

"freebsd"

فری‌بی‌اس‌دی (FreeBSD).

"freedos"

فری‌داس (FreeDOS).

"frugalware"

فروگال‌ور (Frugalware).

"gentoo"

جنتو (Gentoo).

"kalilinux"

کالی لینوکس (Kali Linux).

"kylin"

کایلین (Kylin).

"linuxmint"

لینوکس مینت (Linux Mint).

"mageia"

ماژیا (Mageia).

"mandriva"

ماندریوا (Mandriva).

"meego"

می‌گو (MeeGo).

"msdos"

مایکروسافت داس (Microsoft DOS).

"neokylin"

نئوکایلین (NeoKylin).

"netbsd"

نت‌بی‌اس‌دی (NetBSD).

"openbsd"

اوپن‌بی‌اس‌دی (OpenBSD).

"openeuler"

اوپن‌اویلر (openEuler).

"openmandriva"

اوپن‌ماندریوا (OpenMandriva Lx).

"opensuse"

اوپن‌سوزه (OpenSUSE).

"oraclelinux"

اوراکل لینوکس (Oracle Linux).

"pardus"

پاردوس (Pardus).

"pldlinux"

پی‌ال‌دی لینوکس (PLD Linux).

"redhat-based"

یک توزیع مشتق‌شده از رد هت (Red Hat).

"rhel"

رد هت اینترپرایز لینوکس (Red Hat Enterprise Linux).

"rocky"

راکی لینوکس (Rocky Linux).

"scientificlinux"

ساینتیفیک لینوکس (Scientific Linux).

"slackware"

اسلکور (Slackware).

"sles"

سرور یا دسکتاپ سوزه لینوکس سازمانی (SuSE Linux Enterprise Server or Desktop).

"suse-based"

یک توزیع مشتق‌شده از اوپن‌سوزه.

"ttylinux"

تی‌تی‌وای‌لینوکس (ttylinux).

"ubuntu"

اوبونتو (Ubuntu).

"unknown"

توزیع قابل تشخیص نبود.

"voidlinux"

ووید لینوکس (Void Linux).

"windows"

ویندوز توزیع ندارد. اگر نوع سیستم‌عامل ویندوز باشد، این رشته برگردانده می‌شود.

نسخه‌های بعدی libguestfs ممکن است رشته‌های دیگری را در اینجا برگردانند. فراخوان باید آماده رسیدگی به هر رشته‌ای باشد.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-drive-mappings

inspect-get-drive-mappings root

این فراخوانی برای ویندوز که از سیستم ابتدایی اختصاص حروف درایو (مانند C:\) به پارتیشن‌ها استفاده می‌کند، مفید است. این API بازرسی، رجیستری ویندوز را بررسی می‌کند تا بفهمد دیسک‌ها/پارتیشن‌ها چگونه به حروف درایو نگاشت شده‌اند، و یک جدول هش مانند مثال زیر برمی‌گرداند:

C      =>     /dev/vda2
E      =>     /dev/vdb1
F      =>     /dev/vdc1

توجه داشته باشید که کلیدها حروف درایو هستند. برای ویندوز، کلید به حروف بزرگ و کوچک حساس نیست و فقط شامل حرف درایو است، بدون کاراکتر جداکننده دونقطه معمول.

در آینده ممکن است از سایر سیستم‌های عاملی که از حروف درایو استفاده می‌کردند نیز پشتیبانی کنیم، اما ممکن است کلیدهای آن‌ها به حروف بزرگ و کوچک حساس باشند و طولانی‌تر از ۱ کاراکتر باشند. برای مثال در OS-9، هارد دیسک‌ها "h0"، "h1" و غیره نام‌گذاری می‌شدند.

برای مهمان‌های ویندوز، در حال حاضر فقط نگاشت‌های هارد دیسک بازگردانده می‌شوند. دیسک‌های قابل جابجایی (مثلاً DVD-ROMها) نادیده گرفته می‌شوند.

برای مهمان‌هایی که از نگاشت درایو استفاده نمی‌کنند، یا اگر نگاشت‌های درایو قابل تشخیص نباشد، این دستور یک جدول هش خالی برمی‌گرداند.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید. همچنین ببینید "inspect-get-mountpoints" و "inspect-get-filesystems".

inspect-get-filesystems

inspect-get-filesystems root

فهرستی از تمام فایل‌سیستم‌هایی را که فکر می‌کنیم با این سیستم‌عامل مرتبط هستند برمی‌گرداند. این شامل فایل‌سیستم ریشه، سایر فایل‌سیستم‌های معمولی و دستگاه‌های سوارنشده مانند پارتیشن‌های swap می‌شود.

در مورد یک ماشین مجازی چندبوت (multi-boot)، ممکن است یک فایل‌سیستم بین سیستم‌های عامل به اشتراک گذاشته شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید. همچنین ببینید "inspect-get-mountpoints".

inspect-get-format

inspect-get-format root

قبل از libguestfs 1.38، پشتیبانی غیرقابل اعتمادی برای تشخیص CDهای نصب وجود داشت. این API مقادیر زیر را برمی‌گرداند:

"installed"

این یک سیستم‌عامل نصب‌شده است.

"installer"

ایمیج دیسک در حال بازرسی یک سیستم‌عامل نصب‌شده نیست، بلکه یک دیسک نصب قابل بوت، دیسک زنده (Live CD) یا مشابه آن است.

"unknown"

قالب این ایمیج دیسک ناشناخته است.

در libguestfs ≥ 1.38، این تابع فقط "installed" را برمی‌گرداند. برای تشخیص CDهای نصب مستقیماً از libosinfo استفاده کنید.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

این تابع منسوخ شده است. جایگزینی وجود ندارد. برای اطلاعات بیشتر به مستندات API در guestfs(3) مراجعه کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

inspect-get-hostname

inspect-get-hostname root

این تابع نام میزبان (hostname) سیستم‌عامل را همان‌طور که با بازرسی فایل‌های پیکربندی مهمان یافت شده است برمی‌گرداند.

اگر نام میزبان قابل تشخیص نباشد، رشته "unknown" برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-icon

inspect-get-icon root [favicon:true|false] [highquality:true|false]

این تابع آیکونی متناظر با سیستم‌عامل بازرسی‌شده را برمی‌گرداند. آیکون به عنوان یک بافر حاوی یک تصویر PNG (در صورت نیاز بازرمزگذاری‌شده به PNG) برگردانده می‌شود.

اگر دریافت آیکون ممکن نباشد، این تابع یک بافر با طول صفر (غیر NULL) برمی‌گرداند. فراخوان‌ها باید این حالت را بررسی کنند.

ابزار Libguestfs با جستجو برای فایلی به نام /etc/favicon.png یا C:\etc\favicon.png شروع می‌کند و در صورت داشتن قالب صحیح، محتویات این فایل برگردانده می‌شود. می‌توانید با ارسال مقدار بولی اختیاری "favicon" به عنوان false (پیش‌فرض true است)، فاوآیکون‌ها را غیرفعال کنید.

اگر یافتن فاوآیکون ناموفق باشد، در جاهای دیگر مهمان به دنبال یک آیکون مناسب می‌گردیم.

اگر مقدار بولی اختیاری "highquality" برابر true باشد، فقط آیکون‌های باکیفیت بالا برگردانده می‌شوند، که به معنای فقط آیکون‌های با وضوح بالا همراه با کانال آلفا است. پیش‌فرض (false) بازگرداندن هر آیکونی است که می‌توانیم، حتی اگر کیفیت پایینی داشته باشد.

نکات:

• برخلاف بیشتر فراخوانی‌های دیگر API بازرسی، دیسک‌های مهمان باید قبل از فراخوانی این دستور سوار (mount) شده باشند، زیرا باید اطلاعات را از فایل‌سیستم مهمان در طول فراخوانی بخواند.
• امنیت: داده‌های آیکون از مهمان غیرقابل اعتماد می‌آیند و باید با احتیاط با آن‌ها رفتار شود. فایل‌های PNG به داشتن اکسپلویت شناخته شده‌اند. اطمینان حاصل کنید که libpng (یا سایر کتابخانه‌های مربوطه) قبل از تلاش برای پردازش یا نمایش آیکون کاملاً به‌روز هستند.
• تصویر PNG بازگردانده‌شده می‌تواند هر اندازه‌ای داشته باشد. ممکن است مربع نباشد. Libguestfs تلاش می‌کند بزرگ‌ترین و باکیفیت‌ترین آیکون موجود را برگرداند. برنامه کاربردی باید آیکون را به اندازه مورد نیاز مقیاس‌بندی کند.
• استخراج آیکون‌ها از مهمان‌های ویندوز به برنامه خارجی wrestool(1) از بسته "icoutils"، و چندین برنامه (bmptopnm(1)، pnmtopng(1)، pamcut(1)) از بسته "netpbm" نیاز دارد. این‌ها باید جداگانه نصب شوند.
• آیکون‌های سیستم‌عامل معمولاً نشان‌های تجاری هستند. قبل از استفاده از نشان‌های تجاری در برنامه‌ها به دنبال مشاوره حقوقی باشید.

این دستور دارای یک یا چند آرگومان اختیاری است. ببینید "OPTIONAL ARGUMENTS".

inspect-get-major-version

inspect-get-major-version root

این دستور شماره نسخه اصلی (major version) سیستم‌عامل بازرسی‌شده را برمی‌گرداند.

ویندوز از یک طرح نسخه‌بندی منسجم استفاده می‌کند که در نام‌های عمومی محبوب مورداستفاده برای سیستم‌عامل منعکس نشده است. به‌ویژه سیستم‌عاملی که با نام "Windows 7" شناخته می‌شود، در واقع نسخه 6.1 است (یعنی major = 6 و minor = 1). می‌توانید با مراجعه به ویکی‌پدیا یا MSDN نسخه‌های واقعی مربوط به انتشار‌های ویندوز را بیابید.

اگر نسخه قابل تشخیص نباشد، 0 برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-minor-version

inspect-get-minor-version root

این دستور شماره نسخه فرعی (minor version) سیستم‌عامل بازرسی‌شده را برمی‌گرداند.

اگر نسخه قابل تشخیص نباشد، 0 برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید. همچنین ببینید "inspect-get-major-version".

inspect-get-mountpoints

inspect-get-mountpoints root

یک هش از جاهایی که فکر می‌کنیم فایل‌سیستم‌های مرتبط با این سیستم‌عامل باید در آنجا سوار شوند برمی‌گرداند. فراخوان‌ها باید توجه داشته باشند که این در بهترین حالت یک حدس آگاهانه است که از طریق خواندن فایل‌های پیکربندی مانند /etc/fstab انجام شده است. به‌ویژه توجه داشته باشید که این ممکن است فایل‌سیستم‌هایی را برگرداند که وجود ندارند یا قابل سوار شدن نیستند و فراخوان‌ها باید آماده باشند تا در صورت تلاش برای سوار کردن آن‌ها، خرابی‌ها را مدیریت یا نادیده بگیرند.

هر عنصر در جدول هش بازگردانده‌شده کلیدی دارد که مسیر نقطه اتصال (مانند /boot) است و مقداری دارد که فایل‌سیستمی است که در آنجا سوار می‌شود (مانند /dev/sda1).

دستگاه‌های سوارنشده مانند دستگاه‌های swap در این فهرست بازگردانده نمی‌شوند.

برای سیستم‌های عاملی مانند ویندوز که هنوز از حروف درایو استفاده می‌کنند، این فراخوانی فقط ورودی اولین درایو "سوار شده روی" / را برمی‌گرداند. برای اطلاعات در مورد نگاشت حروف درایو به پارتیشن‌ها، "inspect-get-drive-mappings" را ببینید.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید. همچنین ببینید "inspect-get-filesystems".

inspect-get-osinfo

inspect-get-osinfo root

این تابع یک شناسه کوتاه احتمالی برای libosinfo متناظر با مهمان را برمی‌گرداند.

نکته: شناسه بازگردانده‌شده فقط یک حدس توسط libguestfs است، و هیچ چیز تضمین نمی‌کند که واقعاً در osinfo-db وجود داشته باشد.

اگر هیچ شناسه‌ای قابل تشخیص نباشد، رشته "unknown" برگردانده می‌شود.

inspect-get-package-format

inspect-get-package-format root

این تابع و "inspect-get-package-management" قالب بسته و ابزار مدیریت بسته‌ای را که توسط سیستم‌عامل بازرسی‌شده استفاده می‌شود، برمی‌گردانند. برای مثال برای فدورا این توابع "rpm" (قالب بسته)، و "yum" یا "dnf" (مدیریت بسته) را برمی‌گردانند.

اگر نتوانیم قالب بسته را تعیین کنیم یا اگر سیستم‌عامل سیستم بسته‌بندی واقعی نداشته باشد (مانند ویندوز)، این تابع رشته "unknown" را برمی‌گرداند.

رشته‌های ممکن عبارتند از: "rpm"، "deb"، "ebuild"، "pisi"، "pacman"، "pkgsrc"، "apk"، "xbps". نسخه‌های بعدی libguestfs ممکن است رشته‌های دیگری را برگردانند.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-package-management

inspect-get-package-management root

"inspect-get-package-format" و این تابع قالب بسته و ابزار مدیریت بسته استفاده‌شده توسط سیستم‌عامل بازرسی‌شده را برمی‌گردانند. برای مثال برای فدورا این توابع "rpm" (قالب بسته)، و "yum" یا "dnf" (مدیریت بسته) را برمی‌گردانند.

اگر نتوانیم ابزار مدیریت بسته را تعیین کنیم یا اگر سیستم‌عامل سیستم بسته‌بندی واقعی نداشته باشد (مانند ویندوز)، این تابع رشته "unknown" را برمی‌گرداند.

رشته‌های ممکن عبارتند از: "yum"، "dnf"، "up2date"، "apt" (برای تمام مشتقات دبیان)، "portage"، "pisi"، "pacman"، "urpmi"، "zypper"، "apk"، "xbps". نسخه‌های بعدی libguestfs ممکن است رشته‌های دیگری را برگردانند.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-product-name

inspect-get-product-name root

نام محصول سیستم‌عامل بازرسی‌شده را برمی‌گرداند. نام محصول عموماً یک رشته آزاد است که می‌تواند به کاربر نمایش داده شود، اما نباید توسط برنامه‌ها پردازش شود.

اگر نام محصول قابل تشخیص نباشد، رشته "unknown" برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-product-variant

inspect-get-product-variant root

گونه محصول (product variant) سیستم‌عامل بازرسی‌شده را برمی‌گرداند.

برای مهمان‌های ویندوز، این مقدار کلید رجیستری "HKLM\Software\Microsoft\Windows NT\CurrentVersion" "InstallationType" را برمی‌گرداند که معمولاً رشته‌ای مانند "Client" یا "Server" است (مقادیر دیگر نیز ممکن است). از این مورد می‌توان برای تشخیص نسخه‌های مصرف‌کننده و سازمانی ویندوز که شماره نسخه یکسانی دارند استفاده کرد (برای مثال، Windows 7 و Windows 2008 Server هر دو نسخه 6.1 هستند، اما اولی "Client" و دومی "Server" است).

برای مهمان‌های لینوکس سازمانی، در آینده قصد داریم این مقدار گونه محصول مانند "Desktop"، "Server" و غیره را برگرداند. اما در حال حاضر این ویژگی پیاده‌سازی نشده است.

اگر گونه محصول قابل تشخیص نباشد، رشته "unknown" برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید. همچنین ببینید "inspect-get-product-name" و "inspect-get-major-version".

inspect-get-roots

inspect-get-roots

این تابع روشی مناسب برای دریافت فهرست دستگاه‌های ریشه است، همان‌طور که از فراخوانی قبلی به "inspect-os" بازگردانده شده بود، اما بدون تکرار مجدد کل فرآیند بازرسی.

اگر هیچ دستگاه ریشه‌ای یافت نشده باشد یا فراخوان "inspect-os" را فراخوانی نکرده باشد، این تابع یک فهرست خالی برمی‌گرداند.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-type

inspect-get-type root

نوع سیستم‌عامل بازرسی‌شده را برمی‌گرداند. انواع تعریف‌شده در حال حاضر عبارتند از:

"linux"

هر سیستم‌عامل مبتنی بر لینوکس.

"windows"

هر سیستم‌عامل مایکروسافت ویندوز.

"freebsd"

فری‌بی‌اس‌دی (FreeBSD).

"netbsd"

نت‌بی‌اس‌دی (NetBSD).

"openbsd"

اوپن‌بی‌اس‌دی (OpenBSD).

"hurd"

گنو/هرد (GNU/Hurd).

"dos"

ام‌اس-داس (MS-DOS)، فری‌داس (FreeDOS) و دیگران.

"minix"

مینیکس (MINIX).

"unknown"

نوع سیستم‌عامل قابل تشخیص نبود.

نسخه‌های بعدی libguestfs ممکن است رشته‌های دیگری را در اینجا برگردانند. فراخوان باید آماده رسیدگی به هر رشته‌ای باشد.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-windows-current-control-set

inspect-get-windows-current-control-set root

مقدار CurrentControlSet ویندوز مهمان بازرسی‌شده را برمی‌گرداند. CurrentControlSet نام کلید رجیستری مانند "ControlSet001" است.

این فراخوانی فرض می‌کند که مهمان ویندوز است و رجیستری از طریق بازرسی قابل بررسی بوده است. اگر این‌طور نباشد، یک خطا برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-windows-group-policy

inspect-get-windows-group-policy root

اگر مهمان ویندوز دارای خط‌مشی گروهی (group policy) باشد، مقدار true برمی‌گرداند. خط‌مشی گروهی می‌تواند با نصب درایور دستگاه تداخل داشته باشد و از کارکرد ویژگی‌های libguestfs مانند تزریق درایور جلوگیری کند.

توجه داشته باشید که وجود خط‌مشی گروهی فقط نشانه‌ای از این است که ممکن است مشکلی در نصب درایور وجود داشته باشد. از آنجا که خط‌مشی گروهی بسیار پیچیده است و جنبه‌های مختلف پیکربندی ویندوز را پوشش می‌دهد، و ما هیچ تلاشی برای تجزیه آن نمی‌کنیم، وجود خط‌مشی گروهی فقط باید یک هشدار ایجاد کند.

این فراخوانی فرض می‌کند که مهمان ویندوز است و رجیستری از طریق بازرسی قابل بررسی بوده است. اگر این‌طور نباشد، یک خطا برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-windows-software-hive

inspect-get-windows-software-hive root

مسیر هایو (فایل باینری رجیستری ویندوز) متناظر با HKLM\SOFTWARE را برمی‌گرداند.

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

می‌توانید از "hivex-open" برای خواندن یا نوشتن در هایو استفاده کنید.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-windows-system-hive

inspect-get-windows-system-hive root

مسیر هایو (فایل باینری رجیستری ویندوز) متناظر با HKLM\SYSTEM را برمی‌گرداند.

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

می‌توانید از "hivex-open" برای خواندن یا نوشتن در هایو استفاده کنید.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-get-windows-systemroot

inspect-get-windows-systemroot root

پوشه systemroot ویندوز مهمان بازرسی‌شده را برمی‌گرداند. پوشه systemroot یک مسیر دایرکتوری مانند /WINDOWS است.

این فراخوانی فرض می‌کند که مهمان ویندوز است و systemroot از طریق بازرسی قابل تعیین بوده است. اگر این‌طور نباشد، یک خطا برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-is-live

inspect-is-live root

این تابع منسوخ شده و همیشه "false" برمی‌گرداند.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

این تابع منسوخ شده است. جایگزینی وجود ندارد. برای اطلاعات بیشتر به مستندات API در guestfs(3) مراجعه کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

inspect-is-multipart

inspect-is-multipart root

این تابع منسوخ شده و همیشه "false" برمی‌گرداند.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

این تابع منسوخ شده است. جایگزینی وجود ندارد. برای اطلاعات بیشتر به مستندات API در guestfs(3) مراجعه کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

inspect-is-netinst

inspect-is-netinst root

این تابع منسوخ شده و همیشه "false" برمی‌گرداند.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

این تابع منسوخ شده است. جایگزینی وجود ندارد. برای اطلاعات بیشتر به مستندات API در guestfs(3) مراجعه کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

inspect-list-applications

inspect-list-applications root

فهرست برنامه‌های نصب‌شده در سیستم‌عامل را برمی‌گرداند.

نکته: این فراخوانی متفاوت از سایر بخش‌های API بازرسی کار می‌کند. شما باید قبل از فراخوانی این دستور، "inspect-os" و سپس "inspect-get-mountpoints" را فراخوانی کرده و دیسک‌ها را سوار کنید. فهرست کردن برنامه‌ها عملیاتی به مراتب دشوارتر است که نیاز به دسترسی به کل فایل‌سیستم دارد. همچنین توجه داشته باشید که برخلاف سایر فراخوانی‌های "inspect-get-*" که فقط داده‌های کش‌شده در هندل libguestfs را برمی‌گردانند، این فراخوانی در واقع بخش‌هایی از فایل‌سیستم‌های سوارشده را در طول فراخوانی می‌خواند.

اگر کد بازرسی قادر به تعیین فهرست برنامه‌ها نباشد، یک فهرست خالی برمی‌گرداند.

ساختار برنامه شامل فیلدهای زیر است:

"app_name"

نام برنامه. برای مهمان‌های لینوکس، این نام بسته است.

"app_display_name"

نام نمایشی برنامه، که گاهی اوقات متناسب با زبان نصب سیستم‌عامل مهمان بومی‌سازی شده است.

در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود. فراخوان‌هایی که نیاز به نمایش چیزی دارند می‌توانند به جای آن از "app_name" استفاده کنند.

"app_epoch"

برای مدیران بسته‌ای که از epoch استفاده می‌کنند، این فیلد شامل epoch بسته است (یک عدد صحیح). در صورت عدم دسترسی، به صورت 0 برگردانده می‌شود.

"app_version"

رشته نسخه برنامه یا بسته. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app_release"

رشته انتشار (release) برنامه یا بسته، برای مدیران بسته‌ای که از آن استفاده می‌کنند. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app_install_path"

مسیر نصب برنامه (در سیستم‌های عاملی مانند ویندوز که از مسیرهای نصب استفاده می‌کنند). این مسیر در قالبی است که توسط سیستم‌عامل مهمان استفاده می‌شود و یک مسیر libguestfs نیست.

در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app_trans_path"

مسیر نصب ترجمه‌شده به یک مسیر libguestfs. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app_publisher"

نام ناشر برنامه، برای مدیران بسته‌ای که از آن استفاده می‌کنند. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app_url"

نشانی وب (مثلاً URL بالادست) برنامه. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app_source_package"

برای سیستم‌های بسته‌بندی که از آن پشتیبانی می‌کنند، نام بسته منبع. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app_summary"

یک توضیح کوتاه (معمولاً یک‌خطی) از برنامه یا بسته. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app_description"

توضیحات طولانی‌تر از برنامه یا بسته. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "inspect-list-applications2" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آن‌ها نشان می‌دهد که در استفاده صحیح از این توابع مشکلاتی وجود دارد.

inspect-list-applications2

inspect-list-applications2 root

فهرست برنامه‌های نصب‌شده در سیستم‌عامل را برمی‌گرداند.

نکته: این فراخوانی متفاوت از سایر بخش‌های API بازرسی کار می‌کند. شما باید قبل از فراخوانی این دستور، "inspect-os" و سپس "inspect-get-mountpoints" را فراخوانی کرده و دیسک‌ها را سوار کنید. فهرست کردن برنامه‌ها عملیاتی به مراتب دشوارتر است که نیاز به دسترسی به کل فایل‌سیستم دارد. همچنین توجه داشته باشید که برخلاف سایر فراخوانی‌های "inspect-get-*" که فقط داده‌های کش‌شده در هندل libguestfs را برمی‌گردانند، این فراخوانی در واقع بخش‌هایی از فایل‌سیستم‌های سوارشده را در طول فراخوانی می‌خواند.

اگر کد بازرسی قادر به تعیین فهرست برنامه‌ها نباشد، یک فهرست خالی برمی‌گرداند.

ساختار برنامه شامل فیلدهای زیر است:

"app2_name"

نام برنامه. برای مهمان‌های لینوکس، این نام بسته است.

"app2_display_name"

نام نمایشی برنامه، که گاهی اوقات متناسب با زبان نصب سیستم‌عامل مهمان بومی‌سازی شده است.

در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود. فراخوان‌هایی که نیاز به نمایش چیزی دارند می‌توانند به جای آن از "app2_name" استفاده کنند.

"app2_epoch"

برای مدیران بسته‌ای که از epoch استفاده می‌کنند، این فیلد شامل epoch بسته است (یک عدد صحیح). در صورت عدم دسترسی، به صورت 0 برگردانده می‌شود.

"app2_version"

رشته نسخه برنامه یا بسته. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_release"

رشته انتشار (release) برنامه یا بسته، برای مدیران بسته‌ای که از آن استفاده می‌کنند. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_arch"

رشته معماری برنامه یا بسته، برای مدیران بسته‌ای که از آن استفاده می‌کنند. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_install_path"

مسیر نصب برنامه (در سیستم‌های عاملی مانند ویندوز که از مسیرهای نصب استفاده می‌کنند). این مسیر در قالبی است که توسط سیستم‌عامل مهمان استفاده می‌شود و یک مسیر libguestfs نیست.

در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_trans_path"

مسیر نصب ترجمه‌شده به یک مسیر libguestfs. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_publisher"

نام ناشر برنامه، برای مدیران بسته‌ای که از آن استفاده می‌کنند. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_url"

نشانی وب (مثلاً URL بالادست) برنامه. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_source_package"

برای سیستم‌های بسته‌بندی که از آن پشتیبانی می‌کنند، نام بسته منبع. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_summary"

یک توضیح کوتاه (معمولاً یک‌خطی) از برنامه یا بسته. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_description"

توضیحات طولانی‌تر از برنامه یا بسته. در صورت عدم دسترسی، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

"app2_class"

طبقه‌بندی یا کاربرد اصلی این برنامه. در حال حاضر تنها طبقه‌بندی تعریف‌شده "antivirus" برای نرم‌افزارهای ضدویروس ویندوز است. در صورت ناشناخته بودن، این مقدار به صورت یک رشته خالی "" برگردانده می‌شود.

لطفاً برای جزئیات بیشتر "INSPECTION" در guestfs(3) را بخوانید.

inspect-os

inspect-os

این تابع از سایر توابع libguestfs و روش‌های اکتشافی (heuristics) خاصی برای بازرسی دیسک(ها) (معمولاً دیسک‌های متعلق به یک ماشین مجازی) جهت یافتن سیستم‌عامل‌ها استفاده می‌کند.

اگر هیچ سیستم‌عاملی پیدا نشود، فهرست بازگردانده‌شده خالی خواهد بود.

اگر یک سیستم‌عامل پیدا شود، این تابع فهرستی با یک عنصر بازمی‌گرداند که نام فایل‌سیستم ریشه (root) آن سیستم‌عامل است. همچنین امکان دارد این تابع فهرستی شامل بیش از یک عنصر بازگرداند که نشان‌دهنده یک ماشین مجازی با بوت دوگانه (dual-boot) یا چندگانه (multi-boot) است و هر عنصر آن فایل‌سیستم ریشه یکی از سیستم‌عامل‌ها خواهد بود.

می‌توانید رشته(های) ریشه بازگردانده‌شده را به سایر توابع "inspect-get-*" ارسال کنید تا اطلاعات بیشتری درباره هر سیستم‌عامل، مانند نام و نسخه، دریافت نمایید.

این تابع از سایر قابلیت‌های libguestfs مانند "mount-ro" و "umount-all" به منظور سوار کردن و پیاده کردن فایل‌سیستم‌ها و بررسی محتویات استفاده می‌کند. این تابع باید زمانی فراخوانی شود که در حال حاضر هیچ دیسکی سوار نشده باشد. این تابع همچنین ممکن است از Augeas استفاده کند، بنابراین هر هندل موجود Augeas بسته خواهد شد.

این تابع نمی‌تواند دیسک‌های رمزگذاری‌شده را رمزگشایی کند. در صورت رمزگذاری بودن دیسک، فراخواننده باید ابتدا این کار را (با ارائه کلیدهای لازم) انجام دهد.

لطفاً برای جزئیات بیشتر بخش "INSPECTION" در guestfs(3) را مطالعه کنید.

همچنین "list-filesystems" را ببینید.

is-blockdev

is-blockdev-opts

is-blockdev path [followsymlinks:true|false]

این دستور تنها در صورتی مقدار "true" را بازمی‌گرداند که یک دستگاه بلوکی (block device) با نام "path" داده‌شده وجود داشته باشد.

اگر فلگ اختیاری "followsymlinks" برابر با true باشد، آن‌گاه یک پیوند نمادین (یا زنجیره‌ای از پیوندهای نمادین) که به یک دستگاه بلوکی ختم شود نیز باعث می‌شود تابع مقدار true را بازگرداند.

این فراخوانی تنها فایل‌های درون فایل‌سیستم میهمان را بررسی می‌کند. پارتیشن‌ها و دستگاه‌های بلوکی Libguestfs (مانند /dev/sda) نمی‌توانند به عنوان پارامتر "path" در این فراخوانی استفاده شوند.

همچنین "stat" را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

is-chardev

is-chardev-opts

is-chardev path [followsymlinks:true|false]

این دستور تنها در صورتی مقدار "true" را بازمی‌گرداند که یک دستگاه نویسه‌ای (character device) با نام "path" داده‌شده وجود داشته باشد.

اگر فلگ اختیاری "followsymlinks" برابر با true باشد، آن‌گاه یک پیوند نمادین (یا زنجیره‌ای از پیوندهای نمادین) که به یک دستگاه نویسه‌ای ختم شود نیز باعث می‌شود تابع مقدار true را بازگرداند.

همچنین "stat" را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

is-config

is-config

این دستور تنها در صورتی مقدار true را بازمی‌گرداند که این هندل در حال پیکربندی باشد (در وضعیت "CONFIG").

برای اطلاعات بیشتر درباره وضعیت‌ها، guestfs(3) را ببینید.

is-dir

is-dir-opts

is-dir path [followsymlinks:true|false]

این دستور تنها در صورتی مقدار "true" را بازمی‌گرداند که دایرکتوری‌ای با نام "path" داده‌شده وجود داشته باشد. توجه داشته باشید که برای اشیاء دیگر مانند فایل‌ها مقدار false را بازمی‌گرداند.

اگر فلگ اختیاری "followsymlinks" برابر با true باشد، آن‌گاه یک پیوند نمادین (یا زنجیره‌ای از پیوندهای نمادین) که به یک دایرکتوری ختم شود نیز باعث می‌شود تابع مقدار true را بازگرداند.

همچنین "stat" را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

is-fifo

is-fifo-opts

is-fifo path [followsymlinks:true|false]

این دستور تنها در صورتی مقدار "true" را بازمی‌گرداند که یک FIFO (لوله نام‌گذاری‌شده) با نام "path" داده‌شده وجود داشته باشد.

اگر فلگ اختیاری "followsymlinks" برابر با true باشد، آن‌گاه یک پیوند نمادین (یا زنجیره‌ای از پیوندهای نمادین) که به یک FIFO ختم شود نیز باعث می‌شود تابع مقدار true را بازگرداند.

همچنین "stat" را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

is-file

is-file-opts

is-file path [followsymlinks:true|false]

این دستور تنها در صورتی مقدار "true" را بازمی‌گرداند که یک فایل معمولی با نام "path" داده‌شده وجود داشته باشد. توجه داشته باشید که برای اشیاء دیگر مانند دایرکتوری‌ها مقدار false را بازمی‌گرداند.

اگر فلگ اختیاری "followsymlinks" برابر با true باشد، آن‌گاه یک پیوند نمادین (یا زنجیره‌ای از پیوندهای نمادین) که به یک فایل ختم شود نیز باعث می‌شود تابع مقدار true را بازگرداند.

همچنین "stat" را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

is-lv

is-lv mountable

این دستور بررسی می‌کند که آیا "mountable" یک حجم منطقی (logical volume) است یا خیر، و تنها در صورتی مقدار true را بازمی‌گرداند که چنین باشد.

is-socket

is-socket-opts

is-socket path [followsymlinks:true|false]

این دستور تنها در صورتی مقدار "true" را بازمی‌گرداند که یک سوکت دامنه یونیکس (Unix domain socket) با نام "path" داده‌شده وجود داشته باشد.

اگر فلگ اختیاری "followsymlinks" برابر با true باشد، آن‌گاه یک پیوند نمادین (یا زنجیره‌ای از پیوندهای نمادین) که به یک سوکت ختم شود نیز باعث می‌شود تابع مقدار true را بازگرداند.

همچنین "stat" را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

is-symlink

is-symlink path

این دستور تنها در صورتی مقدار "true" را بازمی‌گرداند که یک پیوند نمادین با نام "path" داده‌شده وجود داشته باشد.

همچنین "stat" را ببینید.

is-whole-device

is-whole-device device

این دستور تنها در صورتی مقدار "true" را بازمی‌گرداند که "device" به یک دستگاه بلوکی کامل اشاره داشته باشد؛ یعنی پارتیشن یا دستگاه منطقی نباشد.

is-zero

is-zero path

این دستور تنها در صورتی مقدار true را بازمی‌گرداند که فایل وجود داشته باشد و فایل خالی باشد یا تمام بایت‌های آن صفر باشد.

is-zero-device

is-zero-device device

این دستور تنها در صورتی مقدار true را بازمی‌گرداند که دستگاه وجود داشته باشد و شامل تمام بایت‌های صفر باشد.

توجه داشته باشید که برای دستگاه‌های بزرگ اجرای این دستور ممکن است زمان زیادی ببرد.

isoinfo

isoinfo isofile

این دستور مشابه "isoinfo-device" است با این تفاوت که برای فایل‌های ISO قرارگرفته درون یک فایل‌سیستم سوارشده دیگر کار می‌کند. توجه داشته باشید در حالت متداول که فایل ISO را به عنوان دستگاه libguestfs اضافه کرده‌اید، نباید این دستور را فراخوانی کنید؛ در عوض باید "isoinfo-device" را فراخوانی نمایید.

isoinfo-device

isoinfo-device device

پارامتر "device" یک دستگاه ISO است. این دستور ساختاری از اطلاعات خوانده‌شده از توصیف‌گر حجم اصلی (primary volume descriptor - معادل ابربلوک در ISO) دستگاه را بازمی‌گرداند.

معمولاً برای تحلیل فایل‌های ISO استفاده از دستور isoinfo(1) با گزینه -d روی میزبان به جای استفاده از libguestfs کارآمدتر است.

برای اطلاعات بیشتر درباره فیلدهای توصیف‌گر حجم اصلی، نشانی زیر را ببینید: https://wiki.osdev.org/ISO_9660#The_Primary_Volume_Descriptor

journal-close

journal-close

هندل ژورنال را می‌بندد.

این دستور به قابلیت "journal" وابسته است. همچنین "feature-available" را ببینید.

journal-get

journal-get

مدخل فعلی ژورنال را می‌خواند. این دستور تمام فیلدهای ژورنال را به صورت مجموعه‌ای از جفت‌های "(attrname, attrval)" بازمی‌گرداند. "attrname" نام فیلد (یک رشته) است.

مقدار "attrval" مقدار فیلد (یک باینری بلاب، اغلب ولی نه همیشه یک رشته) است. لطفاً توجه داشته باشید که "attrval" یک آرایه بایتی است، نه یک رشته C با پایان \0.

طول داده ممکن است به آستانه داده محدود (کوتاه) شود (ببینید: "journal-set-data-threshold" و "journal-get-data-threshold").

اگر آستانه داده را روی نامحدود (0) تنظیم کنید، آن‌گاه این فراخوانی می‌تواند مدخل ژورنال با هر اندازه‌ای را بخواند، یعنی توسط پروتکل libguestfs محدود نمی‌شود.

این دستور به قابلیت "journal" وابسته است. همچنین "feature-available" را ببینید.

journal-get-data-threshold

journal-get-data-threshold

آستانه داده فعلی را برای خواندن مدخل‌های ژورنال دریافت می‌کند. این یک راهنمایی برای ژورنال است که هنگام خواندن فیلدهای داده می‌تواند آن‌ها را به این اندازه کوتاه کند (همچنین توجه داشته باشید که ممکن است آن‌ها را کوتاه نکند). اگر این تابع مقدار 0 را بازگرداند، آستانه نامحدود است.

همچنین "journal-set-data-threshold" را ببینید.

این دستور به قابلیت "journal" وابسته است. همچنین "feature-available" را ببینید.

journal-get-realtime-usec

journal-get-realtime-usec

مهرزمانی بیدرنگ (ساعت واقعی) مدخل فعلی ژورنال را دریافت می‌کند.

این دستور به قابلیت "journal" وابسته است. همچنین "feature-available" را ببینید.

journal-next

journal-next

به مدخل بعدی ژورنال می‌رود. پس از باز کردن هندل، قبل از این که بتوانید داده‌ها را بخوانید، باید حداقل یک بار این تابع را فراخوانی کنید.

مقدار بولی بازگردانده‌شده مشخص می‌کند که آیا رکوردهای بیشتری در ژورنال برای خواندن وجود دارد یا خیر. مقدار "true" به این معنی است که می‌توانید رکورد بعدی را بخوانید (مثلاً با استفاده از "journal-get")، و "false" یعنی به انتهای ژورنال رسیده‌اید.

این دستور به قابلیت "journal" وابسته است. همچنین "feature-available" را ببینید.

journal-open

journal-open directory

ژورنال systemd واقع در directory را باز می‌کند. هر هندل ژورنال که قبلاً باز شده باشد بسته می‌شود.

محتویات ژورنال را می‌توان با استفاده از "journal-next" و "journal-get" خواند.

پس از پایان استفاده از ژورنال، باید با فراخوانی "journal-close" هندل را ببندید.

این دستور به قابلیت "journal" وابسته است. همچنین "feature-available" را ببینید.

journal-set-data-threshold

journal-set-data-threshold threshold

آستانه داده را برای خواندن مدخل‌های ژورنال تنظیم می‌کند. این یک راهنمایی برای ژورنال است که هنگام خواندن فیلدهای داده می‌تواند آن‌ها را به این اندازه کوتاه کند (همچنین توجه داشته باشید که ممکن است آن‌ها را کوتاه نکند). اگر این مقدار را روی 0 تنظیم کنید، آستانه نامحدود خواهد بود.

همچنین "journal-get-data-threshold" را ببینید.

این دستور به قابلیت "journal" وابسته است. همچنین "feature-available" را ببینید.

journal-skip

journal-skip skip

در ژورنال به جلو ("skip ≥ 0") یا به عقب ("skip < 0") پرش می‌کند.

تعداد مدخل‌هایی که واقعاً پرش شده‌اند بازگردانده می‌شود (توجه کنید "rskip ≥ 0"). اگر این مقدار با قدر مطلق پارامتر پرش ("|skip|") که ارسال کرده‌اید برابر نباشد، به این معنی است که به انتهای ژورنال یا ابتدای آن رسیده‌اید.

این دستور به قابلیت "journal" وابسته است. همچنین "feature-available" را ببینید.

kill-subprocess

kill-subprocess

هایپروایزر را متوقف می‌کند (می‌کشد).

این دستور را فراخوانی نکنید. در عوض "shutdown" را ببینید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "shutdown" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

launch

run

launch

باید این دستور را پس از پیکربندی هندل (مثلاً افزودن درایوها) اما قبل از انجام هرگونه عملیاتی فراخوانی کنید.

دستور "launch" را دو بار روی یک هندل یکسان فراخوانی نکنید. اگرچه این کار (به دلایل تاریخی) خطایی تولید نمی‌کند، رفتار دقیق هنگام انجام این کار به خوبی تعریف نشده است. ایجاد هندل‌ها هزینه بسیار کمی دارد، بنابراین برای هر بار راه‌اندازی یک هندل جدید ایجاد کنید.

lchown

lchown owner group path

مالک فایل را به "owner" و گروه آن را به "group" تغییر می‌دهد. این دستور مانند "chown" عمل می‌کند، اما اگر "path" یک پیوند نمادین باشد، خود پیوند تغییر می‌کند نه هدف پیوند.

تنها uid و gid عددی پشتیبانی می‌شوند. اگر می‌خواهید از نام‌ها استفاده کنید، باید خودتان فایل گذرواژه را پیدا و تجزیه کنید (پشتیبانی Augeas این کار را نسبتاً آسان می‌کند).

ldmtool-create-all

ldmtool-create-all

این تابع تمام دستگاه‌های بلوکی را برای یافتن حجم‌ها و پارتیشن‌های دیسک پویا (dynamic disk) ویندوز پویش می‌کند و برای هر موردی که یافت شود دستگاه‌هایی ایجاد می‌نماید.

برای بازگرداندن تمام دستگاه‌ها، "list-ldm-volumes" و "list-ldm-partitions" را فراخوانی کنید.

توجه داشته باشید که معمولاً نیازی نیست این دستور را به صراحت فراخوانی کنید، زیرا این کار به طور خودکار در زمان "launch" انجام می‌شود.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-diskgroup-disks

ldmtool-diskgroup-disks diskgroup

دیسک‌های موجود در یک گروه دیسک پویای ویندوز را بازمی‌گرداند. پارامتر "diskgroup" باید GUID یک گروه دیسک باشد، یعنی یک عنصر از فهرستی که توسط "ldmtool-scan" بازگردانده شده است.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-diskgroup-name

ldmtool-diskgroup-name diskgroup

نام یک گروه دیسک پویای ویندوز را بازمی‌گرداند. پارامتر "diskgroup" باید GUID یک گروه دیسک باشد، یعنی یک عنصر از فهرستی که توسط "ldmtool-scan" بازگردانده شده است.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-diskgroup-volumes

ldmtool-diskgroup-volumes diskgroup

حجم‌های موجود در یک گروه دیسک پویای ویندوز را بازمی‌گرداند. پارامتر "diskgroup" باید GUID یک گروه دیسک باشد، یعنی یک عنصر از فهرستی که توسط "ldmtool-scan" بازگردانده شده است.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-remove-all

ldmtool-remove-all

این دستور در اصل نقطه مقابل "ldmtool-create-all" است. این دستور نگاشت‌های device mapper را برای تمام حجم‌های دیسک پویای ویندوز حذف می‌کند.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-scan

ldmtool-scan

این تابع دیسک‌های پویای ویندوز را پویش می‌کند. این تابع فهرستی از شناسه‌ها (GUIDها) را برای تمام گروه‌های دیسکِ پیدا شده بازمی‌گرداند. این شناسه‌ها را می‌توان به سایر توابع "ldmtool-*" ارسال کرد.

این تابع تمام دستگاه‌های بلوکی را پویش می‌کند. برای پویش زیرمجموعه‌ای از دستگاه‌های بلوکی، به جای آن "ldmtool-scan-devices" را فراخوانی کنید.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-scan-devices

ldmtool-scan-devices 'devices ...'

این تابع دیسک‌های پویای ویندوز را پویش می‌کند. این تابع فهرستی از شناسه‌ها (GUIDها) را برای تمام گروه‌های دیسکِ پیدا شده بازمی‌گرداند. این شناسه‌ها را می‌توان به سایر توابع "ldmtool-*" ارسال کرد.

پارامتر "devices" فهرستی از دستگاه‌های بلوکی است که پویش می‌شوند. اگر این فهرست خالی باشد، تمام دستگاه‌های بلوکی پویش می‌شوند.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-volume-hint

ldmtool-volume-hint diskgroup volume

فیلد hint حجم با نام "volume" را در گروه دیسک با GUID "diskgroup" بازمی‌گرداند. این فیلد ممکن است تعریف نشده باشد، که در این صورت رشته خالی بازگردانده می‌شود. فیلد hint اغلب، هرچند نه همیشه، نام یک درایو ویندوز است، مانند "E:".

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-volume-partitions

ldmtool-volume-partitions diskgroup volume

فهرست پارتیشن‌های موجود در حجم با نام "volume" در گروه دیسک با GUID "diskgroup" را بازمی‌گرداند.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

ldmtool-volume-type

ldmtool-volume-type diskgroup volume

نوع حجم با نام "volume" را در گروه دیسک با GUID "diskgroup" بازمی‌گرداند.

انواع ممکن حجم که می‌توانند در اینجا بازگردانده شوند عبارتند از: "simple"، "spanned"، "striped"، "mirrored"، "raid5". انواع دیگری نیز ممکن است بازگردانده شوند.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

lgetxattr

lgetxattr path name

یک صفت گسترش‌یافته منفرد با نام "name" را از فایل "path" دریافت می‌کند. اگر "path" یک پیوند نمادین باشد، این فراخوانی صفت گسترش‌یافته را از خود پیوند نمادین بازمی‌گرداند.

معمولاً بهتر است همه صفت‌های گسترش‌یافته یک فایل را به یک‌باره با فراخوانی "getxattrs" دریافت کنید. با این حال برخی پیاده‌سازی‌های فایل‌سیستم لینوکس دارای اشکال هستند و راهی برای فهرست کردن صفت‌ها ارائه نمی‌دهند. برای این فایل‌سیستم‌ها (به ویژه ntfs-3g) باید نام‌های صفت‌های گسترش‌یافته مورد نظر خود را از قبل بدانید و این تابع را فراخوانی کنید.

مقادیر صفت‌های گسترش‌یافته بلاب‌هایی از داده‌های باینری هستند. اگر صفت گسترش‌یافته‌ای با نام "name" وجود نداشته باشد، این تابع خطا بازمی‌گرداند.

همچنین ببینید: "lgetxattrs"، "getxattr"، attr(5).

این دستور به قابلیت "linuxxattrs" وابسته است. همچنین "feature-available" را ببینید.

lgetxattrs

lgetxattrs path

این دستور مشابه "getxattrs" است، اما اگر "path" یک پیوند نمادین باشد، صفت‌های گسترش‌یافته خودِ پیوند را بازمی‌گرداند.

این دستور به قابلیت "linuxxattrs" وابسته است. همچنین "feature-available" را ببینید.

list-9p

list-9p

این فراخوانی هیچ کاری انجام نمی‌دهد و یک خطا بازمی‌گرداند.

این تابع منسوخ شده است. هیچ جایگزینی وجود ندارد. برای اطلاعات بیشتر به مستندات API در guestfs(3) مراجعه کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

list-devices

list-devices

تمام دستگاه‌های بلوکی را فهرست می‌کند.

نام‌های کامل دستگاه‌های بلوکی بازگردانده می‌شوند، مانند /dev/sda.

همچنین "list-filesystems" را ببینید.

list-disk-labels

list-disk-labels

اگر درایوها را با استفاده از پارامتر اختیاری "label" در "add-drive-opts" اضافه کنید، می‌توانید از این فراخوانی برای نگاشت میان برچسب‌های دیسک و نام‌های خام دستگاه‌های بلوکی و پارتیشن‌ها (مانند /dev/sda و /dev/sda1) استفاده کنید.

این دستور یک جدول درهم‌سازی (hashtable) بازمی‌گرداند که کلیدهای آن برچسب‌های دیسک (بدون پیشوند /dev/disk/guestfs) و مقادیر آن نام‌های خام و کامل دستگاه‌های بلوکی و پارتیشن‌ها هستند (مانند /dev/sda و /dev/sda1).

list-dm-devices

list-dm-devices

تمام دستگاه‌های device mapper را فهرست می‌کند.

فهرست بازگردانده‌شده شامل دستگاه‌های /dev/mapper/* است، مانند مواردی که با فراخوانی قبلی "luks-open" ایجاد شده‌اند.

دستگاه‌های device mapper که مربوط به حجم‌های منطقی هستند در این فهرست بازگردانده نمی‌شوند. اگر می‌خواهید حجم‌های منطقی را فهرست کنید، "lvs" را فراخوانی نمایید.

list-filesystems

list-filesystems

این دستور بازرسی به دنبال فایل‌سیستم‌ها روی پارتیشن‌ها، دستگاه‌های بلوکی و حجم‌های منطقی می‌گردد و فهرستی از رشته‌های "mountables" حاوی فایل‌سیستم‌ها و نوع آن‌ها بازمی‌گرداند.

مقدار بازگردانده‌شده یک هش است که کلیدهای آن دستگاه‌های حاوی فایل‌سیستم و مقادیر آن نوع فایل‌سیستم‌ها هستند. برای مثال:

"/dev/sda1" => "ntfs"
"/dev/sda2" => "ext2"
"/dev/vg_guest/lv_root" => "ext4"
"/dev/vg_guest/lv_swap" => "swap"

کلید لزوماً یک دستگاه بلوکی نیست؛ همچنین می‌تواند یک رشته مبهم ‘قابل سوار شدن’ (mountable) باشد که می‌توان آن را به "mount" ارسال کرد.

مقدار می‌تواند مقدار ویژه "unknown" را داشته باشد، به این معنی که محتوای دستگاه نامشخص یا خالی است. "swap" به معنی پارتیشن سواپ لینوکس است.

در libguestfs ≤ 1.36 این دستور سایر دستورات libguestfs را اجرا می‌کرد، که ممکن بود شامل "mount" و "umount" باشد، بنابراین باید این دستور را بلافاصله پس از راه‌اندازی و تنها زمانی که هیچ چیز دیگری سوار نشده بود استفاده می‌کردید. این محدودیت در libguestfs ≥ 1.38 برداشته شده است.

همه فایل‌سیستم‌های بازگردانده‌شده قابل سوار شدن نخواهند بود. به ویژه پارتیشن‌های سواپ در این فهرست بازگردانده می‌شوند. همچنین این دستور بررسی نمی‌کند که آیا هر فایل‌سیستم پیدا شده معتبر و قابل سوار شدن است یا خیر، و برخی فایل‌سیستم‌ها ممکن است قابل سوار شدن باشند اما به گزینه‌های خاصی نیاز داشته باشند. ممکن است فایل‌سیستم‌ها همگی متعلق به یک سیستم‌عامل منطقی واحد نباشند (از "inspect-os" برای جستجوی سیستم‌عامل‌ها استفاده کنید).

list-ldm-partitions

list-ldm-partitions

این تابع تمام پارتیشن‌های دیسک پویای ویندوز را که در زمان راه‌اندازی پیدا شده‌اند بازمی‌گرداند. این دستور فهرستی از نام دستگاه‌ها را بازمی‌گرداند.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

list-ldm-volumes

list-ldm-volumes

این تابع تمام حجم‌های دیسک پویای ویندوز را که در زمان راه‌اندازی پیدا شده‌اند بازمی‌گرداند. این دستور فهرستی از نام دستگاه‌ها را بازمی‌گرداند.

این دستور به قابلیت "ldm" وابسته است. همچنین "feature-available" را ببینید.

list-md-devices

list-md-devices

تمام دستگاه‌های md لینوکس را فهرست می‌کند.

list-partitions

list-partitions

تمام پارتیشن‌های شناسایی‌شده روی تمام دستگاه‌های بلوکی را فهرست می‌کند.

نام‌های کامل دستگاه‌های پارتیشن بازگردانده می‌شوند، مانند /dev/sda1.

این دستور حجم‌های منطقی را بازنمی‌گرداند. برای آن منظور باید "lvs" را فراخوانی کنید.

همچنین "list-filesystems" را ببینید.

ll

ll directory

فایل‌های موجود در directory را (نسبت به دایرکتوری ریشه، مسیر کاری فعلی وجود ندارد) در قالب "ls -la" فهرست می‌کند.

این دستور بیشتر برای نشست‌های تعاملی مفید است. قرار نیست رشته خروجی را تجزیه کنید.

llz

llz directory

فایل‌های موجود در directory را در قالب "ls -laZ" فهرست می‌کند.

این دستور بیشتر برای نشست‌های تعاملی مفید است. قرار نیست رشته خروجی را تجزیه کنید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "lgetxattrs" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

ln

ln target linkname

این دستور یک پیوند سخت ایجاد می‌کند.

ln-f

ln-f target linkname

این دستور یک پیوند سخت ایجاد می‌کند، و در صورتی که پیوند "linkname" از قبل وجود داشته باشد آن را حذف می‌نماید.

ln-s

ln-s target linkname

این دستور با استفاده از دستور "ln -s" یک پیوند نمادین ایجاد می‌کند.

ln-sf

ln-sf target linkname

این دستور با استفاده از دستور "ln -sf" یک پیوند نمادین ایجاد می‌کند. گزینه -f در صورتی که پیوند ("linkname") از قبل وجود داشته باشد آن را حذف می‌نماید.

lremovexattr

lremovexattr xattr path

این دستور مشابه "removexattr" است، اما اگر "path" یک پیوند نمادین باشد، صفت گسترش‌یافته خودِ پیوند را حذف می‌کند.

این دستور به قابلیت "linuxxattrs" وابسته است. همچنین "feature-available" را ببینید.

ls

ls directory

فایل‌های موجود در directory را (نسبت به دایرکتوری ریشه، مسیر کاری فعلی وجود ندارد) فهرست می‌کند. مدخل‌های "." و ".." بازگردانده نمی‌شوند، اما فایل‌های پنهان نشان داده می‌شوند.

ls0

ls0 dir (filenames|-)

این دستور تخصصی برای دریافت فهرستی از نام فایل‌ها در دایرکتوری "dir" استفاده می‌شود. فهرست نام فایل‌ها در فایل محلی filenames (روی میزبان) نوشته می‌شود.

در فایل خروجی، نام فایل‌ها با نویسه‌های "\0" از یکدیگر جدا می‌شوند.

مدخل‌های "." و ".." بازگردانده نمی‌شوند. نام فایل‌ها مرتب‌سازی نمی‌شوند.

برای خواندن/نوشتن از ورودی استاندارد/خروجی استاندارد، به جای نام فایل از "-" استفاده کنید.

lsetxattr

lsetxattr xattr val vallen path

این دستور مشابه "setxattr" است، اما اگر "path" یک پیوند نمادین باشد، یک صفت گسترش‌یافته روی خودِ پیوند تنظیم می‌کند.

این دستور به قابلیت "linuxxattrs" وابسته است. همچنین "feature-available" را ببینید.

lstat

lstat path

اطلاعات فایل را برای "path" داده‌شده بازمی‌گرداند.

این دستور مشابه "stat" است به جز این که اگر "path" یک پیوند نمادین باشد، وضعیت خودِ پیوند گرفته می‌شود، نه فایلی که به آن اشاره دارد.

این دستور معادل فراخوانی سیستمی lstat(2) است.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "lstatns" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

lstatlist

lstatlist path 'names ...'

این فراخوانی به شما امکان می‌دهد عملیات "lstat" را روی چندین فایل انجام دهید، که در آن همه فایل‌ها در دایرکتوری "path" قرار دارند. "names" فهرست فایل‌های این دایرکتوری است.

در بازگشت فهرستی از ساختارهای stat دریافت می‌کنید که تناظر یک‌به‌یک با فهرست "names" دارند. اگر نامی وجود نداشته باشد یا نتوان وضعیت lstat آن را گرفت، فیلد "st_ino" آن ساختار روی -1 تنظیم می‌شود.

این فراخوانی برای برنامه‌هایی در نظر گرفته شده است که می‌خواهند بدون انجام رفت‌وبرگشت‌های متعدد، محتویات یک دایرکتوری را به طور کارآمد فهرست کنند. همچنین "lxattrlist" را برای یک فراخوانی مشابه و کارآمد جهت دریافت صفت‌های گسترش‌یافته ببینید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "lstatnslist" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

lstatns

lstatns path

اطلاعات فایل را برای "path" داده‌شده بازمی‌گرداند.

این دستور مشابه "statns" است به جز این که اگر "path" یک پیوند نمادین باشد، وضعیت خودِ پیوند گرفته می‌شود، نه فایلی که به آن اشاره دارد.

این دستور معادل فراخوانی سیستمی lstat(2) است.

lstatnslist

lstatnslist path 'names ...'

این فراخوانی به شما امکان می‌دهد عملیات "lstatns" را روی چندین فایل انجام دهید، که در آن همه فایل‌ها در دایرکتوری "path" قرار دارند. "names" فهرست فایل‌های این دایرکتوری است.

در بازگشت فهرستی از ساختارهای stat دریافت می‌کنید که تناظر یک‌به‌یک با فهرست "names" دارند. اگر نامی وجود نداشته باشد یا نتوان وضعیت lstat آن را گرفت، فیلد "st_ino" آن ساختار روی -1 تنظیم می‌شود.

این فراخوانی برای برنامه‌هایی در نظر گرفته شده است که می‌خواهند بدون انجام رفت‌وبرگشت‌های متعدد، محتویات یک دایرکتوری را به طور کارآمد فهرست کنند. همچنین "lxattrlist" را برای یک فراخوانی مشابه و کارآمد جهت دریافت صفت‌های گسترش‌یافته ببینید.

luks-add-key

luks-add-key device keyslot

این دستور یک کلید جدید را روی دستگاه LUKS با نام "device" اضافه می‌کند. "key" هر کلید موجودی است و برای دسترسی به دستگاه استفاده می‌شود. "newkey" کلید جدید برای افزودن است. "keyslot" اسلات کلیدی است که جایگزین خواهد شد.

توجه داشته باشید که اگر "keyslot" از قبل حاوی کلید باشد، این دستور شکست خواهد خورد. برای حذف آن کلید باید ابتدا از "luks-kill-slot" استفاده کنید.

این دستور یک یا چند پارامتر کلید یا عبارت عبور (passphrase) دارد. Guestfish این موارد را به طور جداگانه درخواست خواهد کرد.

این دستور به قابلیت "luks" وابسته است. همچنین "feature-available" را ببینید.

luks-close

luks-close device

این دستور یک دستگاه LUKS را که قبلاً توسط "luks-open" یا "luks-open-ro" ایجاد شده است می‌بندد. پارامتر "device" باید نام دستگاه نگاشت LUKS (یعنی /dev/mapper/mapname) باشد و نه نام دستگاه بلوکی زیرین.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "cryptsetup-close" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

این دستور به قابلیت "luks" وابسته است. همچنین "feature-available" را ببینید.

luks-format

luks-format device keyslot

این دستور داده‌های موجود روی "device" را پاک کرده و دستگاه را به عنوان یک دستگاه رمزگذاری‌شده LUKS فرمت می‌کند. "key" کلید اولیه است که به اسلات کلید "keyslot" افزوده می‌شود. (LUKS از ۸ اسلات کلید، با شماره‌های ۰ تا ۷ پشتیبانی می‌کند).

این دستور یک یا چند پارامتر کلید یا عبارت عبور دارد. Guestfish این موارد را به طور جداگانه درخواست خواهد کرد.

این دستور به قابلیت "luks" وابسته است. همچنین "feature-available" را ببینید.

luks-format-cipher

luks-format-cipher device keyslot cipher

این دستور مشابه "luks-format" است اما به شما امکان می‌دهد نوع "cipher" مورد استفاده را نیز تنظیم کنید.

این دستور یک یا چند پارامتر کلید یا عبارت عبور دارد. Guestfish این موارد را به طور جداگانه درخواست خواهد کرد.

این دستور به قابلیت "luks" وابسته است. همچنین "feature-available" را ببینید.

luks-kill-slot

luks-kill-slot device keyslot

این دستور کلید موجود در اسلات کلید "keyslot" را از دستگاه LUKS رمزگذاری‌شده "device" حذف می‌کند. "key" باید یکی از کلیدهای دیگر باشد.

این دستور یک یا چند پارامتر کلید یا عبارت عبور دارد. Guestfish این موارد را به طور جداگانه درخواست خواهد کرد.

این دستور به قابلیت "luks" وابسته است. همچنین "feature-available" را ببینید.

luks-open

luks-open device mapname

این دستور یک دستگاه بلوکی را که طبق استاندارد راه‌اندازی کلید یکپارچه لینوکس (LUKS) رمزگذاری شده است باز می‌کند.

پارامتر "device" دستگاه بلوکی یا پارتیشن رمزگذاری‌شده است.

فراخواننده باید یکی از کلیدهای مرتبط با دستگاه بلوکی LUKS را در پارامتر "key" ارائه دهد.

این کار یک دستگاه بلوکی جدید به نام /dev/mapper/mapname ایجاد می‌کند. خواندن و نوشتن در این دستگاه بلوکی به ترتیب از دستگاه زیرین "device" رمزگشایی و در آن رمزگذاری می‌شود.

اگر این دستگاه بلوکی حاوی گروه‌های حجم LVM باشد، فراخوانی "lvm-scan" با پارامتر "activate" برابر با "true" آن‌ها را نمایان خواهد کرد.

از "list-dm-devices" برای فهرست کردن تمام دستگاه‌های device mapper استفاده کنید.

این دستور یک یا چند پارامتر کلید یا عبارت عبور دارد. Guestfish این موارد را به طور جداگانه درخواست خواهد کرد.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "cryptsetup-open" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

این دستور به قابلیت "luks" وابسته است. همچنین "feature-available" را ببینید.

luks-open-ro

luks-open-ro device mapname

این دستور مشابه "luks-open" است، با این تفاوت که یک نگاشت فقط‌خواندنی ایجاد می‌شود.

این دستور یک یا چند پارامتر کلید یا عبارت عبور دارد. Guestfish این موارد را به صورت جداگانه درخواست خواهد کرد.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "cryptsetup-open" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

این دستور به ویژگی "luks" وابسته است. همچنین ببینید "feature-available".

luks-uuid

luks-uuid device

این دستور UUID دستگاه LUKS با نام "device" را برمی‌گرداند.

این دستور به ویژگی "luks" وابسته است. همچنین ببینید "feature-available".

lvcreate

lvcreate logvol volgroup mbytes

یک حجم منطقی LVM به نام "logvol" بر روی گروه حجم "volgroup"، با اندازه "mbytes" مگابایت ایجاد می‌کند.

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvcreate-free

lvcreate-free logvol volgroup percent

یک حجم منطقی LVM به نام /dev/volgroup/logvol ایجاد می‌کند که تقریباً از "percent" درصد فضای آزاد باقی‌مانده در گروه حجم استفاده می‌کند. کاربردی‌ترین حالت زمانی است که "percent" برابر با 100 باشد که در این صورت بزرگ‌ترین LV ممکن را ایجاد می‌کند.

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvm-canonical-lv-name

lvm-canonical-lv-name lvname

طرح‌های نام‌گذاری جایگزین برای LVها را به نام متعارف (canonical) تبدیل می‌کند. برای مثال، /dev/mapper/VG-LV به /dev/VG/LV تبدیل می‌شود.

اگر پارامتر "lvname" به یک حجم منطقی اشاره نکند، این دستور خطا بازمی‌گرداند. در این حالت errno برابر با "EINVAL" تنظیم خواهد شد.

همچنین ببینید "is-lv", "canonical-device-name".

lvm-clear-filter

lvm-clear-filter

اثر دستور "lvm-set-filter" را خنثی می‌کند. LVM قادر خواهد بود تمام دستگاه‌های بلوکی را مشاهده کند.

این دستور همچنین حافظه نهان (cache) مربوط به LVM را پاکسازی کرده و یک اسکن گروه حجم انجام می‌دهد.

lvm-remove-all

lvm-remove-all

این دستور تمام حجم‌های منطقی، گروه‌های حجم و حجم‌های فیزیکی LVM را حذف می‌کند.

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvm-scan

lvm-scan true|false

تمام دستگاه‌های بلوکی را اسکن کرده و فهرست حجم‌های فیزیکی، گروه‌های حجم و حجم‌های منطقی LVM را بازسازی می‌کند.

اگر پارامتر "activate" برابر با "true" باشد، گروه‌های حجم و حجم‌های منطقی جدیدِ یافت‌شده فعال می‌شوند؛ یعنی دستگاه‌های LV به صورت /dev/VG/LV قابل مشاهده خواهند بود.

هنگامی که یک هندل libguestfs راه‌اندازی می‌شود، دستگاه‌های موجود را اسکن می‌کند، بنابراین معمولاً نیازی به استفاده از این API ندارید. با این حال زمانی که دستگاه جدیدی اضافه کرده‌اید یا دستگاهی را حذف نموده‌اید (مانند زمانی که از API "luks-open" استفاده می‌شود) کاربردی خواهد بود.

lvm-set-filter

lvm-set-filter 'devices ...'

فیلتر دستگاه LVM را طوری تنظیم می‌کند که LVM فقط بتواند دستگاه‌های بلوکی موجود در فهرست "devices" را «ببیند» و تمام دستگاه‌های بلوکی متصل دیگر را نادیده بگیرد.

در مواردی که ایمیج(های) دیسک حاوی PVها یا VGهای تکراری باشند، این دستور مفید است تا LVM نسخه‌های تکراری را نادیده بگیرد، در غیر این صورت LVM ممکن است دچار سردرگمی شود. همچنین توجه داشته باشید که دو نوع تکرار امکان‌پذیر است: یا PV/VGهای کلون‌شده که دارای UUIDهای یکسان هستند؛ یا VGهایی که کلون نشده‌اند اما اتفاقاً نام یکسانی دارند. در حالت عادی نمی‌توانید این وضعیت را ایجاد کنید، اما در خارج از LVM امکان‌پذیر است، مثلاً از طریق کلون کردن ایمیج‌های دیسک یا دستکاری بیت‌ها در متادیتای LVM.

این دستور همچنین حافظه نهان (cache) مربوط به LVM را پاکسازی کرده و یک اسکن گروه حجم انجام می‌دهد.

می‌توانید کل دستگاه‌های بلوکی یا پارتیشن‌های منفرد را فیلتر کنید.

اگر هر کدام از VGها در حال حاضر در حال استفاده باشد (مثلاً حاوی یک سیستم‌فایل سوارشده باشد)، نمی‌توانید از این دستور استفاده کنید، حتی اگر آن VG را فیلتر نکرده باشید.

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvremove

lvremove device

یک حجم منطقی LVM به نام "device" را حذف می‌کند، که در آن "device" مسیر منتهی به LV است، مانند /dev/VG/LV.

همچنین می‌توانید با مشخص کردن نام VG مانند /dev/VG، تمام LVهای موجود در یک گروه حجم را حذف کنید.

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvrename

lvrename logvol newlogvol

نام حجم منطقی "logvol" را به نام جدید "newlogvol" تغییر می‌دهد.

lvresize

lvresize device mbytes

اندازه یک حجم منطقی LVM موجود را به "mbytes" تغییر می‌دهد (گسترش یا کاهش). هنگام کاهش اندازه، داده‌های بخش حذف‌شده از بین خواهند رفت.

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvresize-free

lvresize-free lv percent

یک حجم منطقی موجود "lv" را گسترش می‌دهد تا "percent" درصد از فضای آزاد باقی‌مانده در گروه حجم را پر کند. معمولاً این تابع را با مقدار ۱۰۰ فراخوانی می‌کنید که حجم منطقی را تا حد ممکن با استفاده از تمام فضای آزاد باقی‌مانده در گروه حجم گسترش می‌دهد.

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvs

lvs

تمام حجم‌های منطقی شناسایی‌شده را فهرست می‌کند. این دستور معادل دستور lvs(8) است.

این دستور فهرستی از نام دستگاه‌های حجم منطقی (مثلاً /dev/VolGroup00/LogVol00) را بازمی‌گرداند.

همچنین ببینید "lvs-full", "list-filesystems".

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvs-full

lvs-full

تمام حجم‌های منطقی شناسایی‌شده را فهرست می‌کند. این دستور معادل دستور lvs(8) است. نسخه "full" شامل تمام فیلدها است.

این دستور به ویژگی "lvm2" وابسته است. همچنین ببینید "feature-available".

lvuuid

lvuuid device

این دستور UUID مربوط به LV دستگاه LVM با نام "device" را بازمی‌گرداند.

lxattrlist

lxattrlist path 'names ...'

این فراخوانی به شما امکان می‌دهد صفت‌های گسترش‌یافته (extended attributes) چندین فایل را دریافت کنید، که در آن تمام فایل‌ها در دایرکتوری "path" قرار دارند. "names" فهرستی از فایل‌های این دایرکتوری است.

در خروجی، یک فهرست تخت از ساختارهای xattr دریافت می‌کنید که باید به صورت ترتیبی تفسیر شوند. اولین ساختار xattr همیشه دارای "attrname" با طول صفر است. مقدار "attrval" در این ساختار دارای طول صفر است تا نشان دهد در اجرای "lgetxattr" برای این فایل خطایی رخ داده است، یا یک رشته C است که یک عدد ده‌دهی را نشان می‌دهد (تعداد صفت‌های بعدی برای این فایل، که می‌تواند "0" باشد). سپس پس از اولین ساختار xattr، صفر یا چند صفت برای اولین فایل نام‌برده قرار دارد. این روند برای فایل‌های دوم و بعدی تکرار می‌شود.

این فراخوانی برای برنامه‌هایی در نظر گرفته شده است که می‌خواهند بدون رفت‌وبرگشت‌های متعدد، محتوای یک دایرکتوری را به طور کارآمد فهرست کنند. همچنین برای دریافت آمارهای استاندارد به صورت کارآمد، "lstatlist" را ببینید.

این دستور به ویژگی "linuxxattrs" وابسته است. همچنین ببینید "feature-available".

max-disks

max-disks

حداکثر تعداد دیسک‌هایی را که می‌توان به یک هندل اضافه کرد (مثلاً توسط "add-drive-opts" و فراخوانی‌های مشابه) بازمی‌گرداند.

این تابع در libguestfs 1.19.7 اضافه شد. در نسخه‌های قبلی libguestfs این محدودیت ۲۵ بود.

برای اطلاعات بیشتر در این زمینه، بخش "MAXIMUM NUMBER OF DISKS" در guestfs(3) را ببینید.

md-create

md-create name 'devices ...' [missingbitmap:N] [nrdevices:N] [spare:N] [chunk:N] [level:..]

یک دستگاه md (RAID) لینوکس با نام "name" بر روی دستگاه‌های موجود در فهرست "devices" ایجاد می‌کند.

پارامترهای اختیاری عبارتند از:

"missingbitmap"

یک نقشه بیتی (bitmap) از دستگاه‌های مفقود. اگر بیتی تنظیم شده باشد به این معنی است که یک دستگاه مفقود به آرایه اضافه می‌شود. کم‌ارزش‌ترین بیت مربوط به اولین دستگاه در آرایه است.

به عنوان مثال:

اگر "devices = ["/dev/sda"]" و "missingbitmap = 0x1" باشد، آرایه حاصل "[<missing>, "/dev/sda"]" خواهد بود.

اگر "devices = ["/dev/sda"]" و "missingbitmap = 0x2" باشد، آرایه حاصل "["/dev/sda", <missing>]" خواهد بود.

مقدار پیش‌فرض 0 است (هیچ دستگاه مفقودی وجود ندارد).

طول "devices" + تعداد بیت‌های تنظیم‌شده در "missingbitmap" باید برابر با "nrdevices" + "spare" باشد.

"nrdevices"

تعداد دستگاه‌های فعال RAID.

در صورت تنظیم نشدن، مقدار پیش‌فرض برابر با طول "devices" به علاوه تعداد بیت‌های تنظیم‌شده در "missingbitmap" خواهد بود.

"spare"

تعداد دستگاه‌های یدکی (spare).

در صورت تنظیم نشدن، مقدار پیش‌فرض 0 است.

"chunk"

اندازه چانک (قطعه) به بایت.

هنگامی که "level" برابر با "raid1" باشد (که پیش‌فرض است؛ زیر را ببینید)، پارامتر "chunk" کاربردی ندارد و نباید مشخص شود.

"level"

سطح RAID، که می‌تواند یکی از موارد زیر باشد: "linear", "raid0", 0, "stripe", "raid1", 1, "mirror", "raid4", 4, "raid5", 5, "raid6", 6, "raid10", 10. برخی از این موارد مترادف هستند و ممکن است در آینده سطوح بیشتری اضافه شود.

در صورت تنظیم نشدن، مقدار پیش‌فرض "raid1" است.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به ویژگی "mdadm" وابسته است. همچنین ببینید "feature-available".

md-detail

md-detail md

این دستور خروجی "mdadm -DY <md>" را ارائه می‌دهد. فیلدهای زیر معمولاً در هش بازگردانده‌شده وجود دارند. فیلدهای دیگر نیز ممکن است موجود باشند.

"level"

سطح raid مربوط به دستگاه MD.

"devices"

تعداد دستگاه‌های زیربنایی در دستگاه MD.

"metadata"

نسخه متادیتای استفاده‌شده.

"uuid"

شناسه یکتای (UUID) دستگاه MD.

"name"

نام دستگاه MD.

این دستور به ویژگی "mdadm" وابسته است. همچنین ببینید "feature-available".

md-stat

md-stat md

این فراخوانی فهرستی از دستگاه‌های زیربنایی سازنده دستگاه تک‌آرایه نرم‌افزاری RAID با نام "md" را بازمی‌گرداند.

برای دریافت فهرستی از دستگاه‌های نرم‌افزاری RAID، دستور "list-md-devices" را فراخوانی کنید.

هر ساختار بازگردانده‌شده مربوط به یک دستگاه به همراه اطلاعات وضعیت تکمیلی است:

"mdstat_device"

نام دستگاه زیربنایی.

"mdstat_index"

اندیس این دستگاه در درون آرایه.

"mdstat_flags"

پرچم‌های مرتبط با این دستگاه. این یک رشته است که (بدون ترتیب خاصی) شامل صفر یا چند مورد از پرچم‌های زیر است:

این دستور به ویژگی "mdadm" وابسته است. همچنین ببینید "feature-available".

md-stop

md-stop md

این دستور آرایه MD به نام "md" را غیرفعال می‌کند. دستگاه متوقف می‌شود، اما نابود یا صفر نمی‌شود.

این دستور به ویژگی "mdadm" وابسته است. همچنین ببینید "feature-available".

mkdir

mkdir path

دایرکتوری جدیدی با نام "path" ایجاد می‌کند.

mkdir-mode

mkdir-mode path mode

این دستور یک دایرکتوری ایجاد کرده و مجوزهای اولیه آن را برابر با "mode" تنظیم می‌کند.

برای سیستم‌فایل‌های متداول لینوکس، مجوزی که در عمل تنظیم می‌شود برابر با "mode & ~umask & 01777" خواهد بود. سیستم‌فایل‌های غیربومی لینوکس ممکن است مجوز را به روش‌های دیگری تفسیر کنند.

همچنین ببینید "mkdir", "umask".

mkdir-p

mkdir-p path

دایرکتوری به نام "path" ایجاد می‌کند و در صورت لزوم هرگونه دایرکتوری والد را نیز می‌سازد. این کار شبیه دستور پوسته "mkdir -p" است.

mkdtemp

mkdtemp tmpl

این دستور یک دایرکتوری موقت ایجاد می‌کند. پارامتر "tmpl" باید یک مسیر کامل برای نام دایرکتوری موقت باشد که شش کاراکتر پایانی آن "XXXXXX" است.

به عنوان مثال: "/tmp/myprogXXXXXX" یا "/Temp/myprogXXXXXX" که مورد دوم برای سیستم‌فایل‌های ویندوز مناسب است.

نام دایرکتوری موقت ایجادشده بازگردانده می‌شود.

دایرکتوری موقت با مجوز 0700 ایجاد شده و مالک آن root است.

فراخواننده مسئول حذف دایرکتوری موقت و محتویات آن پس از استفاده است.

همچنین ببینید: mkdtemp(3).

mke2fs

mke2fs device [blockscount:N] [blocksize:N] [fragsize:N] [blockspergroup:N] [numberofgroups:N] [bytesperinode:N] [inodesize:N] [journalsize:N] [numberofinodes:N] [stridesize:N] [stripewidth:N] [maxonlineresize:N] [reservedblockspercentage:N] [mmpupdateinterval:N] [journaldevice:..] [label:..] [lastmounteddir:..] [creatoros:..] [fstype:..] [usagetype:..] [uuid:..] [forcecreate:true|false] [writesbandgrouponly:true|false] [lazyitableinit:true|false] [lazyjournalinit:true|false] [testfs:true|false] [discard:true|false] [quotatype:true|false] [extent:true|false] [filetype:true|false] [flexbg:true|false] [hasjournal:true|false] [journaldev:true|false] [largefile:true|false] [quota:true|false] [resizeinode:true|false] [sparsesuper:true|false] [uninitbg:true|false]

دستور "mke2fs" برای ایجاد سیستم‌فایل ext2، ext3 یا ext4 بر روی "device" استفاده می‌شود.

پارامتر اختیاری "blockscount" اندازه سیستم‌فایل را بر حسب بلوک مشخص می‌کند. در صورت حذف، پیش‌فرض اندازه "device" خواهد بود. توجه داشته باشید اگر سیستم‌فایل برای داشتن ژورنال بیش از حد کوچک باشد، "mke2fs" بدون اعلان خطا به جای آن یک سیستم‌فایل ext2 ایجاد خواهد کرد.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

mke2fs-J

mke2fs-J fstype blocksize device journal

یک سیستم‌فایل ext2/3/4 بر روی "device" با ژورنال خارجی روی "journal" ایجاد می‌کند. این دستور معادل دستور زیر است:

mke2fs -t fstype -b blocksize -J device=<journal> <device>

همچنین ببینید "mke2journal".

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mke2fs" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

mke2fs-JL

mke2fs-JL fstype blocksize device label

یک سیستم‌فایل ext2/3/4 بر روی "device" با یک ژورنال خارجی بر روی ژورنال با برچسب "label" ایجاد می‌کند.

همچنین ببینید "mke2journal-L".

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mke2fs" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

mke2fs-JU

mke2fs-JU fstype blocksize device uuid

یک سیستم‌فایل ext2/3/4 بر روی "device" با یک ژورنال خارجی بر روی ژورنال با UUID برابر با "uuid" ایجاد می‌کند.

همچنین ببینید "mke2journal-U".

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mke2fs" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

این دستور به ویژگی "linuxfsuuid" وابسته است. همچنین ببینید "feature-available".

mke2journal

mke2journal blocksize device

یک ژورنال خارجی ext2 بر روی "device" ایجاد می‌کند. این دستور معادل دستور زیر است:

mke2fs -O journal_dev -b blocksize device

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mke2fs" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

mke2journal-L

mke2journal-L blocksize label device

یک ژورنال خارجی ext2 بر روی "device" با برچسب "label" ایجاد می‌کند.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mke2fs" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

mke2journal-U

mke2journal-U blocksize uuid device

یک ژورنال خارجی ext2 بر روی "device" با UUID برابر با "uuid" ایجاد می‌کند.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mke2fs" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

این دستور به ویژگی "linuxfsuuid" وابسته است. همچنین ببینید "feature-available".

mkfifo

mkfifo mode path

این فراخوانی یک FIFO (پایپ نام‌گذاری‌شده) به نام "path" با حالت "mode" ایجاد می‌کند. این صرفاً یک پوشش راحت پیرامون "mknod" است.

برخلاف "mknod"، پارامتر "mode" باید فقط شامل بیت‌های مجوزها باشد.

حالت تنظیم‌شده در عمل تحت تأثیر umask قرار می‌گیرد.

این دستور به ویژگی "mknod" وابسته است. همچنین ببینید "feature-available".

mkfs

mkfs-opts

mkfs fstype device [blocksize:N] [features:..] [inode:N] [sectorsize:N] [label:..]

این تابع یک سیستم‌فایل بر روی "device" ایجاد می‌کند. نوع سیستم‌فایل برابر با "fstype" است، به عنوان مثال "ext3".

آرگومان‌های اختیاری عبارتند از:

"blocksize"

اندازه بلوک سیستم‌فایل. اندازه‌های بلوک پشتیبانی‌شده به نوع سیستم‌فایل بستگی دارد، اما معمولاً برای سیستم‌فایل‌های ext2/3 لینوکس 1024، 2048 یا 4096 هستند.

برای VFAT و NTFS پارامتر "blocksize" به عنوان اندازه کلاستر درخواست‌شده در نظر گرفته می‌شود.

برای اندازه‌های بلوک UFS، لطفاً mkfs.ufs(8) را ببینید.

"features"

این گزینه پارامتر -O را به برنامه خارجی mkfs منتقل می‌کند.

برای برخی از انواع سیستم‌فایل، این امکان را می‌دهد تا ویژگی‌های اضافی سیستم‌فایل انتخاب شوند. برای جزئیات بیشتر به mke2fs(8) و mkfs.ufs(8) مراجعه کنید.

نمی‌توانید از این پارامتر اختیاری با نوع سیستم‌فایل "gfs" یا "gfs2" استفاده کنید.

"inode"

این گزینه پارامتر -I را به برنامه خارجی mke2fs(8) منتقل می‌کند که اندازه inode را تعیین می‌کند (در حال حاضر فقط برای سیستم‌فایل‌های ext2/3/4).

"sectorsize"

این گزینه پارامتر -S را به برنامه خارجی mkfs.ufs(8) منتقل می‌کند، که اندازه سکتور را برای سیستم‌فایل ufs تنظیم می‌کند.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

mkfs-b

mkfs-b fstype blocksize device

این فراخوانی مشابه "mkfs" است، اما به شما امکان می‌دهد اندازه بلوک سیستم‌فایل حاصل را کنترل کنید. اندازه‌های بلوک پشتیبانی‌شده به نوع سیستم‌فایل بستگی دارد، اما معمولاً فقط 1024، 2048 یا 4096 هستند.

برای VFAT و NTFS پارامتر "blocksize" به عنوان اندازه کلاستر درخواست‌شده در نظر گرفته می‌شود.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mkfs" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

mkfs-btrfs

mkfs-btrfs 'devices ...' [allocstart:N] [bytecount:N] [datatype:..] [leafsize:N] [label:..] [metadata:..] [nodesize:N] [sectorsize:N]

یک سیستم‌فایل btrfs ایجاد می‌کند و امکان تنظیم تمام موارد قابل پیکربندی را فراهم می‌سازد. برای اطلاعات بیشتر در مورد آرگومان‌های اختیاری، mkfs.btrfs(8) را ببینید.

از آنجا که سیستم‌فایل‌های btrfs می‌توانند چندین دستگاه را پوشش دهند، این تابع یک فهرست غیرخالی از دستگاه‌ها را می‌گیرد.

برای ایجاد سیستم‌فایل‌های عمومی، از "mkfs" استفاده کنید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به ویژگی "btrfs" وابسته است. همچنین ببینید "feature-available".

mklost-and-found

mklost-and-found mountpoint

دایرکتوری "lost+found" را می‌سازد که معمولاً در دایرکتوری ریشه یک سیستم‌فایل ext2/3/4 قرار دارد. "mountpoint" دایرکتوری‌ای است که در زیر آن سعی در ایجاد دایرکتوری "lost+found" داریم.

mkmountpoint

mkmountpoint exemptpath

توابع "mkmountpoint" و "rmmountpoint" فراخوانی‌های تخصصی هستند که می‌توان از آنها برای ایجاد نقطه سوارشدن (نقطه مانت) اضافی قبل از سوار کردن اولین سیستم‌فایل استفاده کرد.

این فراخوانی‌ها فقط در برخی شرایط بسیار محدود ضروری هستند، عمدتاً در حالتی که می‌خواهید ترکیبی از سیستم‌فایل‌های غیرمرتبط و/یا فقط‌خواندنی را با هم سوار کنید.

به عنوان مثال، دیسک‌های زنده (Live CD) اغلب حاوی یک ساختار تودرتو (شبیه عروسک ماتریوشکا) از سیستم‌فایل‌ها هستند: یک لایه بیرونی ISO، با یک ایمیج squashfs در داخل آن، و یک ایمیج ext2/3 در داخل آن. می‌توانید این مورد را به صورت زیر در guestfish استخراج کنید:

add-ro Fedora-11-i686-Live.iso
run
mkmountpoint /cd
mkmountpoint /sqsh
mkmountpoint /ext3fs
mount /dev/sda /cd
mount-loop /cd/LiveOS/squashfs.img /sqsh
mount-loop /sqsh/LiveOS/ext3fs.img /ext3fs

سیستم‌فایل داخلی اکنون زیر نقطه مانت /ext3fs باز شده است.

تابع "mkmountpoint" با "umount-all" سازگار نیست. اگر سعی کنید این فراخوانی‌ها را ترکیب کنید ممکن است با خطاهای غیرمنتظره مواجه شوید. امن‌ترین راه این است که پس از استفاده، سیستم‌فایل‌ها را به صورت دستی پیاده کرده و نقاط مانت را حذف کنید.

دستور "umount-all" سیستم‌فایل‌ها را با مرتب‌سازی مسیرها از طولانی‌ترین به کوتاه‌ترین پیاده می‌کند، بنابراین برای اینکه این مورد برای نقاط مانت دستی کار کند، باید اطمینان حاصل کنید که داخلی‌ترین نقاط مانت دارای طولانی‌ترین مسیرها باشند، همان‌طور که در کد نمونه بالا نشان داده شده است.

برای جزئیات بیشتر به https://bugzilla.redhat.com/show_bug.cgi?id=599503 مراجعه کنید.

همگام‌سازی خودکار (Autosync) [بخش "set-autosync" را ببینید؛ این قابلیت به طور پیش‌فرض روی هندل‌ها فعال است] می‌تواند باعث فراخوانی "umount-all" در هنگام بسته شدن هندل شود که این امر نیز می‌تواند این مشکلات را ایجاد کند.

mknod

mknod mode devmajor devminor path

این فراخوانی دستگاه‌های ویژه بلوکی یا کاراکتری، یا پایپ‌های نام‌گذاری‌شده (FIFOs) را ایجاد می‌کند.

پارامتر "mode" باید حالت مورد نظر باشد که از ثابت‌های استاندارد استفاده می‌کند. "devmajor" و "devminor" شماره‌های اصلی و فرعی دستگاه هستند که فقط هنگام ایجاد دستگاه‌های ویژه بلوکی و کاراکتری استفاده می‌شوند.

توجه داشته باشید که درست مانند mknod(2)، مقدار mode باید به صورت بیتی با S_IFBLK، S_IFCHR، S_IFIFO یا S_IFSOCK با OR ترکیب شده باشد (در غیر این صورت این فراخوانی صرفاً یک فایل معمولی ایجاد می‌کند). این ثابت‌ها در فایل‌های هدر استاندارد لینوکس موجود هستند، یا می‌توانید از "mknod-b"، "mknod-c" یا "mkfifo" استفاده کنید که پوشش‌هایی پیرامون این دستور هستند و ثابت مناسب را به صورت بیتی با OR برای شما اعمال می‌کنند.

حالت تنظیم‌شده در عمل تحت تأثیر umask قرار می‌گیرد.

این دستور به ویژگی "mknod" وابسته است. همچنین ببینید "feature-available".

mknod-b

mknod-b mode devmajor devminor path

این فراخوانی یک گره دستگاه بلوکی به نام "path" با حالت "mode" و شماره‌های اصلی/فرعی دستگاه "devmajor" و "devminor" ایجاد می‌کند. این صرفاً یک پوشش راحت پیرامون "mknod" است.

برخلاف "mknod"، پارامتر "mode" باید فقط شامل بیت‌های مجوزها باشد.

حالت تنظیم‌شده در عمل تحت تأثیر umask قرار می‌گیرد.

این دستور به ویژگی "mknod" وابسته است. همچنین ببینید "feature-available".

mknod-c

mknod-c mode devmajor devminor path

این فراخوانی یک گره دستگاه کاراکتری به نام "path" با حالت "mode" و شماره‌های اصلی/فرعی دستگاه "devmajor" و "devminor" ایجاد می‌کند. این صرفاً یک پوشش راحت پیرامون "mknod" است.

برخلاف "mknod"، پارامتر "mode" باید فقط شامل بیت‌های مجوزها باشد.

حالت تنظیم‌شده در عمل تحت تأثیر umask قرار می‌گیرد.

این دستور به ویژگی "mknod" وابسته است. همچنین ببینید "feature-available".

mksquashfs

mksquashfs path (filename|-) [compress:..] [excludes:..]

یک سیستم‌فایل squashfs برای "path" مشخص‌شده ایجاد می‌کند.

فلگ اختیاری "compress" فشرده‌سازی را کنترل می‌کند. در صورت مشخص نشدن، خروجی با استفاده از "gzip" فشرده می‌شود. در غیر این صورت می‌توان یکی از رشته‌های زیر را برای انتخاب نوع فشرده‌سازی squashfs مشخص کرد: "gzip", "lzma", "lzo", "lz4", "xz".

سایر آرگومان‌های اختیاری عبارتند از:

"excludes"

فهرستی از الگوهای جانشین (wildcards). فایل‌هایی که با هر یک از الگوهای جانشین مطابقت داشته باشند مستثنی می‌شوند.

لطفاً توجه داشته باشید که این API ممکن است هنگام استفاده برای فشرده‌سازی دایرکتوری‌های حاوی فایل‌های بزرگ، مانند مواردی که squashfs حاصل بیش از ۳ گیگابایت حجم پیدا کند، با شکست مواجه شود.

به جای نام فایل از "-" استفاده کنید تا از stdin/stdout بخوانید/بنویسید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این دستور به ویژگی "squashfs" وابسته است. همچنین ببینید "feature-available".

mkswap

mkswap-opts

mkswap device [label:..] [uuid:..]

یک پارتیشن swap لینوکس بر روی "device" ایجاد می‌کند.

آرگومان‌های اختیاری "label" و "uuid" به شما امکان می‌دهند برچسب و/یا UUID پارتیشن swap جدید را تنظیم کنید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

mkswap-L

mkswap-L label device

یک پارتیشن swap بر روی "device" با برچسب "label" ایجاد می‌کند.

توجه داشته باشید که نمی‌توانید برچسب swap را به یک دستگاه بلوکی (مثلاً /dev/sda) اختصاص دهید، بلکه فقط به یک پارتیشن امکان‌پذیر است. به نظر می‌رسد این یکی از محدودیت‌های هسته یا ابزارهای swap باشد.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mkswap" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

mkswap-U

mkswap-U uuid device

یک پارتیشن swap بر روی "device" با شناسه یکتای "uuid" ایجاد می‌کند.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "mkswap" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

این دستور به ویژگی "linuxfsuuid" وابسته است. همچنین ببینید "feature-available".

mkswap-file

mkswap-file path

یک فایل swap ایجاد می‌کند.

این دستور صرفاً امضای فایل swap را در یک فایل موجود می‌نویسد. برای ایجاد خود فایل، از دستوری مانند "fallocate" استفاده کنید.

mktemp

mktemp tmpl [suffix:..]

این دستور یک فایل موقت ایجاد می‌کند. پارامتر "tmpl" باید یک مسیر کامل برای نام دایرکتوری موقت باشد که شش کاراکتر پایانی آن "XXXXXX" است.

به عنوان مثال: "/tmp/myprogXXXXXX" یا "/Temp/myprogXXXXXX" که مورد دوم برای سیستم‌فایل‌های ویندوز مناسب است.

نام فایل موقت ایجادشده بازگردانده می‌شود.

فایل موقت با مجوز 0600 ایجاد شده و مالک آن root است.

فراخواننده مسئول حذف فایل موقت پس از استفاده است.

اگر پارامتر اختیاری "suffix" داده شود، پسوند (مثلاً ".txt") به انتهای نام موقت اضافه می‌شود.

همچنین ببینید: "mkdtemp".

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

modprobe

modprobe modulename

یک ماژول هسته را در اپلاینس بارگذاری می‌کند.

این دستور به ویژگی "linuxmodules" وابسته است. همچنین ببینید "feature-available".

mount

mount mountable mountpoint

یک دیسک مهمان را در موقعیتی از سیستم‌فایل سوار می‌کند. دستگاه‌های بلوکی همان‌طور که به مهمان اضافه شده‌اند، /dev/sda، /dev/sdb و غیره نام‌گذاری می‌شوند. اگر آن دستگاه‌های بلوکی حاوی پارتیشن باشند، نام‌های معمول را خواهند داشت (مثلاً /dev/sda1). همچنین نام‌های سبک LVM به صورت /dev/VG/LV یا رشته‌های قابل‌سوارشدن (mountable) بازگردانده‌شده توسط "list-filesystems" یا "inspect-get-mountpoints" می‌توانند استفاده شوند.

قوانین همانند mount(2) هستند: یک سیستم‌فایل ابتدا باید روی / سوار شود قبل از اینکه سیستم‌فایل‌های دیگر بتوانند سوار شوند. سایر سیستم‌فایل‌ها فقط می‌توانند روی دایرکتوری‌هایی سوار شوند که از قبل وجود دارند.

سیستم‌فایل سوارشده، در صورتی که دسترسی کافی روی دستگاه زیربنایی داشته باشیم، قابل نوشتن است.

قبل از libguestfs 1.13.16، این فراخوانی به صورت ضمنی گزینه‌های "sync" و "noatime" را اضافه می‌کرد. گزینه "sync" سرعت نوشتن را به شدت کاهش می‌داد و مشکلات زیادی برای کاربران ایجاد می‌کرد. اگر برنامه شما ممکن است نیاز به کار با نسخه‌های قدیمی‌تر libguestfs داشته باشد، به جای آن از "mount-options" استفاده کنید (در صورتی که هیچ گزینه‌ای نمی‌خواهید، از یک رشته خالی برای پارامتر اول استفاده کنید).

mount-9p

mount-9p mounttag mountpoint [options:..]

این فراخوانی هیچ کاری انجام نمی‌دهد و یک خطا برمی‌گرداند.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

این تابع منسوخ شده است. هیچ جایگزینی وجود ندارد. برای اطلاعات بیشتر به مستندات API در guestfs(3) مراجعه کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

mount-local

mount-local localmountpoint [readonly:true|false] [options:..] [cachetimeout:N] [debugcalls:true|false]

این فراخوانی سیستم‌فایل قابل‌دسترس با libguestfs را به یک نقطه مانت محلی (دایرکتوری) به نام "localmountpoint" صادر می‌کند. خواندن و نوشتن‌های معمولی در فایل‌ها و دایرکتوری‌های زیر "localmountpoint" از طریق libguestfs هدایت می‌شوند.

اگر فلگ اختیاری "readonly" روی true تنظیم شود، نوشتن در سیستم‌فایل خطای "EROFS" برمی‌گرداند.

مقدار "options" فهرستی از گزینه‌های مانت است که با کاما از هم جدا شده‌اند. برای برخی از گزینه‌های کاربردی guestmount(1) را ببینید.

مقدار "cachetimeout" زمان انقضا (به ثانیه) را برای ورودی‌های کش‌شده دایرکتوری تعیین می‌کند. مقدار پیش‌فرض ۶۰ ثانیه است. برای اطلاعات بیشتر guestmount(1) را ببینید.

اگر "debugcalls" روی true تنظیم شود، اطلاعات اشکال‌زدایی اضافی برای هر فراخوانی FUSE تولید می‌شود.

هنگامی که "mount-local" برمی‌گردد، سیستم‌فایل آماده است اما درخواست‌ها را پردازش نمی‌کند (دسترسی به آن مسدود خواهد شد). باید "mount-local-run" را فراخوانی کنید تا حلقه اصلی اجرا شود.

برای مستندات کامل بخش "MOUNT LOCAL" در guestfs(3) را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "OPTIONAL ARGUMENTS" را ببینید.

mount-local-run

mount-local-run

اجرای حلقه اصلی که فراخوانی‌های هسته را به فراخوانی‌های libguestfs ترجمه می‌کند.

این دستور باید تنها پس از بازگشت موفقیت‌آمیز "mount-local" فراخوانی شود. این فراخوانی تا زمانی که سیستم فایل آن‌مانت (unmount) نشود بازنخواهد گشت.

توجه داشته باشید که نباید not فراخوانی‌های همزمان libguestfs را روی همان هندل از رشته (thread) دیگری انجام دهید.

می‌توانید این تابع را از رشته‌ای متفاوت از رشته‌ای که "mount-local" را فراخوانی کرده اجرا کنید، مشروط به رعایت قوانین معمول برای رشته‌ها و libguestfs (بخش "MULTIPLE HANDLES AND MULTIPLE THREADS" در guestfs(3) را ببینید).

برای مستندات کامل به "MOUNT LOCAL" در guestfs(3) مراجعه کنید.

mount-loop

mount-loop file mountpoint

این دستور به شما امکان می‌دهد file (تصویر یک سیستم فایل درون یک فایل) را روی یک نقطه اتصال (mount point) سوار کنید. این دستور کاملاً معادل دستور "mount -o loop file mountpoint"; است.

mount-options

mount-options options mountable mountpoint

این دستور مانند دستور "mount" است، اما به شما امکان می‌دهد گزینه‌های مانت را همانند فلگ -o در mount(8) تنظیم کنید.

اگر پارامتر "options" یک رشته خالی باشد، هیچ گزینه‌ای ارسال نمی‌شود (تمام گزینه‌ها به مقادیر پیش‌فرضی که سیستم فایل استفاده می‌کند بازمی‌گردند).

mount-ro

mount-ro mountable mountpoint

این دستور مانند دستور "mount" است، اما سیستم فایل را با فلگ فقط‌خواندنی (-o ro) مانت می‌کند.

mount-vfs

mount-vfs options vfstype mountable mountpoint

این دستور مانند دستور "mount" است، اما به شما امکان می‌دهد هم گزینه‌های مانت و هم نوع vfstype را همانند فلگ‌های -o و -t در mount(8) مشخص کنید.

mountable-device

mountable-device mountable

نام دستگاه یک موجودیت قابل اتصال (mountable) را برمی‌گرداند. در موارد بسیار زیادی، mountable همان نام دستگاه است.

اما این موضوع برای زیرحجم‌های (subvolumes) btrfs صدق نمی‌کند؛ جایی که mountable ترکیبی از نام دستگاه و مسیر زیرحجم است (همچنین برای استخراج مسیر زیرحجم از mountable، در صورت وجود، به "mountable-subvolume" مراجعه کنید).

mountable-subvolume

mountable-subvolume mountable

مسیر زیرحجم (subvolume) یک mountable را برمی‌گرداند. موجودیت‌های قابل اتصال زیرحجم‌های Btrfs ترکیبی از نام دستگاه و مسیر زیرحجم هستند (همچنین برای استخراج دستگاه از mountable به "mountable-device" مراجعه کنید).

اگر mountable نشان‌دهنده یک زیرحجم btrfs نباشد، این تابع با شکست مواجه شده و "errno" روی "EINVAL" تنظیم می‌شود.

mountpoints

mountpoints

این فراخوانی شبیه به "mounts" است. آن فراخوانی فهرستی از دستگاه‌ها را برمی‌گرداند. این یکی یک جدول هش (مپ) از نام دستگاه به دایرکتوری‌ای که دستگاه در آن مانت شده است را برمی‌گرداند.

mounts

mounts

این دستور فهرستی از سیستم‌های فایل متصل‌شده فعلی را برمی‌گرداند. این دستور فهرستی از دستگاه‌ها (مانند /dev/sda1 و /dev/VG/LV) را بازمی‌گرداند.

برخی از مانت‌های داخلی نمایش داده نمی‌شوند.

همچنین ببینید: "mountpoints"

mv

mv src dest

این دستور فایلی را از "src" به "dest" منتقل می‌کند که در آن "dest" می‌تواند نام فایل مقصد یا دایرکتوری مقصد باشد.

همچنین ببینید: "rename".

nr-devices

nr-devices

تعداد کل دستگاه‌های بلاکی (block devices) اضافه شده را برمی‌گرداند. این تعداد برابر با تعداد دستگاه‌هایی است که در صورت فراخوانی "list-devices" بازگردانده می‌شدند.

برای اطلاع از حداکثر تعداد دستگاه‌هایی که می‌توان اضافه کرد، "max-disks" را فراخوانی کنید.

ntfs-3g-probe

ntfs-3g-probe true|false device

این دستور، دستور ntfs-3g.probe(8) را اجرا می‌کند که قابلیت مانت شدن یک "device" از نوع NTFS را بررسی می‌کند. (همه حجم‌های NTFS نمی‌توانند به‌صورت خواندنی-نوشتنی مانت شوند و برخی اصلاً قابل مانت نیستند).

"rw" یک فلگ بولی است. اگر می‌خواهید بررسی کنید که آیا حجم به‌صورت خواندنی-نوشتنی قابل مانت است آن را true قرار دهید. اگر می‌خواهید قابلیت مانت فقط‌خواندنی را بررسی کنید آن را false بگذارید.

مقدار بازگشتی یک عدد صحیح است که در صورت موفقیت‌آمیز بودن عملیات برابر با 0 خواهد بود، یا مقداری غیرصفر خواهد بود که در صفحه راهنمای ntfs-3g.probe(8) مستند شده است.

این دستور به ویژگی "ntfs3g" وابسته است. همچنین "feature-available" را ببینید.

ntfs-chmod

ntfs-chmod device mode path [recursive:true|false]

تغییر مجوزهای فایل در یک سیستم فایل NTFS با استفاده از یک ماسک مجوز به سبک chmod، با استفاده از ntfssecaudit(8). فقط حالت‌های عددی پشتیبانی می‌شوند.

Note: هنگام استفاده از این دستور از طریق guestfish، مقدار "mode" به طور پیش‌فرض در مبنای ۱۰ (decimal) در نظر گرفته می‌شود، مگر اینکه پیشوند 0 را برای مبنای ۸ (octal) قرار دهید؛ یعنی از 0700 استفاده کنید نه 700.

پارامتر "device" دستگاه پارتیشن NTFS است (مانند "/dev/sda5"). این دستگاه باید آن‌مانت باشد. پارامتر "mode" حالت مجوزها است (مانند 0744). پارامتر "path" مسیر فایل یا دایرکتوری در سیستم فایل است. اگر فلگ اختیاری "recursive" تنظیم شده باشد، مجوزهای دایرکتوری به‌صورت بازگشتی اعمال می‌شوند.

این دستور یک یا چند آرگومان اختیاری دارد. به "OPTIONAL ARGUMENTS" مراجعه کنید.

این دستور به ویژگی "ntfs3g" وابسته است. همچنین "feature-available" را ببینید.

ntfscat-i

ntfscat-i device inode (filename|-)

دانلود یک فایل از طریق اینود (inode) آن از یک سیستم فایل NTFS و ذخیره آن با نام filename روی ماشین محلی.

این دستور امکان دانلود برخی فایل‌های غیرقابل دسترس مانند فایل‌های درون پوشه $Extend را فراهم می‌کند.

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

برای خواندن/نوشتن از stdin/stdout به جای نام فایل از "-" استفاده کنید.

ntfsclone-in

ntfsclone-in (backupfile|-) device

بازیابی "backupfile" (از فراخوانی قبلی "ntfsclone-out") روی "device"، که باعث رونویسی هرگونه محتوای موجود روی این دستگاه می‌شود.

برای خواندن/نوشتن از stdin/stdout به جای نام فایل از "-" استفاده کنید.

این دستور به ویژگی "ntfs3g" وابسته است. همچنین "feature-available" را ببینید.

ntfsclone-out

ntfsclone-out device (backupfile|-) [metadataonly:true|false] [rescue:true|false] [ignorefscheck:true|false] [preservetimestamps:true|false] [force:true|false]

جریان دادن (Stream) سیستم فایل NTFS از "device" به فایل محلی "backupfile". قالب مورد استفاده برای فایل پشتیبان، یک فرمت ویژه است که توسط ابزار ntfsclone(8) استفاده می‌شود.

اگر فلگ اختیاری "metadataonly" برابر با true باشد، تنها متادیتا ذخیره می‌شود و تمام داده‌های کاربر از دست می‌روند (این برای عیب‌یابی برخی مشکلات سیستم فایل کاربرد دارد).

فلگ‌های اختیاری "rescue"، "ignorefscheck"، "preservetimestamps" و "force" معانی دقیقی دارند که در صفحه راهنمای ntfsclone(8) به تفصیل شرح داده شده‌اند.

برای بازیابی مجدد فایل روی یک دستگاه libguestfs، از "ntfsclone-in" استفاده کنید.

برای خواندن/نوشتن از stdin/stdout به جای نام فایل از "-" استفاده کنید.

این دستور یک یا چند آرگومان اختیاری دارد. به "OPTIONAL ARGUMENTS" مراجعه کنید.

این دستور به ویژگی "ntfs3g" وابسته است. همچنین "feature-available" را ببینید.

ntfsfix

ntfsfix device [clearbadsectors:true|false]

این دستور برخی از ناسازگاری‌های اساسی NTFS را تعمیر می‌کند، فایل ژورنال NTFS را ریست می‌نماید، و یک بررسی یکپارچگی NTFS را برای اولین راه‌اندازی ویندوز زمان‌بندی می‌کند.

این دستور معادل "chkdsk" ویندوز not نیست. این دستور سیستم فایل را برای یافتن ناسازگاری‌ها اسکن not نمی‌کند.

فلگ اختیاری "clearbadsectors" فهرست سکتورهای خراب (bad sectors) را پاک می‌کند. این مورد پس از شبیه‌سازی دیسکی با سکتورهای خراب روی یک دیسک جدید مفید است.

این دستور یک یا چند آرگومان اختیاری دارد. به "OPTIONAL ARGUMENTS" مراجعه کنید.

این دستور به ویژگی "ntfs3g" وابسته است. همچنین "feature-available" را ببینید.

ntfsresize

ntfsresize-opts

ntfsresize device [size:N] [force:true|false]

این دستور اندازه یک سیستم فایل NTFS را تغییر می‌دهد و آن را به اندازه دستگاه زیرین گسترش داده یا کوچک می‌کند.

پارامترهای اختیاری عبارتند از:

"size"

اندازه جدید سیستم فایل (به بایت). در صورت حذف، اندازه سیستم فایل طوری تغییر می‌کند که متناسب با نگه‌دارنده (مانند پارتیشن) باشد.

"force"

اگر این گزینه true باشد، تغییر اندازه سیستم فایل اجبار می‌شود، حتی اگر سیستم فایل طوری علامت‌گذاری شده باشد که نیاز به بررسی یکپارچگی داشته باشد.

پس از عملیات تغییر اندازه، سیستم فایل همیشه طوری علامت‌گذاری می‌شود که نیاز به بررسی یکپارچگی داشته باشد (برای ایمنی). برای انجام این بررسی و پاک کردن این وضعیت، باید سیستم را با ویندوز بوت کنید. اگر گزینه "force" را تنظیم don't نکنید، فراخوانی مکرر "ntfsresize" روی یک سیستم فایل واحد بدون بوت شدن به ویندوز در بین هر تغییر اندازه امکان‌پذیر نخواهد بود.

همچنین ntfsresize(8) را ببینید.

این دستور یک یا چند آرگومان اختیاری دارد. به "OPTIONAL ARGUMENTS" مراجعه کنید.

این دستور به ویژگی "ntfsprogs" وابسته است. همچنین "feature-available" را ببینید.

ntfsresize-size

ntfsresize-size device size

این دستور همانند "ntfsresize" است به جز اینکه به شما اجازه می‌دهد اندازه جدید (به بایت) را به صراحت مشخص کنید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "ntfsresize" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ شدن آنها نشان می‌دهد که مشکلاتی در استفاده صحیح از این توابع وجود دارد.

این دستور به ویژگی "ntfsprogs" وابسته است. همچنین "feature-available" را ببینید.

parse-environment

parse-environment

محیط برنامه (Environment) را تجزیه کرده و فلگ‌ها را متناسب با آن در هندل تنظیم می‌کند. برای مثال اگر "LIBGUESTFS_DEBUG=1" باشد، فلگ ‘verbose’ در هندل تنظیم می‌شود.

بیشتر برنامه‌ها نیازی به فراخوانی این دستور ندارند. این کار هنگام فراخوانی "create" به طور ضمنی انجام می‌شود.

برای فهرستی از متغیرهای محیطی که می‌توانند بر هندل‌های libguestfs تأثیر بگذارند، به "ENVIRONMENT VARIABLES" در guestfs(3) مراجعه کنید. همچنین "guestfs_create_flags" در guestfs(3) و "parse-environment-list" را ببینید.

parse-environment-list

parse-environment-list 'environment ...'

فهرست رشته‌ها را در آرگومان "environment" تجزیه کرده و فلگ‌ها را متناسب با آن در هندل تنظیم می‌کند. برای مثال اگر "LIBGUESTFS_DEBUG=1" رشته‌ای در این فهرست باشد، فلگ ‘verbose’ در هندل تنظیم می‌شود.

این دستور مانند "parse-environment" است به جز اینکه فهرستی صریح از رشته‌ها را به جای محیط خود برنامه تجزیه می‌کند.

part-add

part-add device prlogex startsect endsect

این دستور یک پارتیشن به "device" اضافه می‌کند. اگر جدول پارتیشن روی دستگاه وجود ندارد، ابتدا "part-init" را فراخوانی کنید.

پارامتر "prlogex" نوع پارتیشن است. به طور معمول در اینجا باید "p" یا "primary" را ارسال کنید، اما جداول پارتیشن MBR از انواع پارتیشن "l" (یا "logical") و "e" (یا "extended") نیز پشتیبانی می‌کنند.

"startsect" و "endsect" شروع و پایان پارتیشن بر حسب سکتور هستند. مقدار "endsect" می‌تواند منفی باشد که به معنای شمارش معکوس از انتهای دیسک است (-1 آخرین سکتور است).

ایجاد پارتیشنی که کل دیسک را پوشش دهد چندان ساده نیست. برای انجام این کار از "part-disk" استفاده کنید.

part-del

part-del device partnum

این دستور پارتیشن با شماره "partnum" را روی "device" حذف می‌کند.

توجه داشته باشید که در مورد پارتیشن‌بندی MBR، حذف یک پارتیشن extended تمام پارتیشن‌های logical درون آن را نیز حذف می‌کند.

part-disk

part-disk device parttype

این دستور صرفاً ترکیبی از "part-init" و سپس "part-add" برای ایجاد یک پارتیشن primary واحد است که کل دیسک را می‌پوشاند.

"parttype" نوع جدول پارتیشن است، معمولاً "mbr" یا "gpt"، اما مقادیر ممکن دیگر در "part-init" شرح داده شده‌اند.

part-expand-gpt

part-expand-gpt device

ساختارهای داده پشتیبان GPT (یا backup GPT) را به انتهای دیسک منتقل می‌کند. این مورد در زمان گسترش درجا (in-place) تصویر دیسک مفید است زیرا فضای دیسک پس از هدر پشتیبان GPT قابل استفاده نیست. این دستور معادل "sgdisk -e" است.

همچنین sgdisk(8) را ببینید.

این دستور به ویژگی "gdisk" وابسته است. همچنین "feature-available" را ببینید.

part-get-bootable

part-get-bootable device partnum

اگر پارتیشن "partnum" روی "device" دارای فلگ bootable فعال باشد، مقدار true برمی‌گرداند.

همچنین ببینید: "part-set-bootable".

part-get-disk-guid

part-get-disk-guid device

شناسه دیسک (GUID) یک "device" با پارتیشن‌بندی GPT را برمی‌گرداند. رفتار برای انواع دیگر پارتیشن نامشخص (undefined) است.

part-get-gpt-attributes

part-get-gpt-attributes device partnum

فلگ‌های ویژگی پارتیشن GPT با شماره "partnum" را برمی‌گرداند. برای پارتیشن‌های MBR خطا برگردانده می‌شود.

part-get-gpt-guid

part-get-gpt-guid device partnum

شناسه GUID پارتیشن GPT شماره "partnum" را برمی‌گرداند.

part-get-gpt-type

part-get-gpt-type device partnum

شناسه نوع (type GUID) پارتیشن GPT شماره "partnum" را برمی‌گرداند.

part-get-mbr-id

part-get-mbr-id device partnum

بایت نوع MBR (که با نام بایت ID نیز شناخته می‌شود) را از پارتیشن شماره "partnum" برمی‌گرداند.

توجه داشته باشید که فقط پارتیشن‌های MBR (سبک قدیمی DOS) دارای بایت نوع هستند. برای سایر انواع جدول پارتیشن نتایج نامشخص دریافت خواهید کرد ("part-get-parttype" را ببینید).

part-get-mbr-part-type

part-get-mbr-part-type device partnum

نوع پارتیشن یک پارتیشن MBR با شماره "partnum" روی دستگاه "device" را برمی‌گرداند.

مقادیر بازگشتی "primary"، "logical"، یا "extended" هستند.

part-get-name

part-get-name device partnum

نام پارتیشن شماره "partnum" روی دستگاه "device" را دریافت می‌کند. توجه داشته باشید که شماره‌گذاری پارتیشن‌ها از ۱ شروع می‌شود.

نام پارتیشن فقط در انواع خاصی از جدول پارتیشن قابل خواندن است. این ویژگی روی پارتیشن‌های "gpt" کار می‌کند اما روی "mbr" کار نمی‌کند.

part-get-parttype

part-get-parttype device

این دستور جدول پارتیشن روی "device" را بررسی کرده و نوع (فرمت) جدول پارتیشن در حال استفاده را برمی‌گرداند.

مقادیر بازگشتی متداول عبارتند از: "msdos" (جدول پارتیشن MBR سبک DOS/Windows)، "gpt" (جدول پارتیشن سبک GPT/EFI). مقادیر دیگری نیز امکان‌پذیر هستند، هرچند غیرمعمول. برای فهرست کامل به "part-init" مراجعه کنید.

part-init

part-init device parttype

یک جدول پارتیشن خالی از یکی از انواع فهرست‌شده در زیر روی "device" ایجاد می‌کند. معمولاً "parttype" باید "msdos" یا "gpt" (برای دیسک‌های بزرگ) باشد.

در ابتدا هیچ پارتیشنی وجود ندارد. در ادامه، باید برای هر پارتیشن مورد نیاز "part-add" را فراخوانی کنید.

مقادیر مجاز برای "parttype" عبارتند از:

"efi"

"gpt"

جدول پارتیشن Intel EFI / GPT.

این گزینه برای پارتیشن‌های بزرگتر یا مساوی ۲ ترابایت که از لینوکس و سیستم‌های Mac OS X مبتنی بر اینتل در دسترس خواهند بود، توصیه می‌شود. همچنین دارای سازگاری محدود رو به عقب با فرمت "mbr" است.

"mbr"

"msdos"

فرمت استاندارد "Master Boot Record" (MBR) در PC که توسط MS-DOS و ویندوز استفاده می‌شود. این نوع پارتیشن only فقط برای اندازه‌های دستگاه تا ۲ ترابایت کار می‌کند. برای دیسک‌های بزرگ استفاده از "gpt" توصیه می‌شود.

انواع دیگر جدول پارتیشن که ممکن است کار کنند اما پشتیبانی نمی‌شوند شامل موارد زیر هستند:

"aix"

برچسب‌های دیسک AIX.

"amiga"

"rdb"

فرمت "Rigid Disk Block" آمیگا.

"bsd"

برچسب‌های دیسک BSD.

"dasd"

فرمت DASD، استفاده‌شده در مِین‌فریم‌های IBM.

"dvh"

حجم‌های MIPS/SGI.

"mac"

فرمت پارتیشن قدیمی مک. مک‌های مدرن از "gpt" استفاده می‌کنند.

"pc98"

فرمت NEC PC-98، ظاهراً رایج در ژاپن.

"sun"

برچسب‌های دیسک Sun.

part-list

part-list device

این دستور جدول پارتیشن روی "device" را تجزیه کرده و فهرست پارتیشن‌های یافت‌شده را برمی‌گرداند.

فیلدهای ساختار بازگردانده‌شده عبارتند از:

"part_num"

شماره پارتیشن، با شمارش از ۱.

"part_start"

شروع پارتیشن به بایت. برای دریافت سکتورها باید آن را بر اندازه سکتور دستگاه تقسیم کنید؛ "blockdev-getss" را ببینید.

"part_end"

پایان پارتیشن به بایت.

"part_size"

اندازه پارتیشن به بایت.

part-resize

part-resize device partnum endsect

این دستور اندازه پارتیشن شماره "partnum" روی "device" را با جابجا کردن موقعیت پایان تغییر می‌دهد.

توجه داشته باشید که این دستور هیچ سیستم فایلی موجود در پارتیشن را تغییر نمی‌دهد. اگر می‌خواهید این کار را انجام دهید، باید از دستورات تغییر اندازه سیستم فایل مانند "resize2fs" استفاده کنید.

هنگام بزرگ کردن پارتیشن، می‌خواهید بعد از آن سیستم فایل را گسترش دهید، اما هنگام کوچک کردن، باید سیستم فایل را قبل از پارتیشن کوچک کنید.

part-set-bootable

part-set-bootable device partnum true|false

این دستور فلگ قابلیت بوت (bootable) را روی پارتیشن شماره "partnum" روی دستگاه "device" تنظیم می‌کند. توجه داشته باشید که شماره‌گذاری پارتیشن‌ها از ۱ شروع می‌شود.

فلگ bootable توسط برخی از سیستم‌های عامل (به‌ویژه ویندوز) برای تشخیص پارتیشنی که باید از آن بوت شوند استفاده می‌شود. این موضوع به هیچ وجه یک استاندارد جهانی نیست.

part-set-disk-guid

part-set-disk-guid device guid

شناسه دیسک (GUID) یک "device" با پارتیشن‌بندی GPT را روی "guid" تنظیم می‌کند. اگر جدول پارتیشن "device" از نوع GPT نباشد، یا اگر "guid" یک GUID معتبر نباشد، خطا برمی‌گرداند.

part-set-disk-guid-random

part-set-disk-guid-random device

شناسه دیسک (GUID) یک "device" با پارتیشن‌بندی GPT را به یک مقدار تولیدشده به صورت تصادفی تنظیم می‌کند. اگر جدول پارتیشن "device" از نوع GPT نباشد خطا برمی‌گرداند.

part-set-gpt-attributes

part-set-gpt-attributes device partnum attributes

فلگ‌های ویژگی پارتیشن GPT شماره "partnum" را روی "attributes" تنظیم می‌کند. اگر جدول پارتیشن "device" از نوع GPT نباشد، خطا برمی‌گرداند.

برای فهرستی مفید از ویژگی‌های پارتیشن به https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_entries مراجعه کنید.

part-set-gpt-guid

part-set-gpt-guid device partnum guid

شناسه GUID پارتیشن GPT شماره "partnum" را روی "guid" تنظیم می‌کند. اگر جدول پارتیشن "device" از نوع GPT نباشد یا اگر "guid" یک GUID معتبر نباشد، خطا برمی‌گرداند.

part-set-gpt-type

part-set-gpt-type device partnum guid

شناسه نوع (type GUID) پارتیشن GPT شماره "partnum" را روی "guid" تنظیم می‌کند. اگر جدول پارتیشن "device" از نوع GPT نباشد، یا اگر "guid" یک GUID معتبر نباشد، خطا برمی‌گرداند.

برای فهرستی مفید از GUIDهای نوع به https://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs مراجعه کنید.

part-set-mbr-id

part-set-mbr-id device partnum idbyte

بایت نوع MBR (که با نام بایت ID نیز شناخته می‌شود) پارتیشن شماره "partnum" را روی "idbyte" تنظیم می‌کند. توجه داشته باشید که بایت‌های نوع ذکرشده در بیشتر مستندات در واقع اعداد هگزادسیمال هستند، اما معمولاً بدون هیچ "0x" ابتدایی ذکر می‌شوند که ممکن است گیج‌کننده باشد.

توجه داشته باشید که فقط پارتیشن‌های MBR (سبک قدیمی DOS) دارای بایت نوع هستند. برای سایر انواع جدول پارتیشن نتایج نامشخص دریافت خواهید کرد ("part-get-parttype" را ببینید).

part-set-name

part-set-name device partnum name

نام پارتیشن شماره "partnum" روی دستگاه "device" را تنظیم می‌کند. توجه داشته باشید که شماره‌گذاری پارتیشن‌ها از ۱ شروع می‌شود.

نام پارتیشن فقط در انواع خاصی از جدول پارتیشن قابل تنظیم است. این قابلیت روی پارتیشن‌های "gpt" کار می‌کند اما روی "mbr" کار نمی‌کند.

part-to-dev

part-to-dev partition

این تابع نام یک پارتیشن (مانند "/dev/sdb1") را گرفته و شماره پارتیشن را حذف می‌کند و نام دستگاه را برمی‌گرداند (مانند "/dev/sdb").

پارتیشن نام‌برده‌شده باید وجود داشته باشد، به عنوان مثال به صورت یک رشته بازگردانده‌شده از "list-partitions".

همچنین ببینید: "part-to-partnum"، "device-index".

part-to-partnum

part-to-partnum partition

این تابع نام یک پارتیشن (مانند "/dev/sdb1") را گرفته و شماره پارتیشن را برمی‌گرداند (مانند 1).

پارتیشن نام‌برده‌شده باید وجود داشته باشد، به عنوان مثال به صورت یک رشته بازگردانده‌شده از "list-partitions".

همچنین ببینید: "part-to-dev".

ping-daemon

ping-daemon

این یک پروب آزمایشی به دیمن guestfs است که در داخل appliance لیب‌گست‌اف‌اس (libguestfs) در حال اجراست. فراخوانی این تابع بررسی می‌کند که آیا دیمن به پیام پینگ پاسخ می‌دهد یا خیر، بدون اینکه به هر نحو دیگری بر دیمن یا دستگاه(های) بلاکی متصل تأثیر بگذارد.

pread

pread path count offset

این دستور به شما امکان می‌دهد بخشی از یک فایل را بخوانید. این دستور "count" بایت از فایل را با شروع از آفست "offset" از فایل "path" می‌خواند.

این تابع ممکن است بایت‌های کمتری نسبت به مقدار درخواستی بخواند. برای جزئیات بیشتر فراخوانی سیستمی pread(2) را ببینید.

همچنین ببینید: "pwrite"، "pread-device".

به دلیل پروتکل پیام‌رسانی، محدودیت انتقالی در حدود ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

pread-device

pread-device device count offset

این دستور به شما امکان می‌دهد بخشی از یک دستگاه بلاکی را بخوانید. این دستور "count" بایت از "device" را با شروع از آفست "offset" می‌خواند.

این تابع ممکن است بایت‌های کمتری نسبت به مقدار درخواستی بخواند. برای جزئیات بیشتر فراخوانی سیستمی pread(2) را ببینید.

همچنین ببینید: "pread".

به دلیل پروتکل پیام‌رسانی، محدودیت انتقالی در حدود ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

pvchange-uuid

pvchange-uuid device

تولید یک UUID تصادفی جدید برای حجم فیزیکی (PV) "device".

این دستور به ویژگی "lvm2" وابسته است. همچنین "feature-available" را ببینید.

pvchange-uuid-all

pvchange-uuid-all

تولید UUIDهای تصادفی جدید برای تمام حجم‌های فیزیکی.

این دستور به ویژگی "lvm2" وابسته است. همچنین "feature-available" را ببینید.

pvcreate

pvcreate device

یک حجم فیزیکی LVM (یا Physical Volume) روی "device" نام‌برده ایجاد می‌کند، جایی که "device" معمولاً باید نام یک پارتیشن مانند /dev/sda1 باشد.

این دستور به ویژگی "lvm2" وابسته است. همچنین "feature-available" را ببینید.

pvremove

pvremove device

یک حجم فیزیکی "device" را پاک می‌کند تا LVM دیگر آن را شناسایی نکند.

پیاده‌سازی این دستور از دستور pvremove(8) استفاده می‌کند که از پاک کردن حجم‌های فیزیکی حاوی هرگونه گروه حجم (volume group) امتناع می‌ورزد، بنابراین ابتدا باید آن‌ها را حذف کنید.

این دستور به ویژگی "lvm2" وابسته است. همچنین "feature-available" را ببینید.

pvresize

pvresize device

تغییر اندازه (گسترش یا کوچک کردن) یک حجم فیزیکی LVM موجود برای مطابقت با اندازه جدید دستگاه زیرین.

این دستور به ویژگی "lvm2" وابسته است. همچنین "feature-available" را ببینید.

pvresize-size

pvresize-size device size

این دستور همانند "pvresize" است به جز اینکه به شما اجازه می‌دهد اندازه جدید (به بایت) را به صراحت مشخص کنید.

این دستور به ویژگی "lvm2" وابسته است. همچنین "feature-available" را ببینید.

pvs

pvs

فهرست کردن تمام حجم‌های فیزیکی شناسایی‌شده. این دستور معادل دستور pvs(8) است.

این تابع فهرستی از نام دستگاه‌هایی که حاوی حجم‌های فیزیکی هستند را برمی‌گرداند (مانند /dev/sda2).

همچنین ببینید: "pvs-full".

این دستور به ویژگی "lvm2" وابسته است. همچنین "feature-available" را ببینید.

pvs-full

pvs-full

فهرست کردن تمام حجم‌های فیزیکی شناسایی‌شده. این دستور معادل دستور pvs(8) است. نسخه "full" شامل تمام فیلدها است.

این دستور به ویژگی "lvm2" وابسته است. همچنین "feature-available" را ببینید.

pvuuid

pvuuid device

این دستور شناسه UUID مربوط به PV از نوع LVM را روی "device" برمی‌گرداند.

pwrite

pwrite path content offset

این دستور در بخشی از یک فایل می‌نویسد. بافر داده "content" را در فایل "path" با شروع از آفست "offset" می‌نویسد.

این دستور فراخوانی سیستمی pwrite(2) را پیاده‌سازی می‌کند و مانند آن فراخوانی سیستمی، ممکن است تمام داده‌های درخواستی را ننویسد. مقدار بازگشتی تعداد بایت‌هایی است که واقعاً در فایل نوشته شده‌اند. این مقدار حتی می‌تواند ۰ باشد، هرچند نوشتن‌های ناقص برای فایل‌های معمولی در شرایط عادی نامحتمل است.

همچنین ببینید: "pread"، "pwrite-device".

به دلیل پروتکل پیام‌رسانی، محدودیت انتقالی در حدود ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

pwrite-device

pwrite-device device content offset

این دستور روی بخشی از یک دستگاه می‌نویسد. بافر داده "content" را در "device" با شروع از آفست "offset" می‌نویسد.

این دستور فراخوانی سیستمی pwrite(2) را پیاده‌سازی می‌کند و مانند آن فراخوانی سیستمی، ممکن است تمام داده‌های درخواستی را ننویسد (اگرچه نوشتن‌های ناقص روی دستگاه‌های دیسک و پارتیشن‌ها در هسته‌های استاندارد لینوکس احتمالاً غیرممکن است).

همچنین ببینید: "pwrite".

به دلیل پروتکل پیام‌رسانی، محدودیت انتقالی در حدود ۲ تا ۴ مگابایت وجود دارد. به "PROTOCOL LIMITS" در guestfs(3) مراجعه کنید.

read-file

read-file path

این فراخوانی محتویات فایل "path" را به عنوان یک بافر برمی‌گرداند.

برخلاف "cat"، این تابع می‌تواند فایل‌های حاوی کاراکترهای NUL اسکی تعبیه‌شده را به درستی مدیریت کند.

read-lines

read-lines path

محتویات فایل به نام "path" را برمی‌گرداند.

محتویات فایل به صورت فهرستی از خطوط برگردانده می‌شوند. توالی کاراکترهای انتهایی "LF" و "CRLF" برگردانده not نمی‌شوند.

توجه داشته باشید که این تابع نمی‌تواند فایل‌های باینری را به درستی مدیریت کند (به طور خاص، فایل‌های حاوی کاراکتر "\0" که به عنوان پایان رشته در نظر گرفته می‌شود). برای این‌گونه فایل‌ها باید از تابع "read-file" استفاده کنید و خودتان بافر را به خطوط تقسیم کنید.

readdir

readdir dir

فهرستی از ورودی‌های دایرکتوری در دایرکتوری "dir" را برمی‌گرداند.

تمام ورودی‌های موجود در دایرکتوری، از جمله "." و ".." برگردانده می‌شوند. ورودی‌ها مرتب‌سازی not نشده‌اند، بلکه به همان ترتیبی که در سیستم فایل زیرین قرار دارند برگردانده می‌شوند.

همچنین این فراخوانی اطلاعات پایه‌ای نوع فایل را درباره هر فایل برمی‌گرداند. فیلد "ftyp" شامل یکی از کاراکترهای زیر خواهد بود:

'b'

دستگاه بلاکی (Block special)

'c'

دستگاه کاراکتری (Char special)

'd'

دایرکتوری

'f'

صف FIFO (پایپ نام‌گذاری‌شده)

'l'

پیوند نمادین (Symbolic link)

'r'

فایل معمولی (Regular file)

's'

سوکت (Socket)

'u'

نوع فایل ناشناخته

'?'

فراخوانی readdir(3) یک فیلد "d_type" با مقدار غیرمنتظره برگردانده است

این تابع در درجه اول برای استفاده برنامه‌ها در نظر گرفته شده است. برای دریافت یک فهرست ساده از نام‌ها از "ls" استفاده کنید. برای دریافت یک دایرکتوری قابل چاپ و خوانا برای انسان، از "ll" استفاده کنید.

readlink

readlink path

این دستور هدف یک پیوند نمادین (symbolic link) را می‌خواند.

readlinklist

readlinklist path 'names ...'

این فراخوانی به شما امکان می‌دهد عملیات "readlink" را روی چندین فایل انجام دهید، که در آن تمام فایل‌ها در دایرکتوری "path" قرار دارند. "names" فهرست فایل‌های این دایرکتوری است.

در خروجی، فهرستی از رشته‌ها دریافت می‌کنید که مطابقت یک‌به‌یک با فهرست "names" دارد. هر رشته مقدار پیوند نمادین است.

اگر عملیات readlink(2) روی هر نامی شکست بخورد، رشته نتیجه مربوطه یک رشته خالی "" خواهد بود. با این حال، کل عملیات حتی در صورت وجود خطاهای readlink(2) تکمیل می‌شود، بنابراین می‌توانید این تابع را با نام‌هایی فراخوانی کنید که مطمئن نیستید آیا قبلاً پیوند نمادین بوده‌اند یا خیر (البته با کارایی اندکی کمتر).

این فراخوانی برای برنامه‌هایی در نظر گرفته شده است که می‌خواهند بدون رفت‌وبرگشت‌های متعدد، محتویات یک دایرکتوری را به طور بهینه فهرست کنند..SS realpath

realpath path

مسیر نام کامل و استانداردشده (canonicalized) مربوط به "path" را بازمی‌گرداند. مسیر بازگردانده‌شده فاقد اجزای مسیر "."، ".." یا پیوندهای نمادین است.

remount

remount mountpoint [rw:true|false]

این فراخوانی به شما امکان می‌دهد فلگ "rw" (فقط‌خواندنی/خواندنی-نوشتنی) را روی یک سیستم‌فایل از پیش سوارشده در "mountpoint" تغییر دهید، و یک سیستم‌فایل فقط‌خواندنی را به خواندنی-نوشتنی یا برعکس تبدیل کنید.

توجه داشته باشید که در حال حاضر باید پارامتر "اختیاری" "rw" را مشخص کنید. در آینده ممکن است اجازه تغییر سایر فلگ‌ها نیز داده شود.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "آرگومان‌های اختیاری" را ببینید.

remove-drive

remove-drive label

این فراخوانی هیچ کاری انجام نمی‌دهد و یک خطا برمی‌گرداند.

این تابع منسوخ شده است. هیچ جایگزینی وجود ندارد. برای اطلاعات بیشتر به مستندات API در guestfs(3) مراجعه کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

removexattr

removexattr xattr path

این فراخوانی صفت گسترش‌یافته با نام "xattr" را از فایل "path" حذف می‌کند.

همچنین ببینید: "lremovexattr"، attr(5).

این دستور به ویژگی "linuxxattrs" وابسته است. همچنین ببینید "feature-available".

rename

rename oldpath newpath

تغییر نام یک فایل به مکانی جدید در همان سیستم‌فایل. این معادل فراخوانی سیستمی rename(2) در لینوکس است. در بیشتر موارد بهتر است به جای آن از "mv" استفاده کنید.

resize2fs

resize2fs device

این دستور اندازه یک سیستم‌فایل ext2، ext3 یا ext4 را متناسب با اندازه دستگاه زیرین تغییر می‌دهد.

همچنین بخش "خطاهای RESIZE2FS" در guestfs(3) را ببینید.

resize2fs-M

resize2fs-M device

این دستور مشابه "resize2fs" است، با این تفاوت که اندازه سیستم‌فایل به حداقل اندازه ممکن کاهش می‌یابد. عملکرد این دستور مانند گزینه -M در دستور resize2fs(8) است.

برای به‌دست آوردن اندازه حاصل از سیستم‌فایل، باید "tune2fs-l" را فراخوانی کرده و مقادیر "Block size" و "Block count" را بخوانید. حاصل‌ضرب این دو عدد، اندازه سیستم‌فایل مینیمال را به بایت نشان می‌دهد.

همچنین بخش "خطاهای RESIZE2FS" در guestfs(3) را ببینید.

resize2fs-size

resize2fs-size device size

این دستور مشابه "resize2fs" است با این تفاوت که به شما امکان می‌دهد اندازه جدید (به بایت) را به طور صریح مشخص کنید.

همچنین بخش "خطاهای RESIZE2FS" در guestfs(3) را ببینید.

rm

rm path

فایل تکی "path" را حذف می‌کند.

rm-f

rm-f path

فایل "path" را حذف می‌کند.

اگر فایل وجود نداشته باشد، از آن خطا صرف‌نظر می‌شود. (سایر خطاها مانند خطاهای I/O یا مسیرهای نامعتبر نادیده گرفته نمی‌شوند).

این فراخوانی نمی‌تواند دایرکتوری‌ها را حذف کند. از "rmdir" برای حذف دایرکتوری خالی، یا از "rm-rf" برای حذف بازگشتی دایرکتوری‌ها استفاده کنید.

rm-rf

rm-rf path

فایل یا دایرکتوری "path" را حذف می‌کند، و در صورتی که دایرکتوری باشد محتویات آن را به صورت بازگشتی پاک می‌کند. این دستور شبیه به دستور پوسته "rm -rf" است.

rmdir

rmdir path

دایرکتوری تکی "path" را حذف می‌کند.

rmmountpoint

rmmountpoint exemptpath

این فراخوانی نقطه اتصالی را که قبلاً با "mkmountpoint" ایجاد شده بود حذف می‌کند. برای جزئیات کامل "mkmountpoint" را ببینید.

rsync

rsync src dest [archive:true|false] [deletedest:true|false]

این فراخوانی می‌تواند برای کپی یا همگام‌سازی دو دایرکتوری تحت یک هندل libguestfs یکسان استفاده شود. این دستور از برنامه rsync(1) استفاده می‌کند که از یک الگوریتم سریع برای جلوگیری از کپی‌های غیرضروری فایل‌ها بهره می‌برد.

مقادیر "src" و "dest" دایرکتوری‌های مبدأ و مقصد هستند. فایل‌ها از "src" به "dest" کپی می‌شوند.

آرگومان‌های اختیاری عبارتند از:

"archive"

حالت بایگانی (archive) را فعال می‌کند. این معادل ارسال فلگ --archive به "rsync" است.

"deletedest"

فایل‌هایی را در مقصد که در مبدأ وجود ندارند حذف می‌کند.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "آرگومان‌های اختیاری" را ببینید.

این دستور به ویژگی "rsync" وابسته است. همچنین ببینید "feature-available".

rsync-in

rsync-in remote dest [archive:true|false] [deletedest:true|false]

این فراخوانی می‌تواند برای کپی یا همگام‌سازی سیستم‌فایل روی میزبان یا روی یک رایانه دوردست با سیستم‌فایل درون libguestfs استفاده شود. این دستور از برنامه rsync(1) استفاده می‌کند که الگوریتم سریعی برای جلوگیری از کپی غیرضروری فایل‌ها دارد.

این فراخوانی تنها در صورتی کار می‌کند که شبکه فعال باشد. "set-network" یا گزینه --network در ابزارهای مختلف مانند guestfish(1) را ببینید.

فایل‌ها از سرور و دایرکتوری دوردست مشخص‌شده توسط "remote" به دایرکتوری مقصد "dest" کپی می‌شوند.

قالب رشته سرور دوردست توسط rsync(1) تعریف می‌شود. توجه داشته باشید که هیچ راهی برای ارائه گذرواژه یا عبارت عبور وجود ندارد، بنابراین مقصد باید طوری تنظیم شده باشد که نیازی به گذرواژه نداشته باشد.

آرگومان‌های اختیاری همانند آرگومان‌های "rsync" هستند.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "آرگومان‌های اختیاری" را ببینید.

این دستور به ویژگی "rsync" وابسته است. همچنین ببینید "feature-available".

rsync-out

rsync-out src remote [archive:true|false] [deletedest:true|false]

این فراخوانی می‌تواند برای کپی یا همگام‌سازی سیستم‌فایل درون libguestfs با یک سیستم‌فایل روی میزبان یا یک رایانه دوردست استفاده شود. این دستور از برنامه rsync(1) استفاده می‌کند که از الگوریتمی سریع برای جلوگیری از کپی‌های غیرضروری فایل‌ها بهره می‌برد.

این فراخوانی تنها در صورتی کار می‌کند که شبکه فعال باشد. "set-network" یا گزینه --network در ابزارهای گوناگون مانند guestfish(1) را ببینید.

فایل‌ها از دایرکتوری مبدأ "src" به سرور و دایرکتوری دوردست مشخص‌شده توسط "remote" کپی می‌شوند.

قالب رشته سرور دوردست توسط rsync(1) تعریف می‌شود. توجه داشته باشید که روشی برای وارد کردن گذرواژه یا عبارت عبور وجود ندارد، بنابراین مقصد باید به گونه‌ای پیکربندی شود که نیازی به آن نباشد.

آرگومان‌های اختیاری همانند آرگومان‌های "rsync" هستند.

تطبیق الگو (Globbing) روی پارامتر "src" اعمال نمی‌شود. در برنامه‌هایی که مستقیماً از API استفاده می‌کنند، باید خودتان نویسه‌های عام (wildcards) را گسترش دهید (بخش "glob-expand" را ببینید). در guestfish می‌توانید از دستور "glob" استفاده کنید (بخش "glob" را ببینید)، برای نمونه:

><fs> glob rsync-out /* rsync://remote/

این دستور یک یا چند آرگومان اختیاری دارد. بخش "آرگومان‌های اختیاری" را ببینید.

این دستور به ویژگی "rsync" وابسته است. همچنین ببینید "feature-available".

scrub-device

scrub-device device

این دستور الگوهایی را روی "device" می‌نویسد تا بازیابی داده‌ها بسیار دشوارتر شود.

این یک رابط برای برنامه scrub(1) است. برای جزئیات بیشتر به صفحه راهنمای آن برنامه مراجعه کنید.

این دستور به ویژگی "scrub" وابسته است. همچنین ببینید "feature-available".

scrub-file

scrub-file file

این دستور الگوهایی را روی یک فایل می‌نویسد تا بازیابی داده‌ها دشوارتر شود.

فایل پس از پاک‌سازی امن (scrubbing) حذف می‌شود.

این یک رابط برای برنامه scrub(1) است. برای جزئیات بیشتر به صفحه راهنمای آن مراجعه کنید.

این دستور به ویژگی "scrub" وابسته است. همچنین ببینید "feature-available".

scrub-freespace

scrub-freespace dir

این دستور دایرکتوری "dir" را ایجاد کرده و سپس آن را با فایل‌ها پر می‌کند تا سیستم‌فایل پر شود، و فایل‌ها را مانند "scrub-file" پاک‌سازی امن کرده و آن‌ها را حذف می‌کند. هدف این است که تمام فضای خالی روی پارتیشن حاوی "dir" پاک‌سازی امن شود.

این یک رابط برای برنامه scrub(1) است. برای جزئیات بیشتر به صفحه راهنمای آن برنامه مراجعه کنید.

این دستور به ویژگی "scrub" وابسته است. همچنین ببینید "feature-available".

selinux-relabel

selinux-relabel specfile path [force:true|false]

برچسب‌گذاری مجدد SELinux روی بخش‌هایی از سیستم‌فایل.

پارامتر "specfile" فایل مشخصات خط‌مشی (policy spec file) مورد استفاده را کنترل می‌کند. شما باید "/etc/selinux/config" را برای یافتن خط‌مشی صحیح SELinux تجزیه کنید و سپس فایل مشخصات را ارسال نمایید، معمولاً: "/etc/selinux/" + selinuxtype + "/contexts/files/file_contexts".

پارامتر الزامی "path" دایرکتوری سطح بالایی است که برچسب‌گذاری مجدد از آنجا آغاز می‌شود. معمولاً باید "path" را برابر "/" قرار دهید تا کل سیستم‌فایل مهمان مجدداً برچسب‌گذاری شود.

مقدار بولی اختیاری "force" کنترل می‌کند که آیا زمینه امنیتی برای فایل‌های سفارشی‌سازی‌پذیر بازنشانی شود یا خیر، و همچنین مشخص می‌کند که بخش‌های کاربر، نقش و محدوده زمینه فایل تغییر کنند یا خیر.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "آرگومان‌های اختیاری" را ببینید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "setfiles" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده درست از این توابع است.

این دستور به ویژگی "selinuxrelabel" وابسته است. همچنین ببینید "feature-available".

set-append

append

set-append append

این تابع برای افزودن گزینه‌های اضافی به خط فرمان هسته اپلاینس libguestfs استفاده می‌شود.

مقدار پیش‌فرض "NULL" است مگر اینکه با تنظیم متغیر محیطی "LIBGUESTFS_APPEND" لغو شود.

تنظیم "append" روی "NULL" به این معنی است که هیچ گزینه اضافی ارسال نمی‌شود (libguestfs همیشه چند گزینه مخصوص به خود را اضافه می‌کند).

set-attach-method

attach-method

set-attach-method backend

روشی را تعیین می‌کند که libguestfs برای اتصال به دیمن بک‌اند guestfsd استفاده می‌کند.

بخش "بک‌اند" در guestfs(3) را ببینید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "set-backend" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

set-autosync

autosync

set-autosync true|false

اگر "autosync" برابر با true باشد، همگام‌سازی خودکار را فعال می‌کند. Libguestfs نهایت تلاش خود را خواهد کرد تا هنگام بسته شدن هندل (و همچنین اگر برنامه بدون بستن هندل‌ها خارج شود)، سیستم‌فایل‌ها سازگار و همگام شوند.

این ویژگی به صورت پیش‌فرض فعال است (از libguestfs 1.5.24 به بعد، قبلاً به طور پیش‌فرض غیرفعال بود).

set-backend

backend

set-backend backend

روشی را تعیین می‌کند که libguestfs برای اتصال به دیمن بک‌اند guestfsd استفاده می‌کند.

این ویژگی هندل قبلاً "attach method" نامیده می‌شد.

بخش "بک‌اند" در guestfs(3) را ببینید.

set-backend-setting

set-backend-setting name val

رشته "name=value" را به فهرست رشته‌های تنظیمات بک‌اند اضافه می‌کند. با این حال اگر از قبل رشته‌ای مطابق با "name" وجود داشته باشد یا با "name=" شروع شود، آن تنظیم جایگزین می‌گردد.

بخش‌های "بک‌اند" در guestfs(3) و "تنظیمات بک‌اند" در guestfs(3) را ببینید.

set-backend-settings

set-backend-settings 'settings ...'

فهرستی از صفر یا چند تنظیم را تعیین می‌کند که به بک‌اند جاری ارسال می‌شوند. هر تنظیم رشته‌ای است که به روش خاص همان بک‌اند تفسیر می‌شود، یا در صورت عدم پشتیبانی توسط بک‌اند نادیده گرفته می‌شود.

مقدار پیش‌فرض یک فهرست خالی است، مگر اینکه متغیر محیطی "LIBGUESTFS_BACKEND_SETTINGS" هنگام ایجاد هندل تنظیم شده باشد. این متغیر محیطی شامل فهرستی از تنظیمات است که با دونقطه (:) از هم جدا شده‌اند.

این فراخوانی تمام تنظیمات بک‌اند را جایگزین می‌کند. اگر می‌خواهید یک تنظیم منفرد بک‌اند را تغییر دهید، "set-backend-setting" را ببینید. اگر می‌خواهید یک تنظیم بک‌اند را پاک کنید، "clear-backend-setting" را ببینید.

بخش‌های "بک‌اند" در guestfs(3) و "تنظیمات بک‌اند" در guestfs(3) را ببینید.

set-cachedir

cachedir

set-cachedir cachedir

دایرکتوری مورد استفاده توسط هندل برای ذخیره حافظه پنهان (cache) اپلاینس را هنگام استفاده از اپلاینس supermin تعیین می‌کند. اپلاینس بین تمامی هندل‌هایی که شناسه کاربری مؤثر (effective user ID) یکسانی دارند، کش شده و به اشتراک گذاشته می‌شود.

متغیرهای محیطی "LIBGUESTFS_CACHEDIR" و "TMPDIR" مقدار پیش‌فرض را کنترل می‌کنند: اگر "LIBGUESTFS_CACHEDIR" تنظیم شده باشد، همان مقدار پیش‌فرض است. در غیر این صورت اگر "TMPDIR" تنظیم شده باشد، آن مقدار پیش‌فرض خواهد بود. در غیر این صورت /var/tmp مقدار پیش‌فرض است.

set-direct

direct

set-direct true|false

اگر فلگ حالت مستقیم اپلاینس (direct appliance mode) فعال باشد، پس از راه‌اندازی اپلاینس، stdin و stdout مستقیماً به اپلاینس منتقل می‌شوند.

یکی از پیامدهای این امر این است که پیام‌های لاگ توسط کتابخانه دریافت نشده و توسط "set-log-message-callback" مدیریت نمی‌شوند، بلکه مستقیماً به stdout می‌روند.

احتمالاً نیازی به استفاده از این مورد نخواهید داشت مگر اینکه بدانید دقیقاً چه کاری انجام می‌دهید.

مقدار پیش‌فرض غیرفعال است.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "internal-get-console-socket" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده درست از این توابع است.

set-e2attrs

set-e2attrs file attrs [clear:true|false]

این تابع صفت‌های فایل "attrs" مرتبط با اینود file را تنظیم یا پاک می‌کند.

"attrs" رشته‌ای از نویسه‌ها است که صفت‌های فایل را نشان می‌دهند. برای فهرستی از صفت‌های ممکن به "get-e2attrs" مراجعه کنید. همه صفت‌ها قابل تغییر نیستند.

اگر مقدار بولی اختیاری "clear" وجود نداشته باشد یا false باشد، صفت‌های ذکر شده در "attrs" در اینود تنظیم می‌شوند.

اگر "clear" برابر با true باشد، صفت‌های ذکر شده در "attrs" در اینود پاک می‌شوند.

در هر دو حالت، سایر صفت‌هایی که در رشته "attrs" وجود ندارند بدون تغییر باقی می‌مانند.

این صفت‌ها فقط زمانی وجود دارند که فایل روی یک سیستم‌فایل ext2/3/4 قرار داشته باشد. استفاده از این فراخوانی روی انواع دیگر سیستم‌فایل منجر به خطا خواهد شد.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "آرگومان‌های اختیاری" را ببینید.

set-e2generation

set-e2generation file generation

این دستور نسل فایل (generation) را در سیستم‌فایل ext2 برای یک فایل تنظیم می‌کند.

بخش "get-e2generation" را ببینید.

set-e2label

set-e2label device label

برچسب سیستم‌فایل ext2/3/4 را روی "device" به "label" تنظیم می‌کند. برچسب‌های سیستم‌فایل به ۱۶ نویسه محدود هستند.

می‌توانید از "tune2fs-l" یا "get-e2label" برای بازگرداندن برچسب موجود روی یک سیستم‌فایل استفاده کنید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "set-label" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده درست از این توابع است.

set-e2uuid

set-e2uuid device uuid

شناسه UUID سیستم‌فایل ext2/3/4 را روی "device" به "uuid" تنظیم می‌کند. قالب UUID و گزینه‌های جایگزین مانند "clear"، "random" و "time" در صفحه راهنمای tune2fs(8) توضیح داده شده‌اند.

می‌توانید از "vfs-uuid" برای بازگرداندن UUID موجود یک سیستم‌فایل استفاده کنید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "set-uuid" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

set-hv

hv

set-hv hv

فایل اجرایی باینری هایپروایزری را که استفاده خواهیم کرد تعیین می‌کند. هایپروایزر به بک‌اند بستگی دارد، اما معمولاً محل هایپروایزر qemu/KVM است.

همچنین می‌توانید با تنظیم متغیر محیطی "LIBGUESTFS_HV" این مقدار را لغو و بازنویسی کنید.

توجه داشته باشید که باید این تابع را در اولین زمان ممکن پس از ایجاد هندل فراخوانی کنید. دلیل این امر این است که برخی عملیات‌های پیش از راه‌اندازی به آزمایش ویژگی‌های qemu (با اجرای "qemu -help") بستگی دارند. اگر باینری qemu تغییر کند، ویژگی‌ها مجدداً آزمایش نمی‌شوند و ممکن است نتایج متناقضی مشاهده کنید. استفاده از متغیر محیطی "LIBGUESTFS_HV" از همه امن‌تر است، زیرا باینری qemu را همزمان با ایجاد هندل انتخاب می‌کند.

set-identifier

identifier

set-identifier identifier

این یک رشته اطلاعاتی است که فراخواننده می‌تواند به صورت اختیاری در هندل تنظیم کند. این رشته در مکان‌های مختلف چاپ می‌شود و اجازه می‌دهد تا هندل جاری در خروجی‌های اشکال‌زدایی شناسایی شود.

یک مکان مهم زمانی است که قابلیت ردگیری (tracing) فعال باشد. اگر رشته شناسه یک رشته خالی نباشد، پیام‌های ردگیری از این حالت:

libguestfs: trace: get_tmpdir
libguestfs: trace: get_tmpdir = "/tmp"

به این حالت تغییر می‌یابند:

libguestfs: trace: ID: get_tmpdir
libguestfs: trace: ID: get_tmpdir = "/tmp"

که در آن "ID" رشته شناسه‌ای است که توسط این فراخوانی تنظیم شده است.

شناسه باید فقط شامل نویسه‌های اسکی الفبایی-عددی، زیرخط و علامت منفی باشد. مقدار پیش‌فرض رشته خالی است.

همچنین ببینید: "set-program"، "set-trace"، "get-identifier".

set-label

set-label mountable label

برچسب سیستم‌فایل را روی "mountable" به "label" تنظیم می‌کند.

تنها برخی از انواع سیستم‌فایل از برچسب‌ها پشتیبانی می‌کنند، و libguestfs فقط از تنظیم برچسب روی زیرمجموعه‌ای از این موارد پشتیبانی می‌کند.

ext2, ext3, ext4

برچسب‌ها به ۱۶ بایت محدود هستند.

NTFS

برچسب‌ها به ۱۲۸ نویسه یونیکد محدود هستند.

XFS

برچسب به ۱۲ بایت محدود است. سیستم‌فایل نباید هنگام تنظیم برچسب سوار (mounted) باشد.

btrfs

برچسب به ۲۵۵ بایت محدود است و برخی نویسه‌ها مجاز نیستند. تنظیم برچسب روی یک زیرحجم (subvolume) btrfs، برچسب را روی سیستم‌فایل والد آن تنظیم می‌کند. سیستم‌فایل نباید هنگام تنظیم برچسب سوار باشد.

fat

برچسب به ۱۱ بایت محدود است.

swap

برچسب به ۱۶ بایت محدود است.

اگر هیچ پشتیبانی برای تغییر برچسب نوع سیستم‌فایل مشخص‌شده وجود نداشته باشد، set_label با شکست مواجه شده و errno را روی ENOTSUP تنظیم می‌کند.

برای خواندن برچسب روی یک سیستم‌فایل، "vfs-label" را فراخوانی کنید.

set-libvirt-requested-credential

set-libvirt-requested-credential index cred

پس از درخواست اعتبارنامه "index"-اُم از کاربر، این تابع را فراخوانی کنید تا پاسخ را به libvirt بازگرداند.

برای مستندات و نمونه کد، بخش "احراز هویت LIBVIRT" در guestfs(3) را ببینید.

set-libvirt-supported-credentials

set-libvirt-supported-credentials 'creds ...'

این تابع را پیش از تنظیم یک گرداننده رویداد (event handler) برای "GUESTFS_EVENT_LIBVIRT_AUTH" فراخوانی کنید تا فهرستی از انواع اعتبارنامه‌هایی را که برنامه نحوه پردازش آن‌ها را می‌داند ارائه دهد.

فهرست "creds" باید یک فهرست غیرخالی از رشته‌ها باشد. رشته‌های ممکن عبارتند از:

"username"

"authname"

"language"

"cnonce"

"passphrase"

"echoprompt"

"noechoprompt"

"realm"

"external"

برای آگاهی از مفهوم این انواع اعتبارنامه، به مستندات libvirt مراجعه کنید.

برای مستندات و نمونه کد، بخش "احراز هویت LIBVIRT" در guestfs(3) را ببینید.

set-memsize

memsize

set-memsize memsize

این دستور مقدار حافظه اختصاص‌یافته به هایپروایزر را بر حسب مگابایت تنظیم می‌کند. این مورد تنها در صورتی اثرگذار است که پیش از "launch" فراخوانی شود.

همچنین می‌توانید این مقدار را با تنظیم متغیر محیطی "LIBGUESTFS_MEMSIZE" پیش از ایجاد هندل تغییر دهید.

برای اطلاعات بیشتر در مورد معماری libguestfs، به guestfs(3) مراجعه کنید.

set-network

network

set-network true|false

اگر "network" برابر با true باشد، شبکه در اپلاینس libguestfs فعال می‌شود. مقدار پیش‌فرض false است.

این گزینه بر دسترسی دستورات به شبکه تأثیر می‌گذارد (بخش "اجرای دستورات" در guestfs(3) را ببینید).

شما باید این تابع را پیش از فراخوانی "launch" اجرا کنید، در غیر این صورت هیچ اثری نخواهد داشت.

set-path

path

set-path searchpath

مسیری را که libguestfs برای جستجوی kernel و initrd.img استفاده می‌کند تنظیم می‌کند.

مقدار پیش‌فرض "$libdir/guestfs" است مگر اینکه با تنظیم متغیر محیطی "LIBGUESTFS_PATH" لغو شود.

تنظیم "path" روی "NULL" مسیر پیش‌فرض را بازیابی می‌کند.

set-pgroup

pgroup

set-pgroup true|false

اگر "pgroup" برابر با true باشد، فرآیندهای فرزند در گروه فرآیندی اختصاصی خود قرار می‌گیرند.

نتیجه عملی این امر این است که سیگنال‌هایی مانند "SIGINT" (ناشی از فشردن "^C" توسط کاربر) توسط فرآیند فرزند دریافت نخواهند شد.

مقدار پیش‌فرض این فلگ false است، زیرا معمولاً تمایل دارید "^C" زیرفرآیند را متوقف کند. Guestfish هنگام استفاده تعاملی این فلگ را روی true تنظیم می‌کند تا "^C" بتواند دستورات طولانی را به طور مناسب لغو کند (بخش "user-cancel" را ببینید).

set-program

program

set-program program

نام برنامه را تنظیم می‌کند. این یک رشته اطلاعاتی است که برنامه اصلی می‌تواند به صورت اختیاری در هندل تنظیم کند.

هنگامی که هندل ایجاد می‌شود، نام برنامه در هندل روی نام پایه (basename) برگرفته از "argv[0]" تنظیم می‌شود. نام برنامه هرگز نمی‌تواند "NULL" باشد.

set-qemu

qemu

set-qemu hv

باینری هایپروایزر (معمولاً qemu) را که استفاده خواهیم کرد تنظیم می‌کند.

همچنین می‌توانید با تنظیم متغیر محیطی "LIBGUESTFS_HV" این مقدار را لغو و بازنویسی کنید.

تنظیم "hv" روی "NULL" باینری پیش‌فرض qemu را بازیابی می‌کند.

توجه داشته باشید که باید این تابع را در اولین زمان ممکن پس از ایجاد هندل فراخوانی کنید. زیرا برخی از عملیات‌های پیش از راه‌اندازی به آزمایش ویژگی‌های qemu (با اجرای "qemu -help") وابسته هستند. اگر باینری qemu تغییر کند، این ویژگی‌ها مجدداً بررسی نمی‌شوند و در نتیجه ممکن است نتایج ناسازگاری مشاهده کنید. استفاده از متغیر محیطی "LIBGUESTFS_HV" امن‌ترین روش است چرا که باینری qemu را دقیقاً همزمان با ساخت هندل تعیین می‌کند.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "set-hv" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

set-recovery-proc

recovery-proc

set-recovery-proc true|false

اگر این تابع با پارامتر "false" فراخوانی شود، "launch" فرآیند بازیابی (recovery process) ایجاد نمی‌کند. هدف فرآیند بازیابی، متوقف کردن فرآیندهای هایپروایزر سرکش در مواردی است که برنامه اصلی به طور ناگهانی خاتمه می‌یابد.

این مورد تنها زمانی اثر دارد که پیش از "launch" فراخوانی شود، و مقدار پیش‌فرض آن true است.

تقریباً تنها زمانی که ممکن است بخواهید این مورد را غیرفعال کنید، هنگامی است که فرآیند اصلی خود را در پس‌زمینه فورک کند ("دیمن" شود). در این حالت، فرآیند بازیابی تصور می‌کند که برنامه اصلی ناپدید شده و بنابراین هایپروایزر را متوقف می‌کند که چندان مطلوب نیست.

set-selinux

selinux

set-selinux true|false

این تابع فلگ selinux را که هنگام بوت به اپلاینس ارسال می‌شود تنظیم می‌کند. مقدار پیش‌فرض "selinux=0" (غیرفعال) است.

توجه داشته باشید که در صورت فعال بودن SELinux، این ابزار همیشه در حالت مداراگر یا Permissive قرار دارد ("enforcing=0").

برای اطلاعات بیشتر در مورد معماری libguestfs، به guestfs(3) مراجعه کنید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "selinux-relabel" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

set-smp

smp

set-smp smp

تعداد پردازنده‌های مجازی اختصاص‌یافته به اپلاینس را تغییر می‌دهد. مقدار پیش‌فرض 1 است. افزایش این مقدار ممکن است کارایی را بهبود بخشد، اگرچه اغلب اثری ندارد.

این تابع باید پیش از "launch" فراخوانی شود.

set-tmpdir

tmpdir

set-tmpdir tmpdir

دایرکتوری مورد استفاده توسط هندل را برای ذخیره فایل‌های موقت تعیین می‌کند.

متغیرهای محیطی "LIBGUESTFS_TMPDIR" و "TMPDIR" مقدار پیش‌فرض را کنترل می‌کنند: اگر "LIBGUESTFS_TMPDIR" تنظیم شده باشد، همان مقدار پیش‌فرض است. در غیر این صورت اگر "TMPDIR" تنظیم شده باشد، آن مقدار پیش‌فرض است. در غیر این صورت /tmp پیش‌فرض خواهد بود.

set-trace

trace

set-trace true|false

اگر فلگ ردگیری دستورات روی 1 تنظیم شود، فراخوانی‌ها، پارامترها و مقادیر بازگشتی libguestfs ردگیری می‌شوند.

اگر می‌خواهید فراخوانی‌های C API به libguestfs (و سایر کتابخانه‌ها) را ردگیری کنید، احتمالاً روش بهتر استفاده از دستور خارجی ltrace(1) است.

ردگیری دستورات غیرفعال است مگر اینکه متغیر محیطی "LIBGUESTFS_TRACE" تعریف شده و روی 1 تنظیم شده باشد.

پیام‌های ردگیری معمولاً به "stderr" فرستاده می‌شوند، مگر اینکه یک کال‌بک ثبت کنید تا آن‌ها را به جای دیگری ارسال کند (به "set-event-callback" مراجعه کنید).

set-uuid

set-uuid device uuid

شناسه UUID سیستم‌فایل را روی "device" به "uuid" تنظیم می‌کند. اگر این عملیات ناموفق باشد و مقدار errno برابر با ENOTSUP گردد، بدین معنی است که هیچ پشتیبانی برای تغییر UUID برای نوع سیستم‌فایل مشخص‌شده وجود ندارد.

تنها برخی از انواع سیستم‌فایل از تنظیم UUID پشتیبانی می‌کنند.

برای خواندن UUID روی یک سیستم‌فایل، "vfs-uuid" را فراخوانی کنید.

set-uuid-random

set-uuid-random device

شناسه UUID سیستم‌فایل را روی "device" به یک UUID تصادفی تنظیم می‌کند. اگر این عملیات ناموفق باشد و مقدار errno برابر با ENOTSUP گردد، بدین معنی است که هیچ پشتیبانی برای تغییر UUID برای نوع سیستم‌فایل مشخص‌شده وجود ندارد.

تنها برخی از انواع سیستم‌فایل از تنظیم UUID پشتیبانی می‌کنند.

برای خواندن UUID روی یک سیستم‌فایل، "vfs-uuid" را فراخوانی کنید.

set-verbose

verbose

set-verbose true|false

اگر "verbose" برابر با true باشد، پیام‌های با جزئیات کامل (verbose) فعال می‌شوند.

پیام‌های با جزئیات کامل غیرفعال هستند مگر اینکه متغیر محیطی "LIBGUESTFS_DEBUG" تعریف شده و روی 1 تنظیم شده باشد.

پیام‌های با جزئیات کامل معمولاً به "stderr" ارسال می‌شوند، مگر اینکه یک کال‌بک برای ارسال آن‌ها به مکانی دیگر ثبت کنید (به "set-event-callback" مراجعه کنید).

setcon

setcon context

این دستور زمینه امنیتی SELinux دیمن را به رشته "context" تنظیم می‌کند.

مستندات مربوط به SELINUX را در guestfs(3) ببینید.

این تابع منسوخ شده است. در کدهای جدید، به جای آن از فراخوانی "selinux-relabel" استفاده کنید.

توابع منسوخ‌شده از API حذف نخواهند شد، اما منسوخ بودن آن‌ها نشان‌دهنده وجود مشکلاتی در استفاده صحیح از این توابع است.

این دستور به ویژگی "selinux" وابسته است. همچنین ببینید "feature-available".

setfiles

setfiles specfile 'paths ...' [force:true|false]

این دستور ابزار "setfiles" در SELinux را اجرا می‌کند که یک ابزار سطح پایین برای برچسب‌گذاری مجدد بخش‌هایی از سیستم‌فایل است.

پارامتر "specfile" فایل مشخصات خط‌مشی مورد استفاده را کنترل می‌کند. شما باید "/etc/selinux/config" را برای یافتن خط‌مشی درست SELinux تجزیه کنید و سپس فایل مشخصات را ارسال نمایید، معمولاً: "/etc/selinux/" + selinuxtype + "/contexts/files/file_contexts".

پارامتر الزامی "paths" فهرستی از دایرکتوری‌های سطح بالا است که برچسب‌گذاری مجدد از آنجا آغاز می‌شود. "setfiles" فقط تا مرزهای سیستم‌فایل برچسب‌گذاری مجدد انجام می‌دهد؛ بنابراین برای نمونه، ارسال "/" کل سیستم‌فایل ریشه را مجدداً برچسب‌گذاری می‌کند، اما سیستم‌فایل‌های سوارشده دیگر را برچسب‌گذاری نمی‌کند. اگر فهرست خالی باشد، setfiles فراخوانی نمی‌شود.

مقدار بولی اختیاری "force" کنترل می‌کند که آیا زمینه برای فایل‌های سفارشی‌سازی‌پذیر بازنشانی شود، و همچنین بخش‌های کاربر، نقش و محدوده زمینه فایل تغییر کنند یا خیر.

این دستور یک یا چند آرگومان اختیاری دارد. بخش "آرگومان‌های اختیاری" را ببینید.

این دستور به ویژگی "selinuxrelabel" وابسته است. همچنین ببینید "feature-available".

setxattr

setxattr xattr val vallen path

این فراخوانی صفت گسترش‌یافته با نام "xattr" را برای فایل "path" به مقدار "val" (با طول "vallen") تنظیم می‌کند. این مقدار داده‌های دلخواه ۸ بیتی است.

همچنین ببینید: "lsetxattr"، attr(5).