GETOPT(1) دستورات کاربر GETOPT(1)

getopt - تجزیه و پردازش گزینه‌های خط فرمان در اسکریپت‌ها

getopt optstring parameters

getopt [options] [--] optstring parameters

getopt [options] -o|--options optstring [options] [--] parameters

دستور getopt برای تفکیک (تجزیه) گزینه‌ها در خطوط فرمان به‌منظور تجزیه آسان توسط رویه‌های پوسته و بررسی معتبر بودن گزینه‌ها استفاده می‌شود. این دستور برای انجام این کار از روتین‌های getopt(3) در گنو (GNU) استفاده می‌کند.

پارامترهایی که getopt با آن‌ها فراخوانی می‌شود را می‌توان به دو بخش تقسیم کرد: گزینه‌هایی که نحوه تجزیه توسط getopt را تغییر می‌دهند (options و optstring در بخش خلاصه دستور)، و پارامترهایی که قرار است تجزیه شوند (parameters در بخش خلاصه دستور). بخش دوم از اولین پارامتر غیرگزینه‌ای که آرگومان یک گزینه نیست، یا پس از اولین رخداد '--' شروع می‌شود. اگر هیچ گزینه '-o' یا '--options' در بخش اول یافت نشود، اولین پارامتر بخش دوم به‌عنوان رشته گزینه‌های کوتاه استفاده می‌شود.

اگر متغیر محیطی GETOPT_COMPATIBLE تنظیم شده باشد، یا اگر اولین parameter یک گزینه نباشد (با '-' شروع نشود، قالب اول در بخش خلاصه دستور)، getopt خروجی سازگار با سایر نسخه‌های getopt(1) تولید خواهد کرد. با این حال همچنان جابه‌جایی پارامترها را انجام داده و آرگومان‌های اختیاری را تشخیص می‌دهد (برای اطلاعات بیشتر به بخش سازگاری مراجعه کنید).

پیاده‌سازی‌های سنتی getopt(1) قادر به مدیریت فاصله‌ها (whitespace) و سایر نویسه‌های خاص (مخصوص پوسته) در آرگومان‌ها و پارامترهای غیرگزینه‌ای نیستند. برای حل این مشکل، این پیاده‌سازی می‌تواند خروجی نقل‌قول‌شده (quoted) تولید کند که باید مجدداً توسط پوسته تفسیر شود (معمولاً با استفاده از دستور eval). این کار باعث حفظ آن نویسه‌ها می‌شود، اما باید getopt را به روشی فراخوانی کنید که دیگر با سایر نسخه‌ها سازگار نیست (قالب دوم یا سوم در بخش خلاصه دستور). برای تعیین اینکه آیا این نسخه بهبودیافته از getopt(1) نصب شده است یا خیر، می‌توان از یک گزینه آزمایشی ویژه (-T) استفاده کرد.

-a, --alternative

اجازه می‌دهد گزینه‌های طولانی با یک '-' تکی شروع شوند.

-l, --longoptions longopts

گزینه‌های طولانی (چندنویسه‌ای) که باید شناسایی شوند. می‌توان بیش از یک نام گزینه را به‌طور هم‌زمان با جدا کردن نام‌ها توسط ویرگول یا نویسه‌های فاصله (فاصله، تب، یا خط جدید) مشخص کرد. این گزینه می‌تواند بیش از یک بار داده شود و مقادیر longopts انباشته می‌شوند. هر نام گزینه طولانی در longopts می‌تواند با یک دونقطه (:) برای نشان دادن نیاز به آرگومان اجباری، و با دو دونقطه (::) برای نشان دادن داشتن آرگومان اختیاری دنبال شود.

-n, --name progname

نامی که توسط روتین‌های getopt(3) هنگام گزارش خطاها استفاده خواهد شد. توجه داشته باشید که خطاهای خود getopt(1) همچنان به‌عنوان خطاهای ناشی از getopt گزارش می‌شوند.

-o, --options shortopts

گزینه‌های کوتاه (تک‌نویسه‌ای) که باید شناسایی شوند. اگر این گزینه یافت نشود، اولین پارامتر getopt که با '-' شروع نمی‌شود (و آرگومان گزینه نیست) به‌عنوان رشته گزینه‌های کوتاه استفاده می‌شود. هر نویسه گزینه کوتاه در shortopts می‌تواند با یک دونقطه (:) برای نشان دادن نیاز به آرگومان اجباری، و با دو دونقطه (::) برای نشان دادن داشتن آرگومان اختیاری دنبال شود. اولین نویسه shortopts می‌تواند '+' یا '-' باشد تا بر نحوه تجزیه گزینه‌ها و تولید خروجی تأثیر بگذارد (برای جزئیات به بخش حالت‌های پویش مراجعه کنید).

-q, --quiet

غیرفعال کردن گزارش خطا توسط getopt(3).

-Q, --quiet-output

عدم تولید خروجی عادی. خطاها همچنان توسط getopt(3) گزارش می‌شوند، مگر اینکه از -q نیز استفاده کنید.

-s, --shell shell

تنظیم قواعد نقل‌قول مطابق با shell. اگر گزینه -s داده نشود، از قواعد BASH استفاده می‌شود. آرگومان‌های معتبر در حال حاضر عبارتند از: 'sh'، 'bash'، 'csh' و 'tcsh'.

-T, --test

بررسی اینکه آیا getopt(1) شما این نسخه بهبودیافته است یا یک نسخه قدیمی. این گزینه هیچ خروجی تولید نمی‌کند و وضعیت خطا (error status) را روی 4 تنظیم می‌کند. سایر پیاده‌سازی‌های getopt(1)، و این نسخه در صورتی که متغیر محیطی GETOPT_COMPATIBLE تنظیم شده باشد، '--' و وضعیت خطای 0 را برمی‌گردانند.

-u, --unquoted

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

-U, --unknown

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

-h, --help

نمایش متن راهنما و خروج.

-V, --version

نمایش نسخه و خروج.

این بخش قالب بخش دوم پارامترهای getopt (parameters در بخش خلاصه دستور) را مشخص می‌کند. بخش بعدی (خروجی) خروجی تولیدشده را شرح می‌دهد. این پارامترها معمولاً پارامترهایی بودند که یک تابع پوسته با آن‌ها فراخوانی شده بود. باید دقت شود که هر پارامتری که تابع پوسته با آن فراخوانی شده دقیقاً با یک پارامتر در فهرست پارامترهای getopt مطابقت داشته باشد (به بخش مثال‌ها مراجعه کنید). تمام فرایند تجزیه توسط روتین‌های getopt(3) در گنو انجام می‌شود.

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

یک گزینه کوتاه ساده عبارت است از یک '-' به همراه یک نویسه گزینه کوتاه، به جز نویسه‌های ':'، ';' و '?'، زیرا این نویسه‌ها توسط getopt(3) رزرو شده‌اند. اگر گزینه نیاز به آرگومان اجباری داشته باشد، می‌توان آن را مستقیماً پس از نویسه گزینه یا به‌عنوان پارامتر بعدی نوشت (یعنی با فاصله در خط فرمان جدا شود). اگر گزینه آرگومان اختیاری داشته باشد، در صورت وجود باید مستقیماً پس از نویسه گزینه نوشته شود.

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

یک گزینه طولانی معمولاً با '--' و به دنبال آن نام گزینه طولانی شروع می‌شود. اگر گزینه آرگومان اجباری داشته باشد، می‌توان آن را مستقیماً پس از نام گزینه طولانی و با جداکننده '=' نوشت، یا به‌عنوان آرگومان بعدی قرار داد (یعنی با فاصله در خط فرمان جدا شود). اگر گزینه آرگومان اختیاری داشته باشد، در صورت وجود باید مستقیماً پس از نام گزینه طولانی و با جداکننده '=' نوشته شود (اگر '=' را اضافه کنید اما چیزی پشت آن نباشد، چنان تفسیر می‌شود که گویی هیچ آرگومانی وجود نداشته است؛ این یک اشکال جزئی است، به بخش اشکالات مراجعه کنید). گزینه‌های طولانی را می‌توان مخفف کرد، به شرطی که مخفف آن‌ها مبهم نباشد.

هر پارامتری که با '-' شروع نشود و آرگومان اجباری یک گزینه قبلی نباشد، یک پارامتر غیرگزینه‌ای است. هر پارامتری پس از پارامتر '--' همیشه به‌عنوان یک پارامتر غیرگزینه‌ای تفسیر می‌شود. اگر متغیر محیطی POSIXLY_CORRECT تنظیم شده باشد، یا اگر رشته گزینه کوتاه با '+' شروع شده باشد، به‌محض یافتن اولین پارامتر غیرگزینه‌ای، تمام پارامترهای باقی‌مانده به‌عنوان پارامترهای غیرگزینه‌ای تفسیر می‌شوند.

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

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

برای یک گزینه کوتاه، یک '-' تکی و نویسه گزینه به‌عنوان یک پارامتر تولید می‌شوند. اگر گزینه دارای آرگومان باشد، پارامتر بعدی همان آرگومان خواهد بود. اگر گزینه یک آرگومان اختیاری بپذیرد اما هیچ آرگومانی یافت نشود، در حالت نقل‌قول پارامتر بعدی تولید می‌شود اما خالی خواهد بود، ولی در حالت بدون نقل‌قول (سازگار) پارامتر دومی تولید نمی‌شود. توجه داشته باشید که بسیاری از پیاده‌سازی‌های دیگر getopt(1) از آرگومان‌های اختیاری پشتیبانی نمی‌کنند.

اگر چندین گزینه کوتاه پس از یک '-' تکی مشخص شده باشند، هر یک در خروجی به‌عنوان یک پارامتر مجزا وجود خواهد داشت.

برای یک گزینه طولانی، '--' و نام کامل گزینه به‌عنوان یک پارامتر تولید می‌شوند. این کار صرف‌نظر از اینکه گزینه در ورودی به‌صورت مخفف یا با یک '-' تکی مشخص شده باشد انجام می‌شود. آرگومان‌ها مشابه گزینه‌های کوتاه مدیریت می‌شوند.

به‌طور معمول، هیچ خروجی پارامتر غیرگزینه‌ای تولید نمی‌شود تا زمانی که تمام گزینه‌ها و آرگومان‌های آن‌ها تولید شده باشند. سپس '--' به‌عنوان یک پارامتر واحد تولید می‌شود و پس از آن پارامترهای غیرگزینه‌ای به ترتیبی که یافت شده‌اند، هر کدام به‌عنوان یک پارامتر مجزا قرار می‌گیرند. تنها در صورتی که اولین نویسه رشته گزینه‌های کوتاه '-' باشد، خروجی پارامتر غیرگزینه‌ای در همان جایی که در ورودی یافت شده است تولید می‌شود (این مورد در صورت استفاده از قالب اول در بخش خلاصه دستور پشتیبانی نمی‌شود؛ در آن حالت تمام رخدادهای پیشین '-' و '+' نادیده گرفته می‌شوند).

در حالت سازگاری، فاصله‌ها یا نویسه‌های «خاص» در آرگومان‌ها یا پارامترهای غیرگزینه‌ای به‌درستی مدیریت نمی‌شوند. هنگامی که خروجی به اسکریپت پوسته داده می‌شود، اسکریپت نمی‌داند چگونه باید خروجی را به پارامترهای جداگانه تقسیم کند. برای دور زدن این مشکل، این پیاده‌سازی قابلیت نقل‌قول‌گذاری (quoting) را ارائه می‌دهد. ایده این است که خروجی همراه با علامت نقل‌قول در اطراف هر پارامتر تولید می‌شود. هنگامی که این خروجی دوباره به پوسته داده می‌شود (معمولاً توسط دستور eval در پوسته)، به‌درستی به پارامترهای جداگانه تقسیم می‌شود.

اگر متغیر محیطی GETOPT_COMPATIBLE تنظیم شده باشد، اگر از قالب اول در بخش خلاصه دستور استفاده شود، یا اگر گزینه '-u' یافت شود، نقل‌قول‌گذاری فعال نمی‌شود.

پوسته‌های مختلف از قواعد نقل‌قول متفاوتی استفاده می‌کنند. می‌توانید از گزینه '-s' برای انتخاب پوسته‌ای که استفاده می‌کنید استفاده کنید. در حال حاضر پوسته‌های زیر پشتیبانی می‌شوند: 'sh'، 'bash'، 'csh' و 'tcsh'. در واقع، تنها دو «گونه» متمایز می‌شوند: قواعد نقل‌قول مشابه sh و قواعد نقل‌قول مشابه csh. به احتمال زیاد اگر از زبان اسکریپت‌نویسی پوسته دیگری استفاده کنید، همچنان می‌توان از یکی از این دو گونه استفاده کرد.

اولین نویسه رشته گزینه‌های کوتاه ممکن است یک '-' یا یک '+' باشد تا یک حالت پویش ویژه را مشخص کند. اگر از اولین قالب فراخوانی در بخش خلاصه دستور استفاده شود، این نویسه‌ها نادیده گرفته می‌شوند؛ با این حال، متغیر محیطی POSIXLY_CORRECT همچنان بررسی می‌شود.

اگر نویسه اول '+' باشد، یا اگر متغیر محیطی POSIXLY_CORRECT تنظیم شده باشد، تجزیه به‌محض یافتن اولین پارامتر غیرگزینه‌ای (یعنی پارامتری که با '-' شروع نمی‌شود) که آرگومان یک گزینه نیست، متوقف می‌شود. تمام پارامترهای باقی‌مانده به‌عنوان پارامترهای غیرگزینه‌ای تفسیر می‌شوند.

اگر نویسه اول '-' باشد، پارامترهای غیرگزینه‌ای در همان جایی که یافت می‌شوند خروجی داده می‌شوند؛ در حالت عادی، همه آن‌ها در انتهای خروجی پس از تولید یک پارامتر '--' جمع‌آوری می‌شوند. توجه داشته باشید که این پارامتر '--' همچنان تولید می‌شود، اما در این حالت همیشه آخرین پارامتر خواهد بود.

این نسخه از getopt(1) به‌گونه‌ای نوشته شده است که تا حد ممکن با سایر نسخه‌ها سازگار باشد. معمولاً می‌توانید بدون هیچ‌گونه تغییری و با بهره‌مندی از برخی مزایا، این نسخه را جایگزین آن‌ها کنید.

اگر اولین نویسه از اولین پارامتر getopt یک '-' نباشد، getopt وارد حالت سازگاری می‌شود. این دستور اولین پارامتر خود را به‌عنوان رشته گزینه‌های کوتاه تفسیر می‌کند و تمام آرگومان‌های دیگر تجزیه خواهند شد. این دستور همچنان جابه‌جایی پارامترها را انجام می‌دهد (یعنی تمام پارامترهای غیرگزینه‌ای در انتها خروجی داده می‌شوند)، مگر اینکه متغیر محیطی POSIXLY_CORRECT تنظیم شده باشد، که در این صورت getopt به‌طور خودکار یک '+' را به ابتدای گزینه‌های کوتاه اضافه می‌کند.

متغیر محیطی GETOPT_COMPATIBLE دستور getopt را مجبور می‌کند به حالت سازگاری برود. تنظیم هم‌زمان این متغیر محیطی و POSIXLY_CORRECT سازگاری ۱۰۰٪ را برای برنامه‌های «دشوار» ارائه می‌دهد. اگرچه معمولاً به هیچ‌یک نیازی نیست.

در حالت سازگاری، نویسه‌های ابتدایی '-' و '+' در رشته گزینه‌های کوتاه نادیده گرفته می‌شوند.

دستور getopt کد خطای 0 را برای تجزیه موفقیت‌آمیز، 1 را در صورتی که getopt(3) خطا برگرداند، 2 را اگر پارامترهای خود را متوجه نشود، 3 را در صورت وقوع یک خطای داخلی مانند اتمام حافظه (out-of-memory)، و 4 را در صورتی که با -T فراخوانی شود برمی‌گرداند.

اسکریپت‌های نمونه برای (ba)sh و (t)csh همراه با بسته توزیع getopt(1) ارائه شده‌اند و در دایرکتوری /usr/share/doc/util-linux نصب می‌شوند.

POSIXLY_CORRECT

این متغیر محیطی توسط روتین‌های getopt(3) بررسی می‌شود. اگر تنظیم شده باشد، تجزیه به‌محض یافتن پارامتری که گزینه یا آرگومان گزینه نباشد متوقف می‌شود. تمام پارامترهای باقی‌مانده نیز صرف‌نظر از اینکه با '-' شروع شوند یا خیر، به‌عنوان پارامترهای غیرگزینه‌ای تفسیر می‌شوند.

GETOPT_COMPATIBLE

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

روتین getopt(3) می‌تواند گزینه‌های طولانی با آرگومان‌های اختیاری را که یک آرگومان اختیاری خالی به آن‌ها داده شده تجزیه کند (اما نمی‌تواند این کار را برای گزینه‌های کوتاه انجام دهد). این getopt(1) با آرگومان‌های اختیاری خالی طوری رفتار می‌کند که گویی وجود نداشته‌اند.

نحو دستور در صورتی که هیچ متغیر گزینه کوتاهی نخواهید، چندان شهودی نیست (باید آن‌ها را صراحتاً روی رشته خالی تنظیم کنید).

Frodo Looijaard <frodo@frodo.looijaard.name>

bash(1), tcsh(1), getopt(3)

برای گزارش اشکالات، از سامانه پیگیری مشکلات https://github.com/util-linux/util-linux/issues.

دستور getopt بخشی از بسته util-linux است که می‌توان آن را از بایگانی هسته لینوکس https://www.kernel.org/pub/linux/utils/util-linux.

2026-09-02 util-linux 2.42.3