'\" t
.TH "SYSTEMD\-NOTIFY" "1" "" "systemd 261.2" "systemd-notify"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
systemd-notify \- اطلاع‌رسانی به مدیر سرویس درباره تکمیل راه‌اندازی و سایر تغییرات وضعیت دیمن
.SH "خلاصه دستور (SYNOPSIS)"
.HP \w'\fBsystemd\-notify\fR\ 'u
\fBsystemd\-notify\fR [OPTIONS...] [VARIABLE=VALUE...]
.HP \w'\fBsystemd\-notify\fR\ 'u
\fBsystemd\-notify\fR \-\-exec [OPTIONS...] [VARIABLE=VALUE...] ;\ \-\- {CMDLINE...}
.HP \w'\fBsystemd\-notify\fR\ 'u
\fBsystemd\-notify\fR \-\-fork [OPTIONS...] \-\- {CMDLINE...}
.SH "توضیحات (DESCRIPTION)"
.PP
\fBsystemd\-notify\fR
می‌تواند توسط اسکریپت‌های سرویس فراخوانی شود تا تغییرات وضعیت را به مدیر سرویس فراخواننده اطلاع دهد\&. این ابزار می‌تواند برای ارسال اطلاعات دلخواه، کدگذاری‌شده در قالبی شبیه به فهرست رشته‌های بلوک متغیرهای محیطی، استفاده شود\&. مهم‌تر از همه، می‌توان از آن برای اعلان تکمیل راه‌اندازی استفاده کرد\&.
.PP
این ابزار در واقع عمدتاً یک پوسته (wrapper) پیرامون
\fBsd_notify()\fR
است و این قابلیت را در دسترس اسکریپت‌های پوسته قرار می‌دهد\&. برای جزئیات
\fBsd_notify\fR(3)
را ببینید\&.
.PP
خط فرمان ممکن است حاوی فهرستی از متغیرهای محیطی باشد تا به عنوان بخشی از به‌روزرسانی وضعیت ارسال شوند\&.
.PP
توجه داشته باشید که سیستم‌دی از پذیرش به‌روزرسانی‌های وضعیت از این دستور خودداری خواهد کرد مگر اینکه
\fINotifyAccess=\fR
به‌طور مناسب برای واحد سرویسی که این دستور از آن فراخوانی می‌شود تنظیم شده باشد\&. برای جزئیات
\fBsystemd.service\fR(5)
را ببینید\&.
.PP
توجه داشته باشید که اعلان‌های
\fBsd_notify()\fR
تنها در صورتی می‌توانند به درستی به واحدها منتسب شوند که فرآیند ارسال‌کننده در زمان پردازش پیام توسط مدیر سرویس هنوز فعال باشد، یا اینکه فرآیند ارسال‌کننده صراحتاً در زمان اجرا توسط مدیر سرویس ردیابی شود\&. حالت دوم زمانی رخ می‌دهد که مدیر سرویس در ابتدا فرآیند را منشعب (fork) کرده باشد، یعنی در تمام فرآیندهایی که با
\fINotifyAccess=\fR\fBmain\fR
یا
\fINotifyAccess=\fR\fBexec\fR
مطابقت دارند\&. برعکس، اگر یک فرآیند کمکیِ واحد پیامی از طریق
\fBsd_notify()\fR
ارسال کند و بلافاصله خارج شود، مدیر سرویس ممکن است نتواند پیام را به درستی به آن واحد منتسب کند و بنابراین آن را نادیده خواهد گرفت، حتی اگر
\fINotifyAccess=\fR\fBall\fR
برای آن تنظیم شده باشد\&. برای رفع این مشکل،
\fBsystemd\-notify\fR
تا زمانی که پیام اعلان توسط مدیر سرویس پردازش شود منتظر خواهد ماند\&. هنگامی که
\fB\-\-no\-block\fR
استفاده شود، این همگام‌سازی برای دریافت اعلان‌ها غیرفعال می‌گردد و از این رو ممکن است شرایط رقابتی (race condition) یادشده رخ دهد، در صورتی که فرآیند فراخواننده، خودِ مدیر سرویس نبوده یا توسط مدیر سرویس ایجاد نشده باشد\&.
.PP
\fBsystemd\-notify\fR
ابتدا تلاش خواهد کرد تا با وانمود کردن به داشتن PID فرآیند والدِ
\fBsystemd\-notify\fR
(یعنی فرآیند فراخواننده)،
\fBsd_notify()\fR
را فراخوانی کند\&. این کار تنها زمانی موفقیت‌آمیز خواهد بود که با دسترسی‌ها و اختیارات کافی فراخوانی شده باشد\&. در صورت عدم موفقیت، سپس به فراخوانی آن با PID خود بازمی‌گردد\&. این رفتار از این جهت مفید است که وقتی این ابزار از یک اسکریپت پوسته فراخوانی می‌شود، فرآیند پوسته \(em و نه فرآیند
\fBsystemd\-notify\fR
\(em به عنوان فرستنده پیام ظاهر می‌شود؛ که این به نوبه خود، به دلیل محدودیت‌های
\fINotifyAccess=\fR\fBall\fR،
در صورتی که فرآیند پوسته فرآیند اصلی یک سرویس باشد، مفید خواهد بود\&. از سوییچ
\fB\-\-pid=\fR
برای دستکاری این رفتار استفاده کنید\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
گزینه‌های زیر پشتیبانی می‌شوند:
.PP
\fB\-\-ready\fR
.RS 4
مدیر سرویس فراخواننده را از تکمیل راه‌اندازی سرویس یا بارگذاری مجدد پیکربندی مطلع می‌کند\&. این معادل
\fBsystemd\-notify READY=1\fR
است\&. برای جزئیات درباره مفاهیم معنایی این گزینه،
\fBsd_notify\fR(3)
را ببینید\&.
.RE
.PP
\fB\-\-reloading\fR
.RS 4
مدیر سرویس فراخواننده را از آغاز چرخه بارگذاری مجدد پیکربندی مطلع می‌کند\&. این معادل
\fBsystemd\-notify RELOADING=1\fR
است (اما به صورت ضمنی فیلد
\fIMONOTONIC_USEC=\fR
را نیز همان‌طور که برای سرویس‌های
\fIType=notify\-reload\fR
لازم است تنظیم می‌کند؛ برای جزئیات
\fBsystemd.service\fR(5)
را ببینید)\&. برای جزئیات درباره مفاهیم معنایی این گزینه،
\fBsd_notify\fR(3)
را ببینید\&.
.sp
افزوده شده در نسخه 253\&.
.RE
.PP
\fB\-\-stopping\fR
.RS 4
مدیر سرویس فراخواننده را از آغاز مرحله خاموش‌شدن (shutdown) سرویس مطلع می‌کند\&. این معادل
\fBsystemd\-notify STOPPING=1\fR
است\&. برای جزئیات درباره مفاهیم معنایی این گزینه،
\fBsd_notify\fR(3)
را ببینید\&.
.sp
افزوده شده در نسخه 253\&.
.RE
.PP
\fB\-\-pid=\fR
.RS 4
مدیر سرویس را از PID اصلی سرویس مطلع می‌کند\&. یک PID را به عنوان آرگومان دریافت می‌کند\&. اگر آرگومان به صورت
"auto"
مشخص شود یا حذف گردد، از PID فرآیندی که
\fBsystemd\-notify\fR
را فراخوانی کرده استفاده می‌شود، مگر اینکه آن فرآیند مدیر سرویس باشد\&. اگر آرگومان به صورت
"self"
مشخص شود، از PID خودِ دستور
\fBsystemd\-notify\fR
استفاده می‌شود، و اگر
"parent"
مشخص شود، از PID فرآیند فراخواننده استفاده می‌شود \(em حتی اگر مدیر سرویس باشد\&.
\fB\-\-pid=auto\fR
معادل
\fBsystemd\-notify \-\-pid=$PID\fR
است\&. برای جزئیات درباره مفاهیم معنایی این گزینه،
\fBsd_notify\fR(3)
را ببینید\&.
.sp
\fBsystemd\-notify\fR
ابتدا تلاش خواهد کرد تا با وانمود کردن به داشتن PID مشخص‌شده با
\fB\-\-pid=\fR،
\fBsd_notify()\fR
را فراخوانی کند\&. این کار تنها در صورتی موفقیت‌آمیز خواهد بود که با اختیارات کافی فراخوانی شده باشد\&. در صورت عدم موفقیت، سپس به فراخوانی آن با PID خود بازمی‌گردد\&. در عمل، این بدان معناست که یک فراخوانی ممتاز از
\fBsystemd\-notify \-\-pid=\fR
ممکن است محدودیت‌های اعمال‌شده
\fINotifyAccess=main\fR
یا
\fINotifyAccess=exec\fR
برای یک سرویس را دور بزند\&.
.sp
اگر این سوییچ در یک فراخوانی بدون اختیارات ممتاز از
\fBsystemd\-notify\fR
توسط فرآیندی استفاده شود که قرار است فرآیند اصلی جدید یک سرویس باشد \(em و آن فرآیند توسط مدیر سرویس منشعب نشده باشد (یا فرآیند اصلی فعلی نباشد) \(em، در این صورت ضروری است که
\fINotifyAccess=all\fR
در فایل واحد سرویس تنظیم شود، در غیر این صورت به دلایل امنیتی اعلان نادیده گرفته خواهد شد\&. برای جزئیات
\fBsystemd.service\fR(5)
را ببینید\&.
.RE
.PP
\fB\-\-uid=\fR\fB\fIUSER\fR\fR
.RS 4
شناسه کاربر (UID) را برای ارسال اعلان از طرف آن تنظیم می‌کند\&. یک نام کاربری یونیکس یا UID عددی را دریافت می‌کند\&. در صورت تعیین، پیام اعلان با UID مشخص‌شده به عنوان فرستنده ارسال خواهد شد، به جای کاربری که دستور تحت آن فراخوانی شده است\&. این گزینه برای اینکه بتواند هویت کاربری فرآیند را دستکاری کند به اختیارات کافی نیاز دارد\&.
.sp
افزوده شده در نسخه 237\&.
.RE
.PP
\fB\-\-status=\fR
.RS 4
یک رشته وضعیت آزاد و خوانا برای انسان برای دیمن به مدیر سرویس ارسال می‌کند\&. این گزینه رشته وضعیت را به عنوان آرگومان دریافت می‌کند\&. این معادل
\fBsystemd\-notify STATUS=\&...\fR
است\&. برای جزئیات درباره مفاهیم معنایی این گزینه،
\fBsd_notify\fR(3)
را ببینید\&. این اطلاعات علاوه بر سایر مکان‌ها، در خروجی
\fBstatus\fR
دستور
\fBsystemctl\fR(1)\*(Aq
نیز نمایش داده می‌شود\&.
.RE
.PP
\fB\-\-booted\fR
.RS 4
اگر سیستم با سیستم‌دی راه‌اندازی (boot) شده باشد مقدار 0 و در غیر این صورت مقداری غیر صفر برمی‌گرداند\&. اگر این گزینه ارسال شود، هیچ پیامی ارسال نخواهد شد\&. بنابراین این گزینه ارتباطی با گزینه‌های دیگر ندارد\&. برای جزئیات درباره مفاهیم معنایی این گزینه،
\fBsd_booted\fR(3)
را ببینید\&. یک روش جایگزین برای بررسی این وضعیت، فراخوانی
\fBsystemctl\fR(1)
با دستور
\fBis\-system\-running\fR
است\&. اگر سیستم با سیستم‌دی بوت نشده باشد، خروجی آن
"offline"
خواهد بود، هرچند مقدار بازگشتی معنای متفاوتی دارد\&.
.RE
.PP
\fB\-\-no\-block\fR
.RS 4
به‌طور همگام منتظر پایان عملیات درخواست‌شده نمی‌ماند\&. استفاده از این گزینه تنها زمانی توصیه می‌شود که
\fBsystemd\-notify\fR
توسط مدیر سرویس ایجاد شده باشد، یا زمانی که فرآیند فراخواننده مستقیماً توسط مدیر سرویس ایجاد شده و دسترسی‌های کافی داشته باشد تا به
\fBsystemd\-notify\fR
اجازه دهد از طرف آن اعلان را ارسال کند\&. ارسال اعلان‌ها با تنظیم این گزینه در سایر موارد مستعد شرایط رقابتی (race conditions) است\&.
.sp
افزوده شده در نسخه 246\&.
.RE
.PP
\fB\-\-exec\fR
.RS 4
در صورت تعیین،
\fBsystemd\-notify\fR
پس از تکمیل عملیات خود، خط فرمان دیگری را اجرا کرده و جایگزین فرآیند خود می‌کند\&. در صورت استفاده، فهرست انتساب‌ها برای گنجاندن در پیام ارسالی باید با یک نویسه
";"
(به عنوان آرگومان جداگانه) و به دنبال آن خط فرمان برای اجرا دنبال شود\&. این امکان «زنجیره‌سازی» دستورات را فراهم می‌کند، یعنی صادر کردن یک عملیات و بلافاصله پس از آن عملیاتی دیگر، بدون تغییر PIDها\&.
.sp
توجه داشته باشید که بسیاری از پوسته‌ها
";"
را به عنوان جداکننده خط فرمان خود تفسیر می‌کنند، بنابراین زمانی که
\fBsystemd\-notify\fR
از یک پوسته فراخوانی می‌شود، نقطه ویرگول معمولاً باید به صورت
"\e;"
گریز داده شود (escaped)\&.
.sp
افزوده شده در نسخه 254\&.
.RE
.PP
\fB\-\-fd=\fR
.RS 4
یک توصیف‌کننده فایل را همراه با پیام اعلان ارسال می‌کند\&. این گزینه هنگام فراخوانی در سرویس‌هایی که تنظیم
\fIFileDescriptorStoreMax=\fR
در آن‌ها فعال است مفید است؛ برای جزئیات
\fBsystemd.service\fR(5)
را ببینید\&. توصیف‌کننده فایل مشخص‌شده هنگام فراخوانی باید به
\fBsystemd\-notify\fR
ارسال شود\&. این گزینه می‌تواند چندین بار برای ارسال چندین توصیف‌کننده فایل در یک پیام اعلان منفرد استفاده شود\&.
.sp
برای استفاده از این قابلیت از یک پوسته
\fBbash\fR(1)،
از عبارتی مانند زیر استفاده کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\-notify \-\-fd=4 \-\-fd=5 4</some/file 5</some/other/file
.fi
.if n \{\
.RE
.\}
.sp
افزوده شده در نسخه 254\&.
.RE
.PP
\fB\-\-fdname=\fR
.RS 4
نامی را برای اختصاص دادن به توصیف‌کننده‌های فایلی که از طریق
\fB\-\-fd=\fR
ارسال شده‌اند (بالا را ببینید) تنظیم می‌کند\&. این گزینه فیلد
"FDNAME="
را کنترل می‌کند\&. این تنظیم فقط می‌تواند یک بار مشخص شود و برای همه توصیف‌کننده‌های فایل ارسال‌شده اعمال می‌شود\&. در صورتی که چندین توصیف‌کننده فایل با نام‌های متفاوت باید ارسال شوند، این ابزار را چندین بار فراخوانی کنید\&.
.sp
افزوده شده در نسخه 254\&.
.RE
.PP
\fB\-\-fork\fR
.RS 4
به جای ارسال پیام اعلان، یک خط فرمان را منشعب (fork) کرده و منتظر می‌ماند تا پیام
"READY=1"
از آن دریافت شود\&. به عبارت دیگر: این گزینه
\fBsystemd\-notify\fR
را به جای فرستنده، به دریافت‌کننده پیام‌های اعلان تبدیل کرده و نقش‌ها را جابه‌جا می‌کند\&. این گزینه برای انشعاب سریع فرآیندی که پروتکل
\fBsd_notify()\fR
را از یک اسکریپت پوسته پیاده‌سازی می‌کند، مفید است\&. ورودی استاندارد و خروجی استاندارد خط فرمان فراخوانی‌شده به
/dev/null
متصل خواهند شد، اما خطای استاندارد از فرآیند فراخواننده به ارث برده می‌شود\&. شناسه عددی فرآیند توسط
\fBsystemd\-notify\fR
در خروجی استاندارد نوشته می‌شود (مگر اینکه
\fB\-\-quiet\fR
مشخص شده باشد)، که بعداً می‌تواند برای خاتمه دادن به فرآیند منشعب‌شده استفاده شود\&.
.sp
توجه داشته باشید فرآیندهایی که بدین شکل منشعب می‌شوند احتمالاً پس از آنکه
\fBsystemd\-notify\fR
قبلاً بازگشته است همچنان در حال اجرا باقی خواهند ماند، که در نتیجه منجر به این می‌شود که والد جدید آن‌ها نزدیک‌ترین فرآیند دروگر (process reaper)، یعنی معمولاً مدیر سرویس به ازای هر کاربر یا مدیر سرویس سراسری سیستم شود\&.
.sp
توجه داشته باشید که این گزینه نباید برای فراخوانی موقت سرویس‌های کامل استفاده شود، برای این کار از
\fBsystemd\-run\fR
استفاده کنید\&.
.sp
همچنین توجه داشته باشید که در صورت فراخوانی با این سوییچ،
\fBsystemd\-notify\fR
تحت دو شرایط متمایز با موفقیت خارج خواهد شد:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
\fBsystemd\-notify\fR
یک اعلان
"READY=1"
از فرآیند فرزندی که به تازگی منشعب کرده است دریافت کرده باشد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
فرآیند فرزند قبل از ارسال
"READY=1"
به صورت تمیز (با کد خروج صفر) خارج شده باشد\&.
.RE
.sp
نمونه استفاده:
.sp
.if n \{\
.RS 4
.\}
.nf
# PID=$(systemd\-notify \-\-fork \-\- mycommand)
\&...
kill "$PID"
unset PID
.fi
.if n \{\
.RE
.\}
.sp
افزوده شده در نسخه 258\&.
.RE
.PP
\fB\-\-quiet\fR, \fB\-q\fR
.RS 4
هنگام استفاده از
\fB\-\-fork\fR،
چاپ شناسه عددی فرآیند را خاموش می‌کند\&.
.sp
افزوده شده در نسخه 258\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
یک متن راهنمای کوتاه را چاپ کرده و خارج می‌شود\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
یک رشته کوتاه نسخه را چاپ کرده و خارج می‌شود\&.
.RE
.SH "کدهای خروج (EXIT STATUS)"
.PP
در صورت موفقیت، 0 برگردانده می‌شود؛ در غیر این صورت یک کد خطای غیر صفر برگردانده خواهد شد\&.
.SH "مثال‌ها (EXAMPLES)"
.PP
\fBمثال\ \&1.\ \&اعلان راه‌اندازی و به‌روزرسانی‌های وضعیت\fR
.PP
یک دیمن ساده پوسته که پس از آماده‌سازی کانال ارتباطی خود، اعلان‌های راه‌اندازی را ارسال می‌کند\&. در طول زمان اجرا به‌روزرسانی‌های وضعیت بیشتری را به سیستم init ارسال می‌کند:
.sp
.if n \{\
.RS 4
.\}
.nf
#!/bin/sh

mkfifo /tmp/waldo
systemd\-notify \-\-ready \-\-status="Waiting for data\&..."

while : ; do
        read \-r a < /tmp/waldo
        systemd\-notify \-\-status="Processing $a"

        # Do something with $a \&...

        systemd\-notify \-\-status="Waiting for data\&..."
done
.fi
.if n \{\
.RE
.\}
.SH "همچنین ببینید (SEE ALSO)"
.PP
\fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd.unit\fR(5), \fBsystemd.service\fR(5), \fBsd_notify\fR(3), \fBsd_booted\fR(3)