.TH "GPG-CONNECT-AGENT" "1" "مه ۲۰۲۵" "gnupg" "دستورهای کاربری"
.SH "نام (NAME)"
gpg-connect-agent \- برقراری ارتباط و ارسال فرمان به دیمن در حال اجرای gpg-agent
.SH "خلاصه دستور (SYNOPSIS)"
\fBgpg-connect-agent\fP [ \fIگزینهها\fP ] [ \fIدستورات\fP... ]
.SH "توضیحات (DESCRIPTION)"
دستور \fBgpg-connect-agent\fR ابزاری است برای برقراری ارتباط مستقیم با پردازش دیمن gpg-agent و ارسال دستورات سطح پروتکل Assuan.
این ابزار جهت بررسی و آزمایش دستوراتی که
.B gpg\-agent
از طریق واسط Assuan ارائه می‌دهد، بسیار کاربردی است. همچنین می‌تواند برای اسکریپت‌نویسی برنامه‌های ساده نیز مفید باشد. ورودی از ورودی استاندارد (stdin) دریافت شده و خروجی در خروجی استاندارد (stdout) چاپ می‌شود.
.PP
عملکرد این ابزار بسیار شبیه به اجرای
.B gpg\-agent
در حالت سرور (server mode) است؛ اما در اینجا اتصال به یک نمونه در حال اجرا برقرار می‌شود.
.SH "گزینه‌ها (OPTIONS)"
گزینه‌های زیر می‌توانند استفاده شوند:

.TP
.B  \-\-dirmngr
به‌جای gpg-agent به یک مدیر دایرکتوری در حال اجرا (کلاینت سرور کلید یا keyserver) متصل می‌شود. اگر dirmngr در حال اجرا نباشد، آن را راه‌اندازی می‌کند.

.TP
.B  \-\-keyboxd
به‌جای gpg-agent به یک دیمن keybox در حال اجرا متصل می‌شود. اگر keyboxd در حال اجرا نباشد، آن را راه‌اندازی می‌کند.

.TP
.B  \-S
.TQ
.B  \-\-raw\-socket \fIنام\fP
به سوکت
.I نام
با این فرض که یک سرور مبتنی بر پروتکل Assuan است متصل می‌شود. هیچ‌گونه مقداردهی اولیه یا بررسی محیطی ویژه انجام نمی‌دهد. از این گزینه می‌توان برای اتصال مستقیم به هر سرور سوکت به سبک Assuan استفاده کرد.

.TP
.B  \-E
.TQ
.B  \-\-exec
باقی‌مانده خط فرمان را به عنوان یک برنامه و آرگومان‌های آن در نظر گرفته و آن را به عنوان یک سرور Assuan اجرا می‌کند. نحوه اجرای
.B gpgsm
به عنوان نمونه به این شکل خواهد بود:
.RS 2
.nf
gpg\-connect\-agent \-\-exec gpgsm \-\-server
.fi
.RE
توجه داشته باشید که در این حالت نمی‌توانید از گزینه‌های دیگر در خط فرمان استفاده کنید.

.TP
.B  \-v
.TQ
.B  \-\-verbose
هنگام اجرا، اطلاعات تکمیلی و با جزئیات بیشتر را نمایش می‌دهد.

.TP
.B  \-q
.TP
.B  \-\-quiet
تلاش می‌کند تا حد امکان بدون خروجی اضافی (بی‌صدا) اجرا شود.

.TP
.B  \-\-homedir \fIپوشه\fP
نام پوشه خانگی را برابر با
.I پوشه
قرار می‌دهد. در صورت عدم استفاده از این گزینه، پوشه خانگی به‌صورت پیش‌فرض برابر با \(oq\fI~/.gnupg\fP\(cq خواهد بود. این گزینه تنها زمانی شناسایی می‌شود که در خط فرمان داده شده باشد. همچنین هر پوشه خانگی تعیین‌شده از طریق متغیر محیطی \(oq\fIGNUPGHOME\fP\(cq یا (در سیستم‌های ویندوز) از طریق مدخل رجیستری
.I HKCU\[rs]Software\[rs]GNU\[rs]GnuPG:HomeDir
را بازنویسی می‌کند.
.PP
در سیستم‌های ویندوز امکان نصب GnuPG به عنوان یک برنامه پرتابل وجود دارد. در این حالت تنها همین گزینه خط فرمان در نظر گرفته می‌شود و تمامی روش‌های دیگر برای تعیین پوشه خانگی نادیده گرفته می‌شوند.

.TP
.B  \-\-chuid \fIuid\fP
کاربر فعلی را به
.I uid
تغییر می‌دهد که می‌تواند یک عدد شناسه یا یک نام کاربری باشد. از این گزینه می‌توان از طریق حساب کاربر ارشد (root) برای اجرای gpg-connect-agent برای کاربری دیگر استفاده کرد. اگر
.I uid
شناسه کاربری فعلی نباشد، متغیر PATH استاندارد تنظیم شده و متغیر محیطی GNUPGHOME حذف می‌شود. برای نادیده گرفتن مورد دوم، می‌توان از گزینه
.B \-\-homedir
استفاده کرد. این گزینه تنها در صورتی اثرگذار است که در خط فرمان استفاده شود. این گزینه در حال حاضر در ویندوز هیچ تاثیری ندارد.

.TP
.B  \-\-no\-ext\-connect
هنگام استفاده از
.B \-S
یا
.BR \-\-exec ،
ابزار
.B gpg\-connect\-agent
به منظور امکان انتقال توصیف‌گر (descriptor passing) به سرور Assuan در حالت توسعه‌یافته متصل می‌شود. این گزینه باعث می‌شود که از حالت قدیمی استفاده شود.

.TP
.B  \-\-no\-autostart
در صورتی که gpg-agent یا dirmngr هنوز اجرا نشده باشند، آن‌ها را به‌صورت خودکار آغاز نمی‌کند.

.TP
.B  \-\-no\-history
در حالت تعاملی (interactive)، تاریخچه خط فرمان معمولاً در فایلی زیر پوشه خانگی GnuPG ذخیره و بازیابی می‌شود. این گزینه از استفاده از آن فایل جلوگیری می‌کند.

.TP
.B  \-\-agent\-program \fIفایل\fP
برنامه agent را مشخص می‌کند تا در صورتی که هیچ برنامه‌ای در حال اجرا نباشد، آغاز شود. مقدار پیش‌فرض با اجرای
.B gpgconf
همراه با گزینه
.B \-\-list\-dirs
تعیین می‌شود. توجه داشته باشید که علامت پایپ (\fB|\fP) برای ترفندی در مجموعه آزمون‌های پس‌رفت (regression test suite) استفاده می‌شود و نباید در نام فایل قرار گیرد.

.TP
.B  \-\-dirmngr\-program \fIفایل\fP
برنامه مدیر دایرکتوری (کلاینت keyserver) را مشخص می‌کند تا در صورت در حال اجرا نبودن، آغاز شود. این گزینه تنها زمانی اثر دارد که همراه با گزینه
.B \-\-dirmngr
استفاده شود.

.TP
.B  \-\-keyboxd\-program \fIفایل\fP
برنامه دیمن keybox را مشخص می‌کند تا در صورت در حال اجرا نبودن، آغاز شود. این گزینه تنها زمانی اثر دارد که همراه با گزینه
.B \-\-keyboxd
استفاده شود.

.TP
.B  \-r \fIفایل\fP
.TQ
.B  \-\-run \fIفایل\fP
دستورات موجود در
.I فایل
را در زمان راه‌اندازی اجرا کرده و سپس با روش ورودی معمول ادامه می‌دهد. توجه داشته باشید دستوراتی که در خط فرمان داده می‌شوند پس از این فایل پردازش و اجرا خواهند شد.

.TP
.B  \-s
.TQ
.B  \-\-subst
دستور
.B /subst
را در هنگام راه‌اندازی اجرا می‌کند.

.TP
.B  \-\-hex
سطرهای داده را در قالب هگزادسیمال و نمایش اسکی نویسه‌های غیرکنترلی چاپ می‌کند.

.TP
.B  \-\-decode
سطرهای داده را رمزگشایی (decode) می‌کند؛ یعنی فرارهای درصدی (percent escapes) را حذف می‌کند اما اطمینان می‌دهد که هر سطر جدید همیشه با یک حرف D و یک فاصله آغاز شود.

.TP
.B  \-u
.TQ
.B  \-\-unbuffered
ورودی استاندارد (stdin) و خروجی استاندارد (stdout) را در حالت ورودی/خروجی بدون بافر قرار می‌دهد. این گزینه گاهی برای اسکریپت‌نویسی مفید است.

.SH "دستورات کنترلی (CONTROL COMMANDS)"
هنگام خواندن دستورات Assuan، برنامه gpg-agent همچنین به چند دستور ویژه اجازه می‌دهد تا عملکرد آن را کنترل کنند. تمامی این دستورات کنترلی با یک اسلش (\fB/\fP) آغاز می‌شوند.

.TP
.B  /echo \fIآرگومان‌ها\fP
صرفاً
.I آرگومان‌ها
را چاپ می‌کند.

.TP
.B  /let \fIنام\fP \fIمقدار\fP
متغیر
.I نام
را برابر با
.I مقدار
قرار می‌دهد. متغیرها تنها در صورتی در ورودی جایگزین می‌شوند که از دستور
.B /subst
استفاده شده باشد. متغیرها با افزودن یک علامت دلار در ابتدای نام ارجاع داده می‌شوند و می‌توان نام را به صورت اختیاری درون آکولاد قرار داد. قوانین نام‌گذاری معتبر دقیقاً مشابه قوانین استاندارد شل بورن (Bourne shell) است. این موضوع هنوز اجباری نشده است اما ممکن است در آینده چنین شود. هنگام استفاده از آکولاد، هیچ فاصله خالی در ابتدا یا انتهای نام مجاز نیست.
.PP
اگر متغیری پیدا نشود، در متغیرهای محیطی جستجو می‌شود و در صورت یافتن، در جدول متغیرها کپی می‌گردد.
.PP
توابع متغیر در دسترس هستند: نام تابع باید با حداقل یک فاصله و سپس حداقل یک آرگومان دنبال شود. توابع زیر موجود هستند:
.RS
.TP
.B  get
مقداری را که توسط آرگومان توصیف شده است برمی‌گرداند. آرگومان‌های مجاز عبارتند از:
.RS
.TP
.B  cwd
دایرکتوری کاری فعلی.
.TP
.B  homedir
پوشه خانگی gnupg.
.TP
.B  sysconfdir
دایرکتوری پیکربندی سیستمی GnuPG.
.TP
.B  bindir
دایرکتوری باینری‌های GnuPG.
.TP
.B  libdir
دایرکتوری کتابخانه‌های GnuPG.
.TP
.B  libexecdir
دایرکتوری فایل‌های اجرایی کتابخانه‌ای GnuPG.
.TP
.B  datadir
دایرکتوری داده‌های GnuPG.
.TP
.B  serverpid
شناسه پردازش (PID) سرور فعلی. برای بازگرداندن یک مقدار مفید، باید دستور
.B /serverpid
قبلاً صادر شده باشد.
.RE

.TP
.B  unescape \fIآرگومان‌ها\fP
فرارهای به سبک C را از
.I آرگومان‌ها
حذف می‌کند. توجه داشته باشید که
\fB\[rs]0\fP
و
\fB\[rs]x00\fP
به‌صورت ضمنی به رشته بازگردانده‌شده خاتمه می‌دهند. رشته‌ای که باید تبدیل شود کل آرگومان‌های بلافاصله پس از فاصله جداکننده نام تابع است.

.TP
.B  unpercent \fIآرگومان‌ها\fP
.TQ
.B  unpercent+ \fIآرگومان‌ها\fP
فرارهای به سبک درصدی را از
.I آرگومان‌ها
حذف می‌کند. توجه داشته باشید که
\fB%00\fP
به‌طور ضمنی رشته را خاتمه می‌دهد. رشته‌ای که باید تبدیل شود کل آرگومان‌های بلافاصله پس از فاصله جداکننده نام تابع است. دستور
\fBunpercent+\fP
همچنین علامت‌های جمع را به فاصله نگاشت می‌کند.

.TP
.B  percent \fIآرگومان‌ها\fP
.TQ
.B  percent+ \fIآرگومان‌ها\fP
با استفاده از روش فرار درصدی، کاراکترهای فرار را به
.I آرگومان‌ها
اعمال می‌کند. کلیدهای تب، انتقال صفحه (formfeed)، سرخط (linefeed)، بازگشت به ابتدای سطر (carriage return) و دو‌نقطه فرار داده می‌شوند. دستور
\fBpercent+\fP
همچنین فاصله‌ها را به علامت‌های جمع نگاشت می‌کند.

.TP
.B  errcode \fIآرگومان\fP
.TQ
.B  errsource \fIآرگومان\fP
.TQ
.B  errstring \fIآرگومان\fP
فرض می‌کند که
.I آرگومان
یک عدد صحیح است و آن را با استفاده از
.B strtol
ارزیابی می‌کند. کد خطای gpg-error، منبع خطا یا رشته‌ای قالب‌بندی‌شده شامل کد خطا و منبع خطا را بازمی‌گرداند.

.TP
.B  +
.TQ
.B  \-
.TQ
.B  *
.TQ
.B  /
.TQ
.B  %
تمام آرگومان‌ها را با استفاده از
.B strtol
به عنوان اعداد صحیح بزرگ (long) ارزیابی کرده و این عملگر را روی آن‌ها اعمال می‌کند. تقسیم بر صفر یک رشته خالی برمی‌گرداند.

.TP
.B  !
.TQ
.B  |
.TQ
.B  &
تمام آرگومان‌ها را با استفاده از
.B strtol
به عنوان اعداد صحیح بزرگ ارزیابی کرده و عملگرهای منطقی NOT، OR یا AND را اعمال می‌کند. عملگر NOT تنها روی آخرین آرگومان اعمال می‌شود.
.RE

.TP
.B  /definq \fIنام\fP \fIمتغیر\fP
از محتوای متغیر
.I متغیر
برای پرس‌وجوهای (inquiries) منطبق با
.I نام
استفاده می‌کند.
.I نام
می‌تواند یک علامت ستاره (\fB*\fP) باشد تا با هر پرس‌وجویی تطابق یابد.

.TP
.B  /definqfile \fIنام\fP \fIفایل\fP
از محتوای
.I فایل
برای پرس‌وجوهای منطبق با
.I نام
استفاده می‌کند.
.I نام
می‌تواند یک علامت ستاره (\fB*\fP) باشد تا با هر پرس‌وجویی تطابق یابد.

.TP
.B  /definqprog \fIنام\fP \fIبرنامه\fP
برنامه
.I برنامه
را برای پرس‌وجوهای منطبق با
.I نام
اجرا کرده و کل سطر را به عنوان آرگومان‌های خط فرمان به آن ارسال می‌کند.

.TP
.B  /datafile \fIنام\fP
تمام سطرهای داده دریافت‌شده از سرور را در فایل
.I نام
می‌نویسد. فایل برای نوشتن باز شده و در صورت عدم وجود ایجاد می‌شود. اگر فایل از قبل موجود باشد، ابتدا طول آن به ۰ تقلیل می‌یابد. داده‌های نوشته‌شده در فایل کاملاً رمزگشایی (decode) می‌شوند. استفاده از یک خط تیره تکی برای
.I نام
باعث نوشتن در خروجی استاندارد (stdout) می‌شود. این فایل تا زمانی که فایل جدیدی با این دستور تنظیم شود یا این دستور بدون آرگومان فراخوانی شود، باز می‌ماند.

.TP
.B  /showdef
تمام تعاریف را چاپ می‌کند.

.TP
.B  /cleardef
تمام تعاریف را پاک می‌کند.

.TP
.B  /sendfd \fIفایل\fP \fIحالت\fP
فایل
.I فایل
را در حالت
.I حالت
(که باید یک رشته معتبر برای حالت تابع \fBfopen\fP باشد) باز کرده و توصیف‌گر فایل (file descriptor) را به سرور ارسال می‌کند. این دستور معمولاً با فرمانی مانند
.B INPUT FD
برای تنظیم منبع ورودی برای سایر دستورات دنبال می‌شود.

.TP
.B  /recvfd
هنوز پیاده‌سازی نشده است.

.TP
.B  /open \fIمتغیر\fP \fIفایل\fP [\fIحالت\fP]
فایل
.I فایل
را باز کرده و توصیف‌گر فایل را به
.I متغیر
اختصاص می‌دهد. هشدار: این دستور آزمایشی است و ممکن است در نسخه‌های بعدی تغییر کند.

.TP
.B  /close \fIfd\fP
توصیف‌گر فایل
.I fd
را می‌بندد. هشدار: این دستور آزمایشی است و ممکن است در نسخه‌های بعدی تغییر کند.

.TP
.B  /showopen
فهرستی از فایل‌های باز را نمایش می‌دهد.

.TP
.B  /serverpid
دستور Assuan با عنوان
.B GETINFO pid
را به سرور ارسال کرده و شناسه پردازش (PID) بازگردانده‌شده را برای مصارف داخلی ذخیره می‌کند.

.TP
.B  /sleep
به مدت یک ثانیه توقف موقت (sleep) می‌کند.

.TP
.B  /hex
.TQ
.B  /nohex
مشابه گزینه خط فرمان
.BR \-\-hex
است.

.TP
.B  /decode
.TQ
.B  /nodecode
مشابه گزینه خط فرمان
.BR \-\-decode
است.

.TP
.B  /subst
.TQ
.B  /nosubst
جایگزینی متغیرها را فعال یا غیرفعال می‌کند. به صورت پیش‌فرض غیرفعال است مگر اینکه از گزینه خط فرمان
.B \-\-subst
استفاده شده باشد. اگر
.B /subst
یک‌بار فعال شود، فاصله‌های خالی ابتدای سطرهای ورودی حذف می‌شوند که خوانایی اسکریپت‌ها را آسان‌تر می‌کند.

.TP
.B  /while \fIشرط\fP
.TQ
.B  /end
این دستورات روشی برای اجرای حلقه‌ها فراهم می‌کنند. تمام سطرهای میان
.B while
و
.B end
متناظر، تا زمانی اجرا می‌شوند که ارزیابی
.I شرط
مقداری غیر از صفر داشته باشد یا رشته
.B true
یا
.B yes
باشد. ارزیابی شرط با انتقال
.I شرط
به تابع
.B strtol
انجام می‌شود. مثال:
.RS 2
.nf
  /subst
  /let i 3
  /while $i
    /echo loop counter is $i
    /let i ${\- $i 1}
  /end
.fi
.RE

.TP
.B  /if \fIشرط\fP
.TQ
.B  /end
این دستورات روشی برای اجرای شرطی فراهم می‌کنند. تمام سطرهای میان
.B if
و
.B end
متناظر، تنها در صورتی اجرا می‌شوند که ارزیابی
.I شرط
مقداری غیر از صفر داشته باشد یا رشته
.B true
یا
.B yes
باشد. ارزیابی شرط با انتقال
.I شرط
به تابع
.B strtol
انجام می‌شود.

.TP
.B  /run \fIفایل\fP
دستورات را از
.I فایل
اجرا می‌کند.

.TP
.B  /history \-\-clear
تاریخچه دستورات را پاک می‌کند.

.TP
.B  /bye
اتصال و برنامه را خاتمه می‌دهد.

.TP
.B  /help
فهرستی از دستورات کنترلی در دسترس را چاپ می‌کند.

.SH "همچنین ببینید (SEE ALSO)"
\fBgpg\-agent\fP(1),
\fBscdaemon\fP(1)
.PP
مستندات کامل این ابزار به عنوان یک راهنمای Texinfo نگهداری می‌شود. اگر GnuPG و برنامه info به درستی در سیستم شما نصب شده باشند، اجرای دستور
.RS 2
.nf
info gnupg
.fi
.RE
باید امکان دسترسی به راهنمای کامل شامل ساختار منو و نمایه را برای شما فراهم کند.