کلیدهای نمایش

اگر هیچ کلید نمایشی مشخص نشده باشد، pv به‌گونه‌ای رفتار می‌کند که گویی گزینه‌های “--progress”، “--timer”، “--eta”، “--rate” و “--bytes” مشخص شده‌اند. در غیر این صورت، تنها حالت‌های نمایشی که به‌طور صریح فعال شده‌اند نشان داده خواهند شد.

-p, --progress

فعال کردن نوار پیشرفت. اگر هر یک از ورودی‌ها فایل نباشند، یا غیرقابل خواندن باشند و اندازه‌ای به‌طور صریح با “--size” تعیین نشده باشد، نوار پیشرفت نمی‌تواند میزان نزدیکی انتقال به پایان را مشخص کند، بنابراین فقط به چپ و راست حرکت می‌کند تا نشان دهد داده‌ها در حال جابه‌جایی هستند؛ یا با گزینهٔ “--gauge”، نوار نرخ فعلی را به‌صورت درصدی از حداکثر نرخ دیده‌شده تاکنون نشان می‌دهد.

-t, --timer

فعال کردن زمان‌سنج. این گزینه کل زمان سپری‌شده از اجرای pv را نمایش می‌دهد.

-e, --eta

فعال کردن شمارش معکوس ETA (زمان تخمینی اتمام). این گزینه بر اساس نرخ‌های فعلی انتقال و اندازه کل داده‌ها، مدت‌زمان باقی‌مانده تا تکمیل کار را برآورد می‌کند. پیشوند این شمارش معکوس با عبارت “ETA” نمایش داده می‌شود. در صورتی که اندازه کل داده‌ها قابل تشخیص نباشد، این گزینه اثری نخواهد داشت.

-I, --fineta

فعال کردن شمارش معکوس ETA، اما نمایش زمان محلی تخمینی پایان انتقال به جای مقدار زمان باقی‌مانده. هنگامی که زمان تخمینی بیش از ۶ ساعت در آینده باشد، تاریخ نیز نمایش داده می‌شود. پیشوند این زمان با عبارت “FIN” (برای زمان پایان) مشخص می‌شود. همانند “--eta”، در صورتی که اندازه کل داده‌ها قابل تشخیص نباشد، این گزینه اثری نخواهد داشت.

-r, --rate

فعال کردن شمارنده نرخ انتقال. این گزینه نرخ فعلی انتقال داده را نمایش می‌دهد. نرخ در قلاب‌های چهارگوش “[]” نمایش داده می‌شود.

-a, --average-rate

فعال کردن شمارنده میانگین نرخ انتقال. این گزینه میانگین نرخ فعلی انتقال داده را، به‌طور پیش‌فرض در بازه ۳۰ ثانیه گذشته نمایش می‌دهد (به “--average-rate-window” مراجعه کنید). میانگین نرخ در پرانتز “()” نمایش داده می‌شود.

-b, --bytes

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

-T, --buffer-percent

فعال کردن نمایش درصد میان‌گیر انتقال. این گزینه درصد استفاده‌شده از میان‌گیر انتقال را نشان می‌دهد. به‌صورت ضمنی “--no-splice” را فعال می‌کند. درصد میان‌گیر انتقال در آکولاد “{}” نمایش داده می‌شود.

-A NUM, --last-written NUM

نمایش آخرین NUM بایت نوشته‌شده. به‌صورت ضمنی “--no-splice” را فعال می‌کند.

-F FORMAT, --format FORMAT

نادیده گرفتن تمام گزینه‌های بالا و استفاده از رشته قالب‌بندی FORMAT برای تعیین قالب خروجی. بخش FORMATTING را در زیر ببینید.

-n, --numeric

خروجی عددی. به جای ارائه نمایش بصری از پیشرفت، یک درصد عددی صحیح را در هر خط روی خطای استاندارد می‌نویسد که برای ارسال به ابزارهایی مانند dialog(1) مناسب است. توجه داشته باشید که در صورت استفاده از “--numeric”، نیازی به “--force” نیست.

ترکیب “--numeric” با “--bytes” باعث می‌شود به جای درصد، تعداد بایت‌های پردازش‌شده تا کنون در خروجی نوشته شود. افزودن “--line-mode” در کنار “--bytes” باعث نوشته شدن تعداد خطوط به جای بایت‌ها یا درصد می‌شود. افزودن “--rate” نرخ انتقال را به هر خط خروجی اضافه می‌کند (اگر از “--bytes” نیز استفاده شده باشد، نرخ پس از شمارش بایت/خط می‌آید). افزودن “--timer” زمان سپری‌شده تاکنون را به عنوان یک عدد اعشاری بر حسب ثانیه به ابتدای هر خط خروجی اضافه می‌کند.

ترکیب “--numeric” با “--format” امکان سفارشی‌سازی خروجی را فراهم می‌کند. اجزای رشته قالب پیش‌فرض برای “--numeric” به ترتیب عبارتند از: “%t %b %r %{progress-amount-only}” که هر مورد بر اساس قوانین ذکر شده در بالا فعال یا غیرفعال می‌شود (بنابراین حالت پیش‌فرض بدون مشخص کردن گزینه‌های دیگر “%{progress-amount-only}” است).

-q, --quiet

بدون خروجی. هنگامی که گزینهٔ “--rate-limit” به‌تنهایی برای محدود کردن نرخ انتقال یک لوله به کار می‌رود، مفید است.

-8, --bits

استفاده از بیت به جای بایت برای شمارنده‌های بایت و نرخ انتقال. پسوند خروجی به جای “B” برابر با “b” خواهد بود.

-k, --si

نمایش و تفسیر پسوندها به عنوان مضارب ۱۰۰۰ به جای مقدار پیش‌فرض ۱۰۲۴. توجه داشته باشید که این گزینه تنها بر گزینه‌های پس از خود تأثیر می‌گذارد؛ بنابراین برای یکدستی، این گزینه را در ابتدا مشخص کنید.

-W, --wait

منتظر ماندن تا زمان انتقال نخستین بایت پیش از نمایش هرگونه اطلاعات پیشرفت یا محاسبهٔ زمان‌های تقریبی پایان (ETA). برای نمونه، هنگام هدایت (pipe کردن) داده‌ها به ابزارهایی مانند gpg(1) یا “mysql -p” از این گزینه استفاده کنید تا شمارش تنها پس از پاسخ به اعلان گذرواژه آغاز شود.

-D SEC, --delay-start SEC

منتظر ماندن تا سپری شدن SEC ثانیه پیش از نمایش هرگونه اطلاعات پیشرفت، به طوری که اگر انتقال سریع تمام شود، چیزی نمایش داده نشود. مقدار SEC می‌تواند عددی اعشاری مانند “0.5” باشد.

-s SIZE, --size SIZE

فرض کردن حجم کل داده‌های در حال انتقال به اندازهٔ SIZE بایت هنگام محاسبهٔ درصدها و زمان‌های تقریبی پایان (ETA). می‌توان یک پسوند “K”، “M”، “G” یا “T” را برای مشخص کردن کیبی‌بایت (*1024)، مبی‌بایت، گیبی‌بایت و تبی‌بایت اضافه کرد. اگر “--si” پیش از این گزینه بیاید، پسوندها در عوض نشان‌دهندهٔ کیلوبایت (*1000)، مگابایت و غیره خواهند بود.

اگر SIZE با “@” آغاز شود، اندازهٔ فایلی که نامش پس از @ می‌آید استفاده خواهد شد؛ چنانچه آن یک دایرکتوری باشد، اندازهٔ همهٔ فایل‌های زیرمجموعهٔ آن استفاده می‌شود، مانند “du --apparent-size -b”.

-g, --gauge

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

-l, --line-mode

به جای شمارش بایت‌ها، شمارش خط‌ها (نویسه‌های خط جدید). نوار پیشرفت تنها زمانی حرکت می‌کند که یک خط جدید پیدا شود، و مقدار داده‌شده به “--size” به عنوان تعداد خطوط تفسیر خواهد شد.

اگر این گزینه بدون “--size” استفاده شود، “اندازهٔ کل” (در این حالت، تعداد کل خطوط) با خواندن کامل همهٔ فایل‌های ورودی برای یک بار پیش از شروع انتقال محاسبه می‌شود. اگر هر یک از ورودی‌ها لوله‌ها (pipes) یا فایل‌های غیرعادی (non-regular) باشند، یا قابل خواندن نباشند، اندازهٔ کل محاسبه نخواهد شد.

-0, --null

محاسبهٔ خطوط به عنوان خاتمه‌یافته با یک بایت تهی (null) به جای خط جدید. این گزینه مستلزم “--line-mode” است.

-i SEC, --interval SEC

صبر کردن به مدت SEC ثانیه بین هر به‌روزرسانی. حالت پیش‌فرض به‌روزرسانی در هر ثانیه است. مقدار SEC می‌تواند عددی اعشاری مانند “0.1” باشد.

-m SEC, --average-rate-window SEC

محاسبهٔ میانگین نرخ فعلی در یک بازهٔ زمانی SEC ثانیه‌ای برای محاسبات میانگین نرخ و ETA. پیش‌فرض ۳۰ ثانیه است. مقدار باید یک عدد صحیح باشد.

-w WIDTH, --width WIDTH

فرض کردن عرض ترمینال به اندازهٔ WIDTH ستون، به جای تشخیص خودکار عرض (یا فرض ۸۰ در صورت شکست در تشخیص). اگر از این گزینه استفاده شود، در صورتی که عرض ترمینال حین اجرای انتقال تغییر کند، عرض خروجی تنظیم نخواهد شد.

-H HEIGHT, --height HEIGHT

فرض کردن ارتفاع ترمینال به اندازهٔ HEIGHT سطر، به جای تشخیص خودکار ارتفاع (یا فرض ۲۵ در صورت شکست در تشخیص). اگر از این گزینه استفاده شود، در صورتی که ارتفاع ترمینال حین اجرای انتقال تغییر کند، ارتفاع خروجی تنظیم نخواهد شد.

-N NAME, --name NAME

قرار دادن NAME به عنوان پیشوند در اطلاعات خروجی. اغلب همراه با “--cursor” برای شناسایی هر نوار پیشرفت در یک خط لوله حاوی بیش از یک pv استفاده می‌شود.

-u STYLE, --bar-style STYLE

تغییر سبک پیش‌فرض نوار پیشرفتِ ارائه‌شده توسط “--progress”، یا توسط توالی‌های “--format” مانند “%{progress}” یا “%{progress-bar-only}” به STYLE. مقدار STYLE می‌تواند یکی از مقادیر plain (پیش‌فرض)، block، granular یا shaded باشد. این سبک‌ها در بخش FORMATTING در ادامه شرح داده شده‌اند.

-x SPEC, --extra-display SPEC

علاوه بر نمایش پیشرفت در ترمینال، آن را در SPEC نیز می‌نویسد. مقدار SPEC باید با فهرستی از مقصدهای جداشده با کاما آغاز شود و می‌تواند به صورت اختیاری با یک دونقطه و یک رشتهٔ قالب‌بندی دنبال گردد. مقصدها می‌توانند windowtitle یا window برای عنوان پنجرهٔ xterm، و processtitle، proctitle، process یا proc برای عنوان فرایند نمایش‌یافته توسط ps(1) باشند. اگر رشتهٔ قالب‌بندی ارائه نشود، همان قالب ترمینال استفاده خواهد شد. برای نمونه، “-x 'window,process:%t %b %r'” زمان سپری‌شده، بایت‌های منتقل‌شده و نرخ را هم در عنوان پنجره و هم در عنوان فرایند نمایش می‌دهد.

-v, --stats

در پایان انتقال، یک خط اضافی شامل کمینه، میانگین، بیشینه و انحراف معیار نرخ انتقال نمایش می‌دهد. مقادیر همیشه بر حسب بایت بر ثانیه هستند (یا با “--bits” بر حسب بیت).

-f, --force

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

-c, --cursor

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

برای نمونه:

pv --cursor --name input file.gz | gzip -d | pv --cursor --name output > file

همان‌طور که در مثال مشخص است، این گزینه اغلب همراه با “--name” استفاده می‌شود.

-o FILE, --output FILE

نوشتن داده‌ها در FILE به‌جای خروجی استاندارد. اگر فایل از قبل وجود داشته باشد، کوتاه‌سازی (truncate) خواهد شد.

-L RATE, --rate-limit RATE

محدود کردن انتقال به حداکثر RATE بایت بر ثانیه. همان پسوندهای مورد استفاده در “--size” قابل استفاده هستند. مقدارهای اعشاری مجاز هستند. تعیین مقدار 0 محدودیت نرخ را غیرفعال می‌کند، که در صورت استفاده با “--remote” سودمند است.

-B BYTES, --buffer-size BYTES

استفاده از اندازهٔ بافر انتقال به مقدار BYTES بایت. همان پسوندهای مورد استفاده در “--size” قابل استفاده هستند. اندازهٔ پیش‌فرض بافر، اندازهٔ بلوک سیستم‌فایل فایل ورودی ضرب در ۳۲ (حداکثر 512KiB) است، یا در صورتی که اندازهٔ بلوک قابل تشخیص نباشد، 400KiB خواهد بود. این گزینه می‌تواند در بسترهایی مانند macOS با خط‌لوله‌هایی که با اندازه‌های بافر مشخصی همچون ۱۰۲۴ عملکرد بهتری دارند، مفید باشد. به‌طور ضمنی “--no-splice” را فعال می‌کند.

-C, --no-splice

جلوگیری از استفاده از splice(2) و copy_file_range(2)، که معمولاً در سیستم‌های پشتیبانی‌کننده برای بهبود کارایی از طریق حذف نیاز به بافر انتقال استفاده می‌شوند.

در حالت پیش‌فرض که splice(2) یا copy_file_range(2) به کار می‌روند، نبود بافر انتقال مانع از کارکرد “--buffer-percent” و “--last-written” شده و “--buffer-size” را بلااستفاده می‌سازد، بنابراین استفاده از هر یک از این گزینه‌ها به‌طور خودکار “--no-splice” را فعال می‌کند.

فایل‌های کم‌پشت (sparse) را نمی‌توان با splice(2) یا copy_file_range(2) نوشت، بنابراین استفاده از “--sparse” به‌طور خودکار “--no-splice” را فعال می‌کند.

فعال‌کردن “--no-splice” منجر به افت اندک کارایی انتقال می‌شود. این گزینه در سیستم‌هایی که splice(2) و copy_file_range(2) در دسترس نیستند، هیچ اثری ندارد.

-J BYTES, --pipe-buffer-size BYTES

تلاش برای تنظیم اندازهٔ بافر لولهٔ خروجی، و بافر لولهٔ ورودی واسط در صورت نیاز، به میزان BYTES بایت. اگر اندازهٔ درخواستی قابل دستیابی نباشد، بدون نمایش خطا هیچ کاری انجام نخواهد شد. اگر این گزینه مشخص نشود، و هر دوی خروجی و ورودی اول از نوع لوله (pipe) باشند، در صورتی که بافر خروجی کوچک‌تر باشد، اندازهٔ آن به‌طور خودکار افزایش می‌یابد تا با بافر لولهٔ ورودی مطابقت پیدا کند.

-E, --skip-errors

نادیده‌گرفتن خطاهای خواندن با تلاش برای پرش از بخش‌های معیوب. بخش‌های متناظر در خروجی، بایت‌های تهی (null) خواهند بود. در ابتدا تنها چند بایت نادیده گرفته می‌شود، اما در صورت وقوع خطاهای متعدد پشت‌سرهم، پرش‌ها به قطعه‌های ۵۱۲ تایی ارتقا می‌یابند. این ویژگی با هدف تشابه با عملکرد “dd conv=sync,noerror” طراحی شده است.

مشخص‌کردن دو بارِ “--skip-errors” باعث می‌شود به‌جای گزارش تک‌تک محدوده‌های بایتیِ رد شده، خطای خواندن تنها یک بار به ازای هر فایل گزارش شود.

-Z BYTES, --error-skip-block BYTES

هنگام نادیده‌گرفتن خطاهای خواندن با “--skip-errors”، به‌جای تلاش برای پرش انطباقی از طریق خواندن مقادیر اندک و پرش از بخش‌های به‌مرور بزرگ‌تر تا زمان موفقیت در خواندن، به‌محض رخ دادن خطا، به بلوک فایل بعدی با اندازهٔ BYTES بایت پرش کنید. ممکن است همچنان پرش‌های کوتاه‌تری وجود داشته باشد که در آن‌ها بلوکِ در حال رد شدن با پایان بافر انتقال هم‌زمان شود. همان پسوندهای مورد استفاده در “--size” قابل استفاده هستند.

این گزینه تنها همراه با “--skip-errors” قابل استفاده است و برای زمان خواندن از یک دستگاه بلوکی (block device) در نظر گرفته شده است، مانند “--skip-errors --error-skip-block 4K” تا پرش‌ها در بلوک‌های ۴ کیبی‌بایتی صورت پذیرد. این کار سرعت خواندن از رسانه‌های معیوب را افزایش می‌دهد، به بهای از دست دادن احتمالی داده‌های بیشتر.

-S, --stop-at-size

اگر اندازه‌ای با “--size” مشخص شده باشد، انتقال داده به‌محض نوشته شدن آن تعداد بایت متوقف می‌شود، به‌جای آنکه تا پایان ورودی ادامه یابد.

-Y, --sync

پس از هر عملیات نوشتن، کَش‌های بافر را با sync(2)، یا در صورت امکان با fdatasync(2)، روی دیسک همگام‌سازی می‌کند. این گزینه در صورتی که خروجی یک لوله باشد، هیچ اثری ندارد. استفاده از “--sync” ممکن است دقت نوار پیشرفت را هنگام نوشتن روی یک دیسک کُند بهبود بخشد.

-K, --direct-io

تنظیم پرچم O_DIRECT روی تمام ورودی‌ها و خروجی‌ها، در صورت پشتیبانی. این کار اثر کَش‌ها را به بهای کاهش کارایی، به حداقل می‌رساند. به‌دلیل الزامات هم‌ترازی حافظه (memory alignment)، ممکن است باعث شکست در خواندن یا نوشتن همراه با خطای “Invalid argument” شود، به‌ویژه هنگام خواندن و نوشتن فایل‌ها در چندین سیستم‌فایل مختلف در یک فراخوانی واحد pv. از این گزینه با احتیاط استفاده کنید.

-O, --sparse

هنگام نوشتن بایت‌های تهی، اقدام به پرش (seek) می‌کند تا یک فایل خروجی کم‌پشت (sparse) ایجاد شود. به‌طور ضمنی “--no-splice” را فعال می‌کند. در سیستم‌فایل‌های فاقد پشتیبانی از فایل‌های کم‌پشت، یا هنگامی که خروجی قابلیت پرش (seekable) نداشته باشد، این گزینه اثری جز روشن کردن “--no-splice” نخواهد داشت.

-X, --discard

به‌جای انتقال داده‌های ورودی به خروجی استاندارد، آن‌ها را دور می‌ریزد. این عمل معادل تغییر مسیر خروجی استاندارد به /dev/null است، با این تفاوت که write(2) هرگز فراخوانی نمی‌شود.

-U FILE, --store-and-forward FILE

به‌جای عبور دادن بلادرنگ داده‌ها، این کار را در دو مرحله انجام می‌دهد - ابتدا تمام ورودی را خوانده و در FILE می‌نویسد، و پس از اتمام کامل ورودی، کل FILE را خوانده و آن را در خروجی می‌نویسد. FILE پس از پایان کار باقی می‌ماند، مگر اینکه “-” مشخص شده باشد، که در این حالت pv یک فایل موقت برای این منظور ایجاد کرده و پس از اتمام، به‌طور خودکار آن را حذف می‌کند.

یک کاربرد رایج برای این قابلیت زمانی است که بخشی از یک خط‌لوله داده‌ها را به‌سرعت اما با اندازهٔ نامشخص تولید می‌کند، و بخش بعدی آن را به‌کندی پردازش می‌نماید. با دستور “quick | pv -U - | slow”، یک نوار پیشرفت با اندازهٔ نامشخص برای بخش quick نمایش داده می‌شود، و سپس نوار دومی با اندازهٔ مشخص و زمان تقریبی پایان (ETA) برای بخش slow نشان داده می‌شود.

-d, --watchfd PID[:FD]|=NAME|@LISTFILE...

به جای انتقال داده، توصیف‌گر فایل FD مربوط به فرایند PID را پایش کرده و پیشرفت آن را نمایش می‌دهد. سایر تغییردهنده‌های انتقال داده - و کنترل از راه دور - ممکن است با این گزینه قابل استفاده نباشند.

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

اگر یک NAME با پیشوند «=» مشخص شود، فرایندهایی با آن نام توسط pgrep(1) پیدا شده و همان‌طور که در بالا توضیح داده شد پایش می‌شوند.

اگر یک LISTFILE با پیشوند «@» مشخص شود، خطوط موجود در آن فایل به عنوان آرگومان‌های اضافی استفاده خواهند شد.

تمام آرگومان‌های غیرگزینه‌ای باقی‌مانده نیز به عنوان آرگومان‌های اضافی در نظر گرفته خواهند شد.

فرایند pv زمانی خارج می‌شود که تمام FDها یا به یک فایل دیگر تغییر یافته باشند، حالت خواندن/نوشتن آن‌ها تغییر کرده باشد یا بسته شده باشند، و تمام PIDها (بدون FD مشخص) خاتمه یافته باشند.

-R PID, --remote PID

کنترل از راه دور نمونهٔ دیگری از pv با شناسه فرایند PID، به‌گونه‌ای که رفتار کند گویی خط فرمان این نمونه به آن داده شده است. برای مثال، اگر “pv --rate-limit 123K” با شناسه فرایند 9876 در حال اجرا باشد، اجرای “pv --remote 9876 --rate-limit 321K” باعث می‌شود فرایند 9876 به‌جای 123KiB از محدودیت نرخ 321KiB استفاده کند. توجه داشته باشید که برخی از گزینه‌ها در حین اجرا قابل تغییر نیستند، مانند “--cursor”، “--line-mode”، “--force”، “--delay-start”، “--skip-errors” و “--stop-at-size”.

-Q PID, --query PID

نمایش پیشرفت انتقال نمونهٔ دیگری از pv با شناسه فرایند PID، متعلق به همان کاربر.

برخی از تغییردهنده‌های خروجی هنگام استعلام از فرایندی دیگر، تنها در صورتی قابل استفاده هستند که با مقادیر آن فرایند مطابقت داشته باشند - مانند “--line-mode”، “--null” و “--average-rate-window”. تغییردهنده‌های انتقال داده هیچ اثری نخواهند داشت.

-M SIDE, --monitor SIDE

دستور مشخص‌شده توسط آرگومان‌های باقی‌مانده را اجرا می‌کند و بسته به اینکه SIDE برابر با “in”، “out” یا “both” باشد، ورودی استاندارد، خروجی استاندارد یا هر دو را پایش می‌کند. بعد از تمام گزینه‌های pv از “--” استفاده کنید تا گزینه‌های دستور مورد پایش جدا نگه داشته شوند.

با مقدار “both” برای SIDE، دو نوار پیشرفت نمایش داده خواهد شد. تمام سوییچ‌های نمایشی، تغییردهنده‌های خروجی و تغییردهنده‌های انتقال دادهٔ pv برای هر دو طرف اعمال خواهند شد.

برای مثال، “pv --cursor --monitor both -- gzip -9” معادل “pv --cursor | gzip -9 | pv --cursor” است، با این تفاوت که دومی نمی‌تواند نسبت ورودی به خروجی را نمایش دهد.

گزینه‌های “--format” و “--name” را می‌توان دو بار مشخص کرد که در این صورت، مورد اول برای سمت ورودی و مورد دوم برای سمت خروجی اعمال می‌شود. اگر هیچ گزینهٔ “--format” مشخص نشود، قالب پیش‌فرض بر پایهٔ سایر سوییچ‌های نمایشی به شکل معمول استفاده می‌شود، با این تفاوت که وقتی SIDE برابر با “both” باشد، نسبت نیز به سمت خروجی افزوده می‌گردد.

مقادیر “0”، “1” و “2” می‌توانند به عنوان مترادف برای “in”، “out” و “both” استفاده شوند.

این گزینه نمی‌تواند همراه با “--store-and-forward” استفاده شود.

سایر گزینه‌ها

-P FILE, --pidfile FILE

شناسه فرایند pv را در FILE ذخیره می‌کند. اگر فایل از قبل وجود داشته باشد جایگزین می‌شود و هنگام خروج pv حذف خواهد شد. تا زمانی که pv در حال اجرا است، FILE حاوی یک عدد منفرد - شناسه فرایند pv - و به دنبال آن یک خط جدید خواهد بود.

-h, --help

پیام راهنمای استفاده را در خروجی استاندارد چاپ کرده و با موفقیت خارج می‌شود.

-V, --version

اطلاعات نسخه را در خروجی استاندارد چاپ کرده و با موفقیت خارج می‌شود. رشته‌های قالب استفاده‌شده توسط “--format” و “--extra-display” می‌توانند شامل دنباله‌های زیر باشند:

%p, %{progress}

نوار پیشرفت (در صورتی که اندازه مشخص باشد، با درصد همراه می‌شود). معادل “--progress”. تا پر کردن فضای باقی‌مانده گسترش می‌یابد، مگر اینکه عددی برای تعیین پهنا به عنوان پیشوند به آن داده شود، مانند “%20p” یا “%20{progress}”.

%{progress-bar-only}

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

%{progress-amount-only}

درصد تکمیل (یا حداکثر نرخ با “--gauge” هنگامی که اندازه نامشخص است).

%{bar-plain}

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

%{bar-block}

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

%{bar-granular}

نوار پیشرفت با استفاده از بلوک‌های کامل یونیکد و بلوک‌های ۱/۸ برای پر کردن جزئی، که نمایش دقیق‌تری ارائه می‌دهد. مانند دیگر رشته‌های “%{bar}”، این مورد نوار را بدون کناره‌ها و بدون نمایش درصد پس از آن نشان می‌دهد، و تا پر کردن فضای باقی‌مانده گسترش می‌یابد مگر اینکه عددی به عنوان پیشوند به آن داده شود. اگر خروجی UTF-8 در دسترس نباشد، از قالب ساده استفاده می‌شود.

%{bar-shaded}

نوار پیشرفت با استفاده از بلوک‌های کامل یونیکد و نویسه‌های سایه‌دار؛ سایه‌های تیره و متوسط برای پر کردن جزئی و سایه روشن برای پس‌زمینه به کار می‌روند. مانند دیگر رشته‌های “%{bar}”، این مورد نوار را بدون کناره‌ها و بدون نمایش درصد پس از آن نشان می‌دهد، و تا پر کردن فضای باقی‌مانده گسترش می‌یابد مگر اینکه عددی به عنوان پیشوند به آن داده شود. اگر خروجی UTF-8 در دسترس نباشد، از قالب ساده استفاده می‌شود.

%t, %{timer}

زمان سپری‌شده. معادل “--timer”.

%e, %{eta}

زمان تخمینی باقی‌مانده (ETA). معادل “--eta”.

%I, %{fineta}

زمان تخمینی اتمام انتقال بر اساس ساعت محلی. معادل “--fineta”.

%r, %{rate}

نرخ فعلی انتقال داده. معادل “--rate”.

%a, %{average-rate}

نرخ میانگین انتقال داده. معادل “--average-rate”.

%b, %{bytes}, %{transferred}

بایت‌های انتقال‌یافته تا این لحظه (یا در صورت مشخص شدن “--line-mode”، سطرها). معادل “--bytes”. اگر “--bits” مشخص شده باشد، “%b” بیت‌های انتقال‌یافته تا این لحظه را نشان می‌دهد، نه بایت‌ها.

%{ratio}

نمایش نسبت بایت‌های انتقال‌یافته توسط طرف دیگر به بایت‌های انتقال‌یافته توسط این طرف، در حالت “--monitor both”.

%T, %{buffer-percent}

درصد بافر انتقالِ در حال استفاده. معادل “--buffer-percent”، اما استفاده از آن “--no-splice” را فعال نمی‌کند.

اگر انتقال از splice(2) استفاده کند، مقدار “{----}” را نمایش می‌دهد؛ اگر انتقال از splice(2) از طریق لوله ورودی میانی استفاده کند، “{-||-}” را نمایش می‌دهد؛ و اگر انتقال از copy_file_range(2) استفاده کند، “{--->}” را نمایش می‌دهد.

%nA, %n{last-written}

نمایش آخرین n بایت نوشته‌شده (برای مثال، “%16A” آخرین ۱۶ بایت را نشان می‌دهد). اگر انتقال از splice(2) یا copy_file_range(2) استفاده کند، فقط نقطه‌ها را نشان می‌دهد، زیرا این حالت‌های انتقال از بافر استفاده نمی‌کنند.

%nL, %n{previous-line}

نمایش اولین n بایت از آخرین سطر نوشته‌شده (برای مثال، “%40L” ۴۰ بایت اول را نشان می‌دهد). اگر هیچ n داده نشود، تا پر کردن فضای موجود گسترش می‌یابد. اگر انتقال از splice(2) یا copy_file_range(2) استفاده کند، فقط فاصله‌ها را نشان می‌دهد.

%N, %{name}

نمایش پیشوند نام داده‌شده توسط “--name”. با فاصله‌ها تا ۹ نویسه پر شده و به “:” ختم می‌شود.

%{sgr:colour,...}

در صورت پشتیبانی پایانه از رنگ، کدهای ECMA-48 SGR (Select Graphic Rendition) را ارسال می‌کند، که در آن colour,... فهرستی از هر یک از کلیدواژه‌های زیر با جداکننده کاما یا مقادیر عددی از console_codes(4) است. اگر پشتیبانی از رنگ وجود نداشته باشد، چیزی ارسال نمی‌شود.

کلیدواژه‌های پشتیبانی‌شده عبارتند از: reset یا none، black، red، green، brown یا yellow، blue، magenta، cyan، white، fg-black، fg-red، fg-green، fg-brown یا fg-yellow، fg-blue، fg-magenta، fg-cyan، fg-white، fg-default، bg-black، bg-red، bg-green، bg-brown یا bg-yellow، bg-blue، bg-magenta، bg-cyan، bg-white، bg-default، bold، dim، italic، underscore یا underline، blink، reverse، no-bold یا no-dim، no-italic، no-underscore یا no-underline، no-blink، no-reverse.

در مورد رنگ‌ها، پیشوند اختیاری "fg-" نشان‌دهنده رنگ متن (پیش‌زمینه) و پیشوند "bg-" نشان‌دهنده رنگ پس‌زمینه است.

برای مثال، “%{sgr:green,bold}TEXT%{sgr:reset}” عبارت TEXT را در پایانه‌های پشتیبانی‌شده به صورت سبز پررنگ نمایش می‌دهد.

%%

یک نویسه منفرد “%”.

هر محتوای دیگری بدون تغییر در نمایش پیشرفت نشان داده می‌شود.

معادل رشته قالب برای سوئیچ‌های نمایش پیش‌فرض عبارت است از “%b %t %r %p %e”. برخی از ترکیب‌های پیشنهادی برای گزینه‌های رایج:

pv -ptebar

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

pv -betlap

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

pv -btrpg

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

pv -t

تنها نمایش زمان سپری‌شده - مفید به‌عنوان یک زمان‌سنج ساده، مانند “sleep 10m | pv -t”.

pv -pterb

رفتار پیش‌فرض: نوار پیشرفت، زمان سپری‌شده، زمان تخمینی تکمیل، نرخ کنونی و شمارنده بایت.

در macOS، تعیین “--buffer-size 1024” در یک خط‌لوله می‌تواند مفید باشد، چرا که ممکن است کارایی را بهبود بخشد.

برای مشاهده سرعت انتقال یک فایل با استفاده از nc(1):

pv file | nc -w 1 somewhere.com 3000

مثالی مشابه برای انتقال یک فایل از فرایندی دیگر و ارسال اندازه مورد انتظار به pv:

cat file | pv --size 12345 | nc -w 1 somewhere.com 3000

برای مشاهده پیشرفت ایجاد یک بایگانی tar.gz:

tar cf - directory/ \
| pv --size $(du -sb directory/ | awk '{print $1}') \
| gzip -9 \
> out.tar.gz

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

tar cf - directory/ \
| pv --size @directory/ \
| gzip -9 \
> out.tar.gz

تهیه یک ایمیج از دیسک با نادیده گرفتن خطاها:

pv -EE /dev/your/disk/device > disk-image.img

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

pv disk-image.img > /dev/your/disk/device

صفر کردن یک دیسک:

pv < /dev/zero > /dev/your/disk/device

توجه داشته باشید که اگر اندازه ورودی قابل محاسبه نباشد و خروجی یک دستگاه بلوکی باشد، اندازه دستگاه بلوکی استفاده خواهد شد و pv به‌طور خودکار در آن اندازه متوقف می‌شود، گویی گزینه “--stop-at-size” داده شده است.

(تنها در Linux و macOS): نظارت بر توصیف‌گر فایل ۳ باز شده توسط فرایند دیگری با شناسه 1234:

pv --watchfd 1234:3

(تنها در Linux و macOS): نظارت بر تمام توصیف‌گرهای فایل استفاده‌شده توسط فرایند 1234:

pv --watchfd 1234

محدود کردن نرخ انتقال میان دو فرایند در یک خط‌لوله، بدون هیچ نمایشی:

producer | pv --quiet --rate-limit 1M | consumer

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

pv --no-splice --format '%a %p : %L' big.log | processing-script

نمایش پیشرفت به‌صورت خطوطی از داده‌های JSON:

pv --numeric --format '{"elapsed":%t,"bytes":%b,"rate":%r,"percentage":%{progress-amount-only}}' big.log | processing-script

هر وضعیت خروج دیگری، یک ماسک بیتی (bitmask) از مقادیر زیر است:

 2

یک یا چند فایل قابل دسترسی، اجرای stat(2) یا باز شدن نبودند.

 4

یک فایل ورودی با فایل خروجی یکسان بود.

 8

خطای داخلی در بستن یک فایل یا رفتن به فایل بعدی.

 16

هنگام انتقال داده‌ها از یک یا چند فایل ورودی خطایی رخ داد.

 32

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

 64

تخصیص حافظه با شکست مواجه شد.

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