.TH PV 1 2026-06-11 pv-1.11.0 "User Commands"
.\"
.SH "نام (NAME)"
pv \- پایش و مدیریت پیشرفت داده‌ها در یک لوله
.\"
.SH "خلاصه دستور (SYNOPSIS)"
.B pv
[\fIOPTION\fR]... [\fIFILE\fR]...
.PP
\fBpv\fR [\fIOPTION\fR]... \fB\-d\fR|\fB\-\-watchfd\fR
\fIPID\fR[:\fIFD\fR]|=\fINAME\fR|@\fILISTFILE\fR...
.PP
\fBpv\fR \fB\-R\fR|\fB\-\-remote\fR \fIPID\fR [\fIOPTION\fR]...
.PP
\fBpv\fR \fB\-Q\fR|\fB\-\-query\fR \fIPID\fR [\fIOPTION\fR]...
.PP
\fBpv\fR [\fIOPTION\fR]... \fB\-M\fR|\fB\-\-monitor\fR \fISIDE\fR \-\- \fICOMMAND\fR [\fIARGS\fR]...
.\"
.SH "توضیحات (DESCRIPTION)"
نمایش میزان پیشرفت داده‌ها در طول یک خط لوله (pipeline) با ارائه اطلاعاتی همچون
زمان سپری‌شده، درصد تکمیل (همراه با نوار پیشرفت)، نرخ توان عملیاتی فعلی،
مجموع داده‌های منتقل‌شده و زمان تخمینی باقی‌مانده (ETA).
نرخ جریان داده، راهبرد مدیریت خطا، اندازه میان‌گیر (buffer) و تعامل با حافظه
نهان (cache) همگی قابل تنظیم هستند.
.PP
هر \fIFILE\fR در خروجی استاندارد کپی می‌شود.
در صورت مشخص نشدن \fIFILE\fR، یا زمانی که \fIFILE\fR برابر \*(lq-\*(rq باشد،
ورودی استاندارد خوانده می‌شود.
.PP
در حالت \*(lq\fB\-\-watchfd\fR\*(rq، یک فرایند دیگر را بررسی کرده و میزان پیشرفت
آن را از طریق فایل‌هایی که باز کرده است نمایش می‌دهد.
.PP
در حالت \*(lq\fB\-\-monitor\fR\*(rq، یک دستور را اجرا کرده و میزان پیشرفت
داده‌ها را از طریق هر دو ورودی استاندارد و خروجی استاندارد آن نمایش می‌دهد.
.\"
.SH "گزینه‌ها (OPTIONS)"
.\"
.SS "کلیدهای نمایش"
اگر هیچ کلید نمایشی مشخص نشده باشد، \fBpv\fR به‌گونه‌ای رفتار می‌کند که گویی
گزینه‌های \*(lq\fB\-\-progress\fR\*(rq، \*(lq\fB\-\-timer\fR\*(rq،
\*(lq\fB\-\-eta\fR\*(rq، \*(lq\fB\-\-rate\fR\*(rq و
\*(lq\fB\-\-bytes\fR\*(rq مشخص شده‌اند.
در غیر این صورت، تنها حالت‌های نمایشی که به‌طور صریح فعال شده‌اند
نشان داده خواهند شد.
.TP
.B \-p, \-\-progress
فعال کردن نوار پیشرفت.
اگر هر یک از ورودی‌ها فایل نباشند، یا غیرقابل خواندن باشند و اندازه‌ای به‌طور
صریح با \*(lq\fB\-\-size\fR\*(rq تعیین نشده باشد، نوار پیشرفت نمی‌تواند میزان
نزدیکی انتقال به پایان را مشخص کند، بنابراین فقط به چپ و راست حرکت می‌کند
تا نشان دهد داده‌ها در حال جابه‌جایی هستند؛ یا با گزینهٔ \*(lq\fB\-\-gauge\fR\*(rq،
نوار نرخ فعلی را به‌صورت درصدی از حداکثر نرخ دیده‌شده تاکنون نشان می‌دهد.
.TP
.B \-t, \-\-timer
فعال کردن زمان‌سنج.
این گزینه کل زمان سپری‌شده از اجرای \fBpv\fR را نمایش می‌دهد.
.TP
.B \-e, \-\-eta
فعال کردن شمارش معکوس ETA (زمان تخمینی اتمام).
این گزینه بر اساس نرخ‌های فعلی انتقال و اندازه کل داده‌ها، مدت‌زمان باقی‌مانده
تا تکمیل کار را برآورد می‌کند.
پیشوند این شمارش معکوس با عبارت \*(lqETA\*(rq نمایش داده می‌شود.
در صورتی که اندازه کل داده‌ها قابل تشخیص نباشد، این گزینه اثری نخواهد داشت.
.TP
.B \-I, \-\-fineta
فعال کردن شمارش معکوس ETA، اما نمایش زمان محلی تخمینی پایان انتقال به جای
مقدار زمان باقی‌مانده.
هنگامی که زمان تخمینی بیش از ۶ ساعت در آینده باشد، تاریخ نیز نمایش داده می‌شود.
پیشوند این زمان با عبارت \*(lqFIN\*(rq (برای زمان پایان) مشخص می‌شود.
همانند \*(lq\fB\-\-eta\fR\*(rq، در صورتی که اندازه کل داده‌ها قابل تشخیص نباشد،
این گزینه اثری نخواهد داشت.
.TP
.B \-r, \-\-rate
فعال کردن شمارنده نرخ انتقال.
این گزینه نرخ فعلی انتقال داده را نمایش می‌دهد.
نرخ در قلاب‌های چهارگوش \*(lq[]\*(rq نمایش داده می‌شود.
.TP
.B \-a, \-\-average\-rate
فعال کردن شمارنده میانگین نرخ انتقال.
این گزینه میانگین نرخ فعلی انتقال داده را، به‌طور پیش‌فرض در بازه ۳۰ ثانیه گذشته
نمایش می‌دهد (به \*(lq\fB\-\-average-rate-window\fR\*(rq مراجعه کنید).
میانگین نرخ در پرانتز \*(lq()\*(rq نمایش داده می‌شود.
.TP
.B \-b, \-\-bytes
فعال کردن شمارنده کل بایت‌ها.
این گزینه مقدار کل داده‌های منتقل‌شده تاکنون را نمایش می‌دهد.
.TP
.B \-T, \-\-buffer\-percent
فعال کردن نمایش درصد میان‌گیر انتقال.
این گزینه درصد استفاده‌شده از میان‌گیر انتقال را نشان می‌دهد.
به‌صورت ضمنی \*(lq\fB\-\-no\-splice\fR\*(rq را فعال می‌کند.
درصد میان‌گیر انتقال در آکولاد \*(lq{}\*(rq نمایش داده می‌شود.
.TP
.BI \-A\  NUM \fR,\ \fB\-\-last\-written\  NUM
نمایش آخرین \fINUM\fR بایت نوشته‌شده.
به‌صورت ضمنی \*(lq\fB\-\-no\-splice\fR\*(rq را فعال می‌کند.
.TP
.BI \-F\  FORMAT \fR,\ \fB\-\-format\  FORMAT
نادیده گرفتن تمام گزینه‌های بالا و استفاده از رشته قالب‌بندی \fIFORMAT\fR
برای تعیین قالب خروجی.
بخش \fBFORMATTING\fR را در زیر ببینید.
.TP
.B \-n, \-\-numeric
خروجی عددی.
به جای ارائه نمایش بصری از پیشرفت، یک درصد عددی صحیح را در هر خط روی
خطای استاندارد می‌نویسد که برای ارسال به ابزارهایی مانند \fBdialog\fR(1) مناسب است.
توجه داشته باشید که در صورت استفاده از \*(lq\fB\-\-numeric\fR\*(rq، نیازی به
\*(lq\fB\-\-force\fR\*(rq نیست.
.IP
ترکیب \*(lq\fB\-\-numeric\fR\*(rq با \*(lq\fB\-\-bytes\fR\*(rq باعث می‌شود
به جای درصد، تعداد بایت‌های پردازش‌شده تا کنون در خروجی نوشته شود.
افزودن \*(lq\fB\-\-line\-mode\fR\*(rq در کنار \*(lq\fB\-\-bytes\fR\*(rq
باعث نوشته شدن تعداد خطوط به جای بایت‌ها یا درصد می‌شود.
افزودن \*(lq\fB\-\-rate\fR\*(rq نرخ انتقال را به هر خط خروجی اضافه می‌کند
(اگر از \*(lq\fB\-\-bytes\fR\*(rq نیز استفاده شده باشد، نرخ پس از شمارش بایت/خط می‌آید).
افزودن \*(lq\fB\-\-timer\fR\*(rq زمان سپری‌شده تاکنون را به عنوان یک عدد اعشاری
بر حسب ثانیه به ابتدای هر خط خروجی اضافه می‌کند.
.IP
ترکیب \*(lq\fB\-\-numeric\fR\*(rq با \*(lq\fB\-\-format\fR\*(rq امکان سفارشی‌سازی
خروجی را فراهم می‌کند. اجزای رشته قالب پیش‌فرض برای \*(lq\fB\-\-numeric\fR\*(rq
به ترتیب عبارتند از:
\*(lq\fB%t\~%b\~%r\~%{progress\-amount\-only}\fR\*(rq
که هر مورد بر اساس قوانین ذکر شده در بالا فعال یا غیرفعال می‌شود (بنابراین حالت
پیش‌فرض بدون مشخص کردن گزینه‌های دیگر \*(lq\fB%{progress\-amount\-only}\fR\*(rq است).
.TP
.B \-q, \-\-quiet
بدون خروجی.
هنگامی که گزینهٔ \*(lq\fB\-\-rate\-limit\fR\*(rq به‌تنهایی برای محدود کردن
نرخ انتقال یک لوله به کار می‌رود، مفید است.
.\".SS "اصلاح‌کننده‌های خروجی (Output modifiers)"
.TP
.B \-8, \-\-bits
استفاده از بیت به جای بایت برای شمارنده‌های بایت و نرخ انتقال.
پسوند خروجی به جای \*(lqB\*(rq برابر با \*(lqb\*(rq خواهد بود.
.TP
.B \-k, \-\-si
نمایش و تفسیر پسوندها به عنوان مضارب ۱۰۰۰ به جای مقدار پیش‌فرض ۱۰۲۴.
توجه داشته باشید که این گزینه تنها بر گزینه‌های پس از خود تأثیر می‌گذارد؛ بنابراین برای یکدستی، این گزینه را در ابتدا مشخص کنید.
.TP
.B \-W, \-\-wait
منتظر ماندن تا زمان انتقال نخستین بایت پیش از نمایش هرگونه اطلاعات پیشرفت یا محاسبهٔ زمان‌های تقریبی پایان (ETA).
برای نمونه، هنگام هدایت (pipe کردن) داده‌ها به ابزارهایی مانند \fBgpg\fR(1) یا \*(lq\fBmysql\~\-p\fR\*(rq از این گزینه استفاده کنید تا شمارش تنها پس از پاسخ به اعلان گذرواژه آغاز شود.
.TP
.BI \-D\  SEC \fR,\ \fB\-\-delay\-start\  SEC
منتظر ماندن تا سپری شدن \fISEC\fR ثانیه پیش از نمایش هرگونه اطلاعات پیشرفت، به طوری که اگر انتقال سریع تمام شود، چیزی نمایش داده نشود.
مقدار \fISEC\fR می‌تواند عددی اعشاری مانند \*(lq0.5\*(rq باشد.
.TP
.BI \-s\  SIZE \fR,\ \fB\-\-size\  SIZE
فرض کردن حجم کل داده‌های در حال انتقال به اندازهٔ \fISIZE\fR بایت هنگام محاسبهٔ درصدها و زمان‌های تقریبی پایان (ETA).
می‌توان یک پسوند \*(lqK\*(rq، \*(lqM\*(rq، \*(lqG\*(rq یا \*(lqT\*(rq را برای مشخص کردن کیبی‌بایت (*1024)، مبی‌بایت، گیبی‌بایت و تبی‌بایت اضافه کرد.
اگر \*(lq\fB\-\-si\fR\*(rq پیش از این گزینه بیاید، پسوندها در عوض نشان‌دهندهٔ کیلوبایت (*1000)، مگابایت و غیره خواهند بود.
.IP
اگر \fISIZE\fR با \*(lq\fB@\fR\*(rq آغاز شود، اندازهٔ فایلی که نامش پس از @ می‌آید استفاده خواهد شد؛ چنانچه آن یک دایرکتوری باشد، اندازهٔ همهٔ فایل‌های زیرمجموعهٔ آن استفاده می‌شود، مانند \*(lq\fBdu\~\-\-apparent\-size\~\-b\fR\*(rq.
.TP
.B \-g, \-\-gauge
اگر نوار پیشرفت نمایش داده شود اما اندازه مشخص نباشد، به جای حرکت دادن نوار به چپ و راست برای نشان دادن پیشرفت، نرخ انتقال فعلی را به صورت درصدی از حداکثر نرخ دیده‌شده تا کنون نمایش می‌دهد.
.TP
.B \-l, \-\-line\-mode
به جای شمارش بایت‌ها، شمارش خط‌ها (نویسه‌های خط جدید).
نوار پیشرفت تنها زمانی حرکت می‌کند که یک خط جدید پیدا شود، و مقدار داده‌شده به \*(lq\fB\-\-size\fR\*(rq به عنوان تعداد خطوط تفسیر خواهد شد.
.IP
اگر این گزینه بدون \*(lq\fB\-\-size\fR\*(rq استفاده شود، \*(lqاندازهٔ کل\*(rq (در این حالت، تعداد کل خطوط) با خواندن کامل همهٔ فایل‌های ورودی برای یک بار پیش از شروع انتقال محاسبه می‌شود.
اگر هر یک از ورودی‌ها لوله‌ها (pipes) یا فایل‌های غیرعادی (non-regular) باشند، یا قابل خواندن نباشند، اندازهٔ کل محاسبه نخواهد شد.
.TP
.B \-0, \-\-null
محاسبهٔ خطوط به عنوان خاتمه‌یافته با یک بایت تهی (null) به جای خط جدید.
این گزینه مستلزم \*(lq\fB\-\-line\-mode\fR\*(rq است.
.TP
.BI \-i\  SEC \fR,\ \fB\-\-interval\  SEC
صبر کردن به مدت \fISEC\fR ثانیه بین هر به‌روزرسانی.
حالت پیش‌فرض به‌روزرسانی در هر ثانیه است.
مقدار \fISEC\fR می‌تواند عددی اعشاری مانند \*(lq0.1\*(rq باشد.
.TP
.BI \-m\  SEC \fR,\ \fB\-\-average-rate-window\  SEC
محاسبهٔ میانگین نرخ فعلی در یک بازهٔ زمانی \fISEC\fR ثانیه‌ای برای محاسبات میانگین نرخ و ETA.
پیش‌فرض ۳۰ ثانیه است.
مقدار باید یک عدد صحیح باشد.
.TP
.BI \-w\  WIDTH \fR,\ \fB\-\-width\  WIDTH
فرض کردن عرض ترمینال به اندازهٔ \fIWIDTH\fR ستون، به جای تشخیص خودکار عرض (یا فرض ۸۰ در صورت شکست در تشخیص).
اگر از این گزینه استفاده شود، در صورتی که عرض ترمینال حین اجرای انتقال تغییر کند، عرض خروجی تنظیم نخواهد شد.
.TP
.BI \-H\  HEIGHT \fR,\ \fB\-\-height\  HEIGHT
فرض کردن ارتفاع ترمینال به اندازهٔ \fIHEIGHT\fR سطر، به جای تشخیص خودکار ارتفاع (یا فرض ۲۵ در صورت شکست در تشخیص).
اگر از این گزینه استفاده شود، در صورتی که ارتفاع ترمینال حین اجرای انتقال تغییر کند، ارتفاع خروجی تنظیم نخواهد شد.
.TP
.BI \-N\  NAME \fR,\ \fB\-\-name\  NAME
قرار دادن \fINAME\fR به عنوان پیشوند در اطلاعات خروجی.
اغلب همراه با \*(lq\fB\-\-cursor\fR\*(rq برای شناسایی هر نوار پیشرفت در یک خط لوله حاوی بیش از یک \fBpv\fR استفاده می‌شود.
.TP
.BI \-u\  STYLE \fR,\ \fB\-\-bar\-style\  STYLE
تغییر سبک پیش‌فرض نوار پیشرفتِ ارائه‌شده توسط \*(lq\fB\-\-progress\fR\*(rq، یا توسط توالی‌های \*(lq\fB\-\-format\fR\*(rq مانند \*(lq\fB%{progress}\fR\*(rq یا \*(lq\fB%{progress\-bar\-only}\fR\*(rq به \fISTYLE\fR.
مقدار \fISTYLE\fR می‌تواند یکی از مقادیر \fBplain\fR (پیش‌فرض)، \fBblock\fR، \fBgranular\fR یا \fBshaded\fR باشد.
این سبک‌ها در بخش \fBFORMATTING\fR در ادامه شرح داده شده‌اند.
.TP
.BI \-x\  SPEC \fR,\ \fB\-\-extra\-display\  SPEC
علاوه بر نمایش پیشرفت در ترمینال، آن را در \fISPEC\fR نیز می‌نویسد.
مقدار \fISPEC\fR باید با فهرستی از مقصدهای جداشده با کاما آغاز شود و می‌تواند به صورت اختیاری با یک دونقطه و یک رشتهٔ قالب‌بندی دنبال گردد.
مقصدها می‌توانند \fBwindowtitle\fR یا \fBwindow\fR برای عنوان پنجرهٔ xterm، و \fBprocesstitle\fR، \fBproctitle\fR، \fBprocess\fR یا \fBproc\fR برای عنوان فرایند نمایش‌یافته توسط \fBps\fR(1) باشند.
اگر رشتهٔ قالب‌بندی ارائه نشود، همان قالب ترمینال استفاده خواهد شد.
برای نمونه، \*(lq\fB\-x\~'window,process:%t\~%b\~%r'\fR\*(rq زمان سپری‌شده، بایت‌های منتقل‌شده و نرخ را هم در عنوان پنجره و هم در عنوان فرایند نمایش می‌دهد.
.TP
.B \-v, \-\-stats
در پایان انتقال، یک خط اضافی شامل کمینه، میانگین، بیشینه و انحراف معیار نرخ انتقال نمایش می‌دهد.
مقادیر همیشه بر حسب بایت بر ثانیه هستند (یا با \*(lq\fB\-\-bits\fR\*(rq بر حسب بیت).
.TP
.B \-f, \-\-force
اجبار خروجی.
به‌طور معمول، اگر خطای استاندارد یک ترمینال نباشد، \fBpv\fR هیچ نمایش بصری در خروجی نخواهد داشت.
این گزینه آن را وادار به انجام این کار می‌کند.
.TP
.B \-c, \-\-cursor
استفاده از توالی‌های فرار موقعیت‌دهی مکان‌نما برای حرکت به سطر اولیهٔ ترمینال هنگام به‌روزرسانی صفحهٔ نمایش، به جای استفادهٔ صرف از carriage return.
این امر اجازه می‌دهد چند نمونهٔ \fBpv\fR پیشرفت را به طور همزمان روی همان ترمینال نمایش دهند.
.IP
برای نمونه:
.IP
.in +4
.EX
pv --cursor --name input file.gz | gzip -d | pv --cursor --name output > file
.EE
.in
.IP
همان‌طور که در مثال مشخص است، این گزینه اغلب همراه با \*(lq\fB\-\-name\fR\*(rq استفاده می‌شود.
.\".SS "تغییردهنده‌های انتقال داده (Data transfer modifiers)"
.TP
.BI \-o\  FILE \fR,\ \fB\-\-output\  FILE
نوشتن داده‌ها در \fIFILE\fR به‌جای خروجی استاندارد.
اگر فایل از قبل وجود داشته باشد، کوتاه‌سازی (truncate) خواهد شد.
.TP
.BI \-L\  RATE \fR,\ \fB\-\-rate-limit\  RATE
محدود کردن انتقال به حداکثر \fIRATE\fR بایت بر ثانیه.
همان پسوندهای مورد استفاده در \*(lq\fB\-\-size\fR\*(rq قابل استفاده هستند.
مقدارهای اعشاری مجاز هستند.
تعیین مقدار 0 محدودیت نرخ را غیرفعال می‌کند، که در صورت استفاده با
\*(lq\fB\-\-remote\fR\*(rq سودمند است.
.TP
.BI \-B\  BYTES \fR,\ \fB\-\-buffer-size\  BYTES
استفاده از اندازهٔ بافر انتقال به مقدار \fIBYTES\fR بایت.
همان پسوندهای مورد استفاده در \*(lq\fB\-\-size\fR\*(rq قابل استفاده هستند.
اندازهٔ پیش‌فرض بافر، اندازهٔ بلوک سیستم‌فایل فایل ورودی
ضرب در ۳۲ (حداکثر 512KiB) است، یا در صورتی که اندازهٔ بلوک
قابل تشخیص نباشد، 400KiB خواهد بود.
این گزینه می‌تواند در بسترهایی مانند macOS با خط‌لوله‌هایی که با
اندازه‌های بافر مشخصی همچون ۱۰۲۴ عملکرد بهتری دارند، مفید باشد.
به‌طور ضمنی \*(lq\fB\-\-no\-splice\fR\*(rq را فعال می‌کند.
.TP
.B \-C, \-\-no-splice
جلوگیری از استفاده از \fBsplice\fR(2) و \fBcopy_file_range\fR(2)، که معمولاً
در سیستم‌های پشتیبانی‌کننده برای بهبود کارایی از طریق حذف نیاز به بافر انتقال
استفاده می‌شوند.
.IP
در حالت پیش‌فرض که \fBsplice\fR(2) یا \fBcopy_file_range\fR(2) به کار
می‌روند، نبود بافر انتقال مانع از کارکرد
\*(lq\fB\-\-buffer\-percent\fR\*(rq و
\*(lq\fB\-\-last\-written\fR\*(rq شده و
\*(lq\fB\-\-buffer\-size\fR\*(rq را بلااستفاده می‌سازد، بنابراین استفاده از هر یک از این گزینه‌ها
به‌طور خودکار \*(lq\fB\-\-no\-splice\fR\*(rq را فعال می‌کند.
.IP
فایل‌های کم‌پشت (sparse) را نمی‌توان با \fBsplice\fR(2) یا
\fBcopy_file_range\fR(2) نوشت، بنابراین استفاده از
\*(lq\fB\-\-sparse\fR\*(rq به‌طور خودکار
\*(lq\fB\-\-no\-splice\fR\*(rq را فعال می‌کند.
.IP
فعال‌کردن \*(lq\fB\-\-no\-splice\fR\*(rq منجر به افت اندک کارایی
انتقال می‌شود.
این گزینه در سیستم‌هایی که \fBsplice\fR(2) و
\fBcopy_file_range\fR(2) در دسترس نیستند، هیچ اثری ندارد.
.TP
.BI \-J\  BYTES \fR,\ \fB\-\-pipe\-buffer\-size\  BYTES
تلاش برای تنظیم اندازهٔ بافر لولهٔ خروجی، و بافر لولهٔ ورودی واسط در صورت نیاز،
به میزان \fIBYTES\fR بایت.
اگر اندازهٔ درخواستی قابل دستیابی نباشد، بدون نمایش خطا هیچ کاری انجام نخواهد شد.
اگر این گزینه مشخص نشود، و هر دوی خروجی و ورودی اول از نوع لوله (pipe) باشند، در صورتی که بافر خروجی
کوچک‌تر باشد، اندازهٔ آن به‌طور خودکار افزایش می‌یابد تا با بافر لولهٔ ورودی مطابقت پیدا کند.
.TP
.B \-E, \-\-skip-errors
نادیده‌گرفتن خطاهای خواندن با تلاش برای پرش از بخش‌های معیوب.
بخش‌های متناظر در خروجی، بایت‌های تهی (null) خواهند بود.
در ابتدا تنها چند بایت نادیده گرفته می‌شود، اما در صورت وقوع خطاهای متعدد
پشت‌سرهم، پرش‌ها به قطعه‌های ۵۱۲ تایی ارتقا می‌یابند.
این ویژگی با هدف تشابه با عملکرد \*(lq\fIdd\~conv=sync,noerror\fR\*(rq طراحی شده است.
.IP
مشخص‌کردن دو بارِ \*(lq\fB\-\-skip\-errors\fR\*(rq باعث می‌شود به‌جای گزارش تک‌تک محدوده‌های
بایتیِ رد شده، خطای خواندن تنها یک بار به ازای هر فایل گزارش شود.
.TP
.BI \-Z\  BYTES \fR,\ \fB\-\-error\-skip\-block\  BYTES
هنگام نادیده‌گرفتن خطاهای خواندن با \*(lq\fB\-\-skip\-errors\fR\*(rq، به‌جای تلاش
برای پرش انطباقی از طریق خواندن مقادیر اندک و پرش از بخش‌های به‌مرور بزرگ‌تر تا زمان موفقیت در خواندن،
به‌محض رخ دادن خطا، به بلوک فایل بعدی با اندازهٔ \fIBYTES\fR بایت پرش کنید.
ممکن است همچنان پرش‌های کوتاه‌تری وجود داشته باشد که در آن‌ها بلوکِ در حال رد شدن با پایان بافر انتقال هم‌زمان شود.
همان پسوندهای مورد استفاده در \*(lq\fB\-\-size\fR\*(rq قابل استفاده هستند.
.IP
این گزینه تنها همراه با \*(lq\fB\-\-skip\-errors\fR\*(rq قابل استفاده است
و برای زمان خواندن از یک دستگاه بلوکی (block device) در نظر گرفته شده است، مانند
\*(lq\fB\-\-skip\-errors\~\-\-error\-skip\-block\~4K\fR\*(rq
تا پرش‌ها در بلوک‌های ۴ کیبی‌بایتی صورت پذیرد.
این کار سرعت خواندن از رسانه‌های معیوب را افزایش می‌دهد، به بهای از دست دادن احتمالی داده‌های بیشتر.
.TP
.B \-S, \-\-stop-at-size
اگر اندازه‌ای با \*(lq\fB\-\-size\fR\*(rq مشخص شده باشد، انتقال داده
به‌محض نوشته شدن آن تعداد بایت متوقف می‌شود، به‌جای آنکه تا پایان ورودی ادامه یابد.
.TP
.B \-Y, \-\-sync
پس از هر عملیات نوشتن، کَش‌های بافر را با \fBsync\fR(2)، یا در صورت امکان با \fBfdatasync\fR(2)،
روی دیسک همگام‌سازی می‌کند.
این گزینه در صورتی که خروجی یک لوله باشد، هیچ اثری ندارد.
استفاده از \*(lq\fB\-\-sync\fR\*(rq ممکن است دقت نوار پیشرفت را هنگام نوشتن روی یک دیسک کُند بهبود بخشد.
.TP
.B \-K, \-\-direct-io
تنظیم پرچم \fBO_DIRECT\fR روی تمام ورودی‌ها و خروجی‌ها، در صورت پشتیبانی.
این کار اثر کَش‌ها را به بهای کاهش کارایی، به حداقل می‌رساند.
به‌دلیل الزامات هم‌ترازی حافظه (memory alignment)، ممکن است باعث شکست در خواندن یا نوشتن
همراه با خطای \*(lqInvalid argument\*(rq شود، به‌ویژه هنگام خواندن و نوشتن فایل‌ها در چندین سیستم‌فایل مختلف در یک فراخوانی واحد \fBpv\fR.
از این گزینه با احتیاط استفاده کنید.
.TP
.B \-O, \-\-sparse
هنگام نوشتن بایت‌های تهی، اقدام به پرش (seek) می‌کند تا یک فایل خروجی کم‌پشت (sparse) ایجاد شود.
به‌طور ضمنی \*(lq\fB\-\-no\-splice\fR\*(rq را فعال می‌کند.
در سیستم‌فایل‌های فاقد پشتیبانی از فایل‌های کم‌پشت، یا هنگامی که خروجی قابلیت پرش (seekable) نداشته باشد،
این گزینه اثری جز روشن کردن \*(lq\fB\-\-no\-splice\fR\*(rq نخواهد داشت.
.TP
.B \-X, \-\-discard
به‌جای انتقال داده‌های ورودی به خروجی استاندارد، آن‌ها را دور می‌ریزد.
این عمل معادل تغییر مسیر خروجی استاندارد به \fI/dev/null\fR است، با این تفاوت که
\fBwrite\fR(2) هرگز فراخوانی نمی‌شود.
.TP
.BI \-U\  FILE \fR,\ \fB\-\-store\-and\-forward\  FILE
به‌جای عبور دادن بلادرنگ داده‌ها، این کار را در دو مرحله انجام می‌دهد - ابتدا
تمام ورودی را خوانده و در \fIFILE\fR می‌نویسد، و پس از اتمام کامل ورودی،
کل \fIFILE\fR را خوانده و آن را در خروجی می‌نویسد.
\fIFILE\fR پس از پایان کار باقی می‌ماند، مگر اینکه
\*(lq\fB-\fR\*(rq مشخص شده باشد، که در این حالت \fBpv\fR یک فایل موقت برای این
منظور ایجاد کرده و پس از اتمام، به‌طور خودکار آن را حذف می‌کند.
.IP
یک کاربرد رایج برای این قابلیت زمانی است که بخشی از یک خط‌لوله داده‌ها را به‌سرعت اما با اندازهٔ نامشخص تولید می‌کند،
و بخش بعدی آن را به‌کندی پردازش می‌نماید.
با دستور \*(lq\fIquick\fR\~\fB|\~pv\~\-U\~\-\~|\fR\~\fIslow\fR\*(rq، یک نوار پیشرفت با اندازهٔ نامشخص برای بخش \fIquick\fR نمایش داده می‌شود،
و سپس نوار دومی با اندازهٔ مشخص و زمان تقریبی پایان (ETA) برای بخش \fIslow\fR نشان داده می‌شود.
.\"
.\".SS "حالت‌های عملیاتی جایگزین"
.TP
\fB\-d\fR, \fB\-\-watchfd\fR \fIPID\fR[:\fIFD\fR]|=\fINAME\fR|@\fILISTFILE\fR...
به جای انتقال داده، توصیف‌گر فایل \fIFD\fR مربوط به فرایند \fIPID\fR را پایش کرده و پیشرفت آن را نمایش می‌دهد.
سایر تغییردهنده‌های انتقال داده \- و کنترل از راه دور \- ممکن است با این گزینه قابل استفاده نباشند.
.IP
اگر یک \fIPID\fR بدون \fIFD\fR مشخص شود، آن فرایند پایش خواهد شد و تمام فایل‌های عادی و دستگاه‌های بلوکی که باز می‌کند با یک نوار پیشرفت نمایش داده خواهند شد.
.IP
اگر یک \fINAME\fR با پیشوند «=» مشخص شود، فرایندهایی با آن نام توسط \fBpgrep\fR(1) پیدا شده و همان‌طور که در بالا توضیح داده شد پایش می‌شوند.
.IP
اگر یک \fILISTFILE\fR با پیشوند «@» مشخص شود، خطوط موجود در آن فایل به عنوان آرگومان‌های اضافی استفاده خواهند شد.
.IP
تمام آرگومان‌های غیرگزینه‌ای باقی‌مانده نیز به عنوان آرگومان‌های اضافی در نظر گرفته خواهند شد.
.IP
فرایند \fBpv\fR زمانی خارج می‌شود که تمام \fIFD\fRها یا به یک فایل دیگر تغییر یافته باشند، حالت خواندن/نوشتن آن‌ها تغییر کرده باشد یا بسته شده باشند، و تمام \fIPID\fRها (بدون \fIFD\fR مشخص) خاتمه یافته باشند.
.TP
.BI \-R\  PID \fR,\ \fB\-\-remote\  PID
کنترل از راه دور نمونهٔ دیگری از \fBpv\fR با شناسه فرایند \fIPID\fR، به‌گونه‌ای که رفتار کند گویی خط فرمان این نمونه به آن داده شده است.
برای مثال، اگر \*(lq\fBpv\~\-\-rate\-limit\~123K\fR\*(rq با شناسه فرایند 9876 در حال اجرا باشد، اجرای
\*(lq\fBpv\~\-\-remote\~9876\~\-\-rate\-limit\~321K\fR\*(rq باعث می‌شود فرایند 9876 به‌جای 123KiB از محدودیت نرخ 321KiB استفاده کند.
توجه داشته باشید که برخی از گزینه‌ها در حین اجرا قابل تغییر نیستند، مانند
\*(lq\fB\-\-cursor\fR\*(rq، \*(lq\fB\-\-line\-mode\fR\*(rq،
\*(lq\fB\-\-force\fR\*(rq، \*(lq\fB\-\-delay\-start\fR\*(rq،
\*(lq\fB\-\-skip\-errors\fR\*(rq و \*(lq\fB\-\-stop\-at\-size\fR\*(rq.
.TP
.BI \-Q\  PID \fR,\ \fB\-\-query\  PID
نمایش پیشرفت انتقال نمونهٔ دیگری از \fBpv\fR با شناسه فرایند \fIPID\fR، متعلق به همان کاربر.
.IP
برخی از تغییردهنده‌های خروجی هنگام استعلام از فرایندی دیگر، تنها در صورتی قابل استفاده هستند که با مقادیر آن فرایند مطابقت داشته باشند \- مانند
\*(lq\fB\-\-line\-mode\fR\*(rq،
\*(lq\fB\-\-null\fR\*(rq و
\*(lq\fB\-\-average\-rate\-window\fR\*(rq.
تغییردهنده‌های انتقال داده هیچ اثری نخواهند داشت.
.TP
.BR \-M " \fISIDE\fR, " \-\-monitor " \fISIDE\fR"
دستور مشخص‌شده توسط آرگومان‌های باقی‌مانده را اجرا می‌کند و بسته به اینکه \fISIDE\fR برابر با \*(lq\fBin\fR\*(rq، \*(lq\fBout\fR\*(rq یا \*(lq\fBboth\fR\*(rq باشد، ورودی استاندارد، خروجی استاندارد یا هر دو را پایش می‌کند.
بعد از تمام گزینه‌های \fBpv\fR از \*(lq\fB\-\-\fR\*(rq استفاده کنید تا گزینه‌های دستور مورد پایش جدا نگه داشته شوند.
.IP
با مقدار \*(lq\fBboth\fR\*(rq برای \fISIDE\fR، دو نوار پیشرفت نمایش داده خواهد شد.
تمام سوییچ‌های نمایشی، تغییردهنده‌های خروجی و تغییردهنده‌های انتقال دادهٔ \fBpv\fR برای هر دو طرف اعمال خواهند شد.
.IP
برای مثال،
\*(lq\fBpv\~\-\-cursor\~\-\-monitor\~both\~\-\-\~gzip\~\-9\fR\*(rq معادل
\*(lq\fBpv\~\-\-cursor\~|\~gzip\~\-9\~|\~pv\~\-\-cursor\fR\*(rq است، با این تفاوت که دومی نمی‌تواند نسبت ورودی به خروجی را نمایش دهد.
.IP
گزینه‌های \*(lq\fB\-\-format\fR\*(rq و \*(lq\fB\-\-name\fR\*(rq را می‌توان دو بار مشخص کرد که در این صورت، مورد اول برای سمت ورودی و مورد دوم برای سمت خروجی اعمال می‌شود.
اگر هیچ گزینهٔ \*(lq\fB\-\-format\fR\*(rq مشخص نشود، قالب پیش‌فرض بر پایهٔ سایر سوییچ‌های نمایشی به شکل معمول استفاده می‌شود، با این تفاوت که وقتی \fISIDE\fR برابر با \*(lq\fBboth\fR\*(rq باشد، نسبت نیز به سمت خروجی افزوده می‌گردد.
.IP
مقادیر \*(lq\fB0\fR\*(rq، \*(lq\fB1\fR\*(rq و \*(lq\fB2\fR\*(rq می‌توانند به عنوان مترادف برای \*(lq\fBin\fR\*(rq، \*(lq\fBout\fR\*(rq و \*(lq\fBboth\fR\*(rq استفاده شوند.
.IP
این گزینه نمی‌تواند همراه با \*(lq\fB\-\-store\-and\-forward\fR\*(rq استفاده شود.
.\"
.SS "سایر گزینه‌ها"
.TP
.BI \-P\  FILE \fR,\ \fB\-\-pidfile\  FILE
شناسه فرایند \fBpv\fR را در \fIFILE\fR ذخیره می‌کند.
اگر فایل از قبل وجود داشته باشد جایگزین می‌شود و هنگام خروج \fBpv\fR حذف خواهد شد.
تا زمانی که \fBpv\fR در حال اجرا است، \fIFILE\fR حاوی یک عدد منفرد \- شناسه فرایند \fBpv\fR \- و به دنبال آن یک خط جدید خواهد بود.
.TP
.B \-h, \-\-help
پیام راهنمای استفاده را در خروجی استاندارد چاپ کرده و با موفقیت خارج می‌شود.
.TP
.B \-V, \-\-version         
اطلاعات نسخه را در خروجی استاندارد چاپ کرده و با موفقیت خارج می‌شود.
.\".SH "قالب‌بندی (FORMATTING)"
رشته‌های قالب استفاده‌شده توسط \*(lq\fB\-\-format\fR\*(rq و
\*(lq\fB\-\-extra\-display\fR\*(rq می‌توانند شامل دنباله‌های زیر باشند:
.TP
.BR %p ", " %{progress}
نوار پیشرفت (در صورتی که اندازه مشخص باشد، با درصد همراه می‌شود).
معادل \*(lq\fB\-\-progress\fR\*(rq.
تا پر کردن فضای باقی‌مانده گسترش می‌یابد، مگر اینکه عددی برای تعیین پهنا به عنوان پیشوند به آن داده شود، مانند \*(lq\fB%20p\fR\*(rq یا \*(lq\fB%20{progress}\fR\*(rq.
.TP
.BR %{progress\-bar\-only}
نوار پیشرفت، بدون کناره‌ها و بدون نمایش درصد پس از آن.
تا پر کردن فضای باقی‌مانده گسترش می‌یابد مگر اینکه عددی به عنوان پیشوند به آن داده شود.
.TP
.B %{progress\-amount\-only}
درصد تکمیل (یا حداکثر نرخ با \*(lq\fB\-\-gauge\fR\*(rq هنگامی که اندازه نامشخص است).
.TP
.B %{bar\-plain}
نوار پیشرفت در قالب متنی ساده و استاندارد، بدون کناره‌ها و بدون نمایش درصد پس از آن.
تا پر کردن فضای باقی‌مانده گسترش می‌یابد مگر اینکه عددی به عنوان پیشوند به آن داده شود.
.TP
.B %{bar\-block}
نوار پیشرفت با استفاده از بلوک‌های کامل یونیکد، بدون کناره‌ها و بدون نمایش درصد پس از آن.
تا پر کردن فضای باقی‌مانده گسترش می‌یابد مگر اینکه عددی به عنوان پیشوند به آن داده شود.
اگر خروجی UTF-8 در دسترس نباشد، از قالب ساده استفاده می‌شود.
.TP
.B %{bar\-granular}
نوار پیشرفت با استفاده از بلوک‌های کامل یونیکد و بلوک‌های ۱/۸ برای پر کردن جزئی، که نمایش دقیق‌تری ارائه می‌دهد.
مانند دیگر رشته‌های \*(lq%{bar}\*(rq، این مورد نوار را بدون کناره‌ها و بدون نمایش درصد پس از آن نشان می‌دهد، و تا پر کردن فضای باقی‌مانده گسترش می‌یابد مگر اینکه عددی به عنوان پیشوند به آن داده شود.
اگر خروجی UTF-8 در دسترس نباشد، از قالب ساده استفاده می‌شود.
.TP
.B %{bar\-shaded}
نوار پیشرفت با استفاده از بلوک‌های کامل یونیکد و نویسه‌های سایه‌دار؛ سایه‌های تیره و متوسط برای پر کردن جزئی و سایه روشن برای پس‌زمینه به کار می‌روند.
مانند دیگر رشته‌های \*(lq%{bar}\*(rq، این مورد نوار را بدون کناره‌ها و بدون نمایش درصد پس از آن نشان می‌دهد، و تا پر کردن فضای باقی‌مانده گسترش می‌یابد مگر اینکه عددی به عنوان پیشوند به آن داده شود.
اگر خروجی UTF-8 در دسترس نباشد، از قالب ساده استفاده می‌شود.
.TP
.BR %t ", " %{timer}
زمان سپری‌شده.
معادل \*(lq\fB\-\-timer\fR\*(rq.
.TP
.BR %e ", " %{eta}
زمان تخمینی باقی‌مانده (ETA).
معادل \*(lq\fB\-\-eta\fR\*(rq.
.TP
.BR %I ", " %{fineta}
زمان تخمینی اتمام انتقال بر اساس ساعت محلی.
معادل \*(lq\fB\-\-fineta\fR\*(rq.
.TP
.BR %r ", " %{rate}
نرخ فعلی انتقال داده.
معادل \*(lq\fB\-\-rate\fR\*(rq.
.TP
.BR %a ", " %{average\-rate}
نرخ میانگین انتقال داده.
معادل \*(lq\fB\-\-average\-rate\fR\*(rq.
.TP
.BR %b ", " %{bytes} ", " %{transferred}
بایت‌های انتقال‌یافته تا این لحظه (یا در صورت مشخص شدن \*(lq\fB\-\-line\-mode\fR\*(rq، سطرها).
معادل \*(lq\fB\-\-bytes\fR\*(rq.
اگر \*(lq\fB\-\-bits\fR\*(rq مشخص شده باشد، \*(lq\fB%b\fR\*(rq بیت‌های انتقال‌یافته تا این لحظه را نشان می‌دهد، نه بایت‌ها.
.TP
.B %{ratio}
نمایش نسبت بایت‌های انتقال‌یافته توسط طرف دیگر به بایت‌های انتقال‌یافته توسط این طرف، در حالت \*(lq\fB\-\-monitor\~both\fR\*(rq.
.TP
.BR %T ", " %{buffer\-percent}
درصد بافر انتقالِ در حال استفاده.
معادل \*(lq\fB\-\-buffer\-percent\fR\*(rq، اما استفاده از آن \*(lq\fB\-\-no\-splice\fR\*(rq را فعال نمی‌کند.
.IP
اگر انتقال از \fBsplice\fR(2) استفاده کند، مقدار \*(lq{\-\-\-\-}\*(rq را نمایش می‌دهد؛ اگر انتقال از \fBsplice\fR(2) از طریق لوله ورودی میانی استفاده کند، \*(lq{\-||\-}\*(rq را نمایش می‌دهد؛ و اگر انتقال از \fBcopy_file_range\fR(2) استفاده کند، \*(lq{\-\-\->}\*(rq را نمایش می‌دهد.
.TP
.BR %nA ", " %n{last\-written}
نمایش آخرین \fIn\fR بایت نوشته‌شده (برای مثال، \*(lq\fB%16A\fR\*(rq آخرین ۱۶ بایت را نشان می‌دهد).
اگر انتقال از \fBsplice\fR(2) یا \fBcopy_file_range\fR(2) استفاده کند، فقط نقطه‌ها را نشان می‌دهد، زیرا این حالت‌های انتقال از بافر استفاده نمی‌کنند.
.TP
.BR %nL ", " %n{previous\-line}
نمایش اولین \fIn\fR بایت از آخرین سطر نوشته‌شده (برای مثال، \*(lq\fB%40L\fR\*(rq ۴۰ بایت اول را نشان می‌دهد).
اگر هیچ \fIn\fR داده نشود، تا پر کردن فضای موجود گسترش می‌یابد.
اگر انتقال از \fBsplice\fR(2) یا \fBcopy_file_range\fR(2) استفاده کند، فقط فاصله‌ها را نشان می‌دهد.
.TP
.BR %N ", " %{name}
نمایش پیشوند نام داده‌شده توسط \*(lq\fB\-\-name\fR\*(rq.
با فاصله‌ها تا ۹ نویسه پر شده و به \*(lq:\*(rq ختم می‌شود.
.TP
.B %{sgr:colour,...}
در صورت پشتیبانی پایانه از رنگ، کدهای ECMA-48 SGR (Select Graphic Rendition) را ارسال می‌کند، که در آن \fIcolour,...\fR فهرستی از هر یک از کلیدواژه‌های زیر با جداکننده کاما یا مقادیر عددی از \fBconsole_codes\fR(4) است. اگر پشتیبانی از رنگ وجود نداشته باشد، چیزی ارسال نمی‌شود.
.IP
کلیدواژه‌های پشتیبانی‌شده عبارتند از:
\fBreset\fR یا \fBnone\fR،
\fBblack\fR،
\fBred\fR،
\fBgreen\fR،
\fBbrown\fR یا \fByellow\fR،
\fBblue\fR،
\fBmagenta\fR،
\fBcyan\fR،
\fBwhite\fR،
\fBfg\-black\fR،
\fBfg\-red\fR،
\fBfg\-green\fR،
\fBfg\-brown\fR یا \fBfg\-yellow\fR،
\fBfg\-blue\fR،
\fBfg\-magenta\fR،
\fBfg\-cyan\fR،
\fBfg\-white\fR،
\fBfg\-default\fR،
\fBbg\-black\fR،
\fBbg\-red\fR،
\fBbg\-green\fR،
\fBbg\-brown\fR یا \fBbg\-yellow\fR،
\fBbg\-blue\fR،
\fBbg\-magenta\fR،
\fBbg\-cyan\fR،
\fBbg\-white\fR،
\fBbg\-default\fR،
\fBbold\fR،
\fBdim\fR،
\fBitalic\fR،
\fBunderscore\fR یا \fBunderline\fR،
\fBblink\fR،
\fBreverse\fR،
\fBno\-bold\fR یا \fBno\-dim\fR،
\fBno\-italic\fR،
\fBno\-underscore\fR یا \fBno\-underline\fR،
\fBno\-blink\fR،
\fBno\-reverse\fR.
.IP
در مورد رنگ‌ها، پیشوند اختیاری "fg-" نشان‌دهنده رنگ متن (پیش‌زمینه) و پیشوند "bg-" نشان‌دهنده رنگ پس‌زمینه است.
.IP
برای مثال، \*(lq\fB%{sgr:green,bold}TEXT%{sgr:reset}\fR\*(rq عبارت \fITEXT\fR را در پایانه‌های پشتیبانی‌شده به صورت سبز پررنگ نمایش می‌دهد.
.TP
.B %%
یک نویسه منفرد \*(lq%\*(rq.
.PP
هر محتوای دیگری بدون تغییر در نمایش پیشرفت نشان داده می‌شود.
.PP
معادل رشته قالب برای سوئیچ‌های نمایش پیش‌فرض عبارت است از \*(lq\fB%b\~%t\~%r\~%p\~%e\fR\*(rq.
.\".SH "مثال‌ها (EXAMPLES)"
برخی از ترکیب‌های پیشنهادی برای گزینه‌های رایج:
.TP
.B pv \-ptebar
نمایش نوار پیشرفت، زمان سپری‌شده، زمان تخمینی تکمیل، شمارنده بایت،
میانگین نرخ و نرخ کنونی.
.TP
.B pv \-betlap
نمایش نوار پیشرفت، زمان سپری‌شده، زمان تخمینی تکمیل، شمارنده خط
و میانگین نرخ، با شمارش خط‌ها به جای بایت‌ها.
.TP
.B pv \-btrpg
نمایش مقدار منتقل‌شده، زمان سپری‌شده، نرخ کنونی و نشانگری که
نرخ کنونی را به‌صورت درصدی از حداکثر نرخ دیده‌شده نشان می‌دهد \- مفید در یک
خط‌لوله هنگامی که اندازه کل نامشخص است.
(اگر اندازه \fIمشخص باشد\fR، این گزینه‌ها به جای نشانگر نرخ، درصد
تکمیل را نشان خواهند داد).
.TP
.B pv \-t
تنها نمایش زمان سپری‌شده \- مفید به‌عنوان یک زمان‌سنج ساده، مانند
\*(lq\fBsleep\~10m\~|\~pv\~\-t\fR\*(rq.
.TP
.B pv \-pterb
رفتار پیش‌فرض: نوار پیشرفت، زمان سپری‌شده، زمان تخمینی
تکمیل، نرخ کنونی و شمارنده بایت.
.PP
در macOS، تعیین \*(lq\fB\-\-buffer\-size\~1024\fR\*(rq
در یک خط‌لوله می‌تواند مفید باشد، چرا که ممکن است کارایی را بهبود بخشد.
.PP
برای مشاهده سرعت انتقال یک فایل با استفاده از \fBnc\fR(1):
.PP
.in +4
.EX
pv file | nc \-w 1 somewhere.com 3000
.EE
.in
.PP
مثالی مشابه برای انتقال یک فایل از فرایندی دیگر و ارسال
اندازه مورد انتظار به \fBpv\fR:
.PP
.in +4
.EX
cat file | pv \-\-size 12345 | nc \-w 1 somewhere.com 3000
.EE
.in
.PP
برای مشاهده پیشرفت ایجاد یک بایگانی tar.gz:
.PP
.in +4
.EX
tar cf \- directory/ \e
| pv \-\-size $(du \-sb directory/ | awk '{print $1}') \e
| gzip \-9 \e
> out.tar.gz
.EE
.in
.PP
روشی دیگر برای انجام همان کار:
.PP
.in +4
.EX
tar cf \- directory/ \e
| pv \-\-size @directory/ \e
| gzip \-9 \e
> out.tar.gz
.EE
.in
.PP
تهیه یک ایمیج از دیسک با نادیده گرفتن خطاها:
.PP
.in +4
.EX
pv \-EE /dev/your/disk/device > disk-image.img
.EE
.in
.PP
نوشتن دوباره یک ایمیج بر روی دیسک:
.PP
.in +4
.EX
pv disk-image.img > /dev/your/disk/device
.EE
.in
.PP
صفر کردن یک دیسک:
.PP
.in +4
.EX
pv < /dev/zero > /dev/your/disk/device
.EE
.in
.PP
توجه داشته باشید که اگر اندازه ورودی قابل محاسبه نباشد و خروجی یک دستگاه
بلوکی باشد، اندازه دستگاه بلوکی استفاده خواهد شد و \fBpv\fR
به‌طور خودکار در آن اندازه متوقف می‌شود، گویی گزینه \*(lq\fB\-\-stop\-at\-size\fR\*(rq
داده شده است.
.PP
(تنها در Linux و macOS): نظارت بر توصیف‌گر فایل ۳ باز شده توسط فرایند دیگری با شناسه 1234:
.PP
.in +4
.EX
pv \-\-watchfd 1234:3
.EE
.in
.PP
(تنها در Linux و macOS): نظارت بر تمام توصیف‌گرهای فایل استفاده‌شده توسط فرایند 1234:
.PP
.in +4
.EX
pv \-\-watchfd 1234
.EE
.in
.PP
محدود کردن نرخ انتقال میان دو فرایند در یک خط‌لوله، بدون هیچ
نمایشی:
.PP
.in +4
.EX
producer | pv \-\-quiet \-\-rate\-limit 1M | consumer
.EE
.in
.PP
ارسال لاگ‌ها به یک اسکریپت پردازشی، به‌همراه نمایش آخرین خط به‌عنوان بخشی از
نمایشگر پیشرفت:
.PP
.in +4
.EX
pv \-\-no\-splice \-\-format '%a %p : %L' big.log | processing-script
.EE
.in
.PP
نمایش پیشرفت به‌صورت خطوطی از داده‌های JSON:
.PP
.in +4
.EX
pv \-\-numeric \-\-format '{"elapsed":%t,"bytes":%b,"rate":%r,"percentage":%{progress-amount-only}}' big.log | processing-script
.EE
.in
.\".SH "وضعیت خروج (EXIT STATUS)"
وضعیت خروج ۱ نشان‌دهندهٔ بروز مشکل در گزینه‌های \*(lq\fB\-\-remote\fR\*(rq،
\*(lq\fB\-\-query\fR\*(rq، \*(lq\fB\-\-pidfile\fR\*(rq یا
\*(lq\fB\-\-monitor\fR\*(rq است.
.PP
هر وضعیت خروج دیگری، یک ماسک بیتی (bitmask) از مقادیر زیر است:
.TP 5
\~\fB2\fR
یک یا چند فایل قابل دسترسی، اجرای \fBstat\fR(2) یا باز شدن نبودند.
.TP
\~\fB4\fR
یک فایل ورودی با فایل خروجی یکسان بود.
.TP
\~\fB8\fR
خطای داخلی در بستن یک فایل یا رفتن به فایل بعدی.
.TP
\~\fB16\fR
هنگام انتقال داده‌ها از یک یا چند فایل ورودی خطایی رخ داد.
.TP
\~\fB32\fR
سیگنالی دریافت شد که باعث خروج زودهنگام گردید.
.TP
\~\fB64\fR
تخصیص حافظه با شکست مواجه شد.
.PP
وضعیت خروج صفر نشان‌دهندهٔ عدم وجود هرگونه مشکل است.
.\"
.SH "محیط (ENVIRONMENT)"
متغیرهای محیطی زیر ممکن است بر \fBpv\fR تأثیر بگذارند:
.TP
.B HOME
دایرکتوری خانگی کاربر فعلی.
این متغیر ممکن است توسط \*(lq\fB\-\-remote\fR\*(rq و \*(lq\fB\-\-query\fR\*(rq
برای تبادل پیام‌ها بین نمونه‌های \fBpv\fR استفاده شود: اگر دایرکتوری \fI/run/user/UID/\fR
وجود نداشته باشد (که در آن \fIUID\fR شناسهٔ کاربر فعلی است)، به‌جای آن از
\fI$HOME/.pv/\fR استفاده خواهد شد.
.TP
.BR TMPDIR ", " TMP
دایرکتوری ایجاد فایل‌های قفل به ازای هر tty برای ترمینال هنگام استفاده از
\*(lq\fB\-\-cursor\fR\*(rq.
اگر \fBTMPDIR\fR روی یک مقدار غیرخالی تنظیم شده باشد، دایرکتوری‌ای است که فایل‌های
قفل در آن ایجاد می‌شوند.
در غیر این صورت، از \fBTMP\fR استفاده می‌شود.
اگر هیچ‌کدام تنظیم نشده باشند، \fI/tmp\fR استفاده خواهد شد.
.\"
.SH "نکات (NOTES)"
در برخی از نسخه‌های \fBbash\fR(1) و \fBzsh\fR(1)، ساختار
\*(lq\fB<(pv\~filename)\fR\*(rq هنگام اجرا در یک شل تعاملی، هیچ پیشرفتی را در ترمینال
نمایش نمی‌دهد، زیرا زیرفرایند در یک گروه فرایندی جدا از گروه مالک ترمینال اجرا می‌شود.
در این موارد، از \*(lq\fB\-\-force\fR\*(rq استفاده کنید.
.PP
اگر \fBpv\fR در یک خط لوله (pipeline) در نسخهٔ 5.8 از \fBzsh\fR استفاده شود، و آخرین
دستور در خط لوله بر پایهٔ دستورهای توکار پوسته (builtins) باشد، \fBzsh\fR کنترل ترمینال را
از \fBpv\fR می‌گیرد و از نمایش پیشرفت جلوگیری می‌کند.
برای نمونه، دستور زیر هیچ نوار پیشرفتی ایجاد نمی‌کند:
.PP
.in +4n
.EX
pv InputFile | { while read \-r line; do sleep 0.1; done; }
.EE
.in
.PP
برای دور زدن این مشکل، دستورهای پایانی خط لوله را در پرانتزهای معمولی
قرار دهید تا استفاده از یک زیرپوسته (subshell) اجباری شود:
.PP
.in +4n
.EX
pv InputFile | ( while read \-r line; do sleep 0.1; done; )
.EE
.in
.PP
برای جزئیات کامل، به
.UR https://codeberg.org/ivarch/pv/issues/105
issue #105
.UE
مراجعه کنید.
.PP
گزینه‌های \*(lq\fB\-\-remote\fR\*(rq و \*(lq\fB\-\-query\fR\*(rq برای ارتباط
بین‌فرایندی، نیازمند قابلیت نوشتن در \fI/run/user/<uid>/\fR
یا \fI$HOME/\fR هستند.
.PP
گزینهٔ \*(lq\fB\-\-size\fR\*(rq در صورت استفاده به همراه
\*(lq\fB\-\-watchfd\fR\~\fIPID\fR\*(rq برای پایش تمام توصیف‌کننده‌های فایل یک فرایند
بی‌اثر است، اما با \*(lq\fB\-\-watchfd\fR\~\fIPID\fR:\fIFD\fR\*(rq
برای پایش یک توصیف‌کنندهٔ فایل منفرد کار خواهد کرد.
.PP
اگر اندازهٔ ورودی قابل محاسبه نباشد و خروجی یک دستگاه بلوکی (block device) باشد،
آنگاه \fBpv\fR اندازهٔ دستگاه خروجی را خوانده، از آن به‌گونه‌ای استفاده می‌کند که گویی
به \*(lq\fB\-\-size\fR\*(rq ارسال شده است، و \*(lq\fB\-\-stop\-at\-size\fR\*(rq را فعال
می‌کند.
.PP
دنباله‌های قالب‌بندی \*(lq\fB%nA\fR\*(rq و \*(lq\fB%nL\fR\*(rq ممکن است
با فایل‌های ورودی کوچک کارآمد نباشند، و \*(lq\fB%nL\fR\*(rq ممکن است به‌دلیل بافر شدن
در درون خود خط لوله، چند خط اختلاف داشته باشد.
.PP
اعدادی که به \*(lq\fB\-\-size\fR\*(rq،
\*(lq\fB\-\-buffer\-size\fR\*(rq، \*(lq\fB\-\-pipe\-buffer\-size\fR\*(rq
و \*(lq\fB\-\-error\-skip\-block\fR\*(rq ارسال می‌شوند در صورت همراه بودن با یک پسوند،
همگی می‌توانند به‌صورت اعداد اعشاری بیان شوند؛ بنابراین برای نمونه \*(lq\fI\-\-size\~1.5G\fR\*(rq
معادل \*(lq\fI\-\-size\~1536M\fR\*(rq است.
.PP
اعدادی که به \*(lq\fB\-\-rate\-limit\fR\*(rq داده می‌شوند می‌توانند با یا بدون پسوند
به‌صورت اعشاری بیان شوند.
.PP
اعدادی که به \*(lq\fB\-\-interval\fR\*(rq و
\*(lq\fB\-\-delay\-start\fR\*(rq داده می‌شوند می‌توانند صحیح یا اعشاری باشند، اما نباید
پسوند داشته باشند.
.PP
اعدادی که به \*(lq\fB\-\-last\-written\fR\*(rq،
\*(lq\fB\-\-width\fR\*(rq، \*(lq\fB\-\-height\fR\*(rq،
\*(lq\fB\-\-average\-rate\-window\fR\*(rq، \*(lq\fB\-\-remote\fR\*(rq و
\*(lq\fB\-\-query\fR\*(rq ارسال می‌شوند باید عدد صحیح بدون پسوند باشند.
.PP
هنگامی که \*(lq\fB\-\-sparse\fR\*(rq فعال است و خروجی در یک فایل نوشته می‌شود،
اگر در هنگام نوشتن بایت‌های تهی (null bytes) وضعیت فایل با \fBls\fR(1) بررسی شود،
ممکن است به نظر برسد که رشد فایل متوقف شده است، هرچند \fBpv\fR همچنان پیشرفت
را گزارش می‌کند.
دلیل این امر نحوهٔ ایجاد خروجی متفرق (sparse) است و فایل پس از پایان انتقال دارای
اندازهٔ صحیح خواهد بود.
.\".SH "گزارش باگ‌ها (REPORTING BUGS)"
لطفاً باگ‌ها یا درخواست‌های قابلیت جدید را از طریق سامانه پیگیری اشکالات پیوند داده‌شده در
.UR https://ivarch.com/p/pv
صفحه خانگی \fBpv\fR
.UE
گزارش دهید.
.\"
.SH "همچنین ببینید (SEE ALSO)"
.BR cat (1),
.BR splice (2),
.BR copy_file_range (2),
.BR fsync (2),
.BR fdatasync (2),
.BR open (2)
(برای \fBO_DIRECT\fR)،
.BR console_codes (4)
.\"
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
حق نشر \(co 2002-2008, 2010, 2012-2015, 2017, 2021, 2023-2026 Andrew Wood.
.PP
مجوز GPLv3+:
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU GPL نسخه ۳ یا بالاتر
.UE .
.PP
این یک نرم‌افزار آزاد است: شما مجاز به تغییر و بازتوزیع آن هستید. هیچ ضمانتی وجود ندارد، تا حدودی که قانون اجازه می‌دهد.
.PP
لطفاً برای فهرست کامل مشارکت‌کنندگان، فایل ACKNOWLEDGEMENTS بسته را ببینید.