BUSCTL(1)

الاسم
busctl - استكشاف الناقل

موجز

busctl [خيارات...] [أمر] [اسم...]

الوصف

يمكن استخدام busctl لاستكشاف ومراقبة ناقل D-Bus.

الأوامر

الأوامر التالية مفهومة:

list
    عرض جميع الأقران على الناقل، بأسماء خدماتهم. افتراضياً، يعرض الأسماء الفريدة والمعروفة معاً، ولكن يمكن تغيير ذلك باستخدام المفتاحين --unique و --acquired. هذه هي العملية المبدئية إذا لم يُحدد أمر.

    أُضيف في الإصدارة 209.

status [خدمة]
    عرض معلومات العملية وبيانات الاستيثاق لخدمة ناقل (إذا حُددت باسمها الفريد أو المعروف)، أو عملية (إذا حُددت بمعرف العملية الرقمي PID)، أو مالك الناقل (إذا لم يُحدد أي معامل).

    أُضيف في الإصدارة 209.

monitor [خدمة...]
    تفريغ الرسائل المتبادلة. إذا حُدد خدمة، اعرض الرسائل الواردة أو الصادرة من هذا القرين، المُعرّف باسمه المعروف أو الفريد. وإلا، اعرض جميع الرسائل على الناقل. استخدم Ctrl+C لإنهاء التفريغ أو قيّده بالخيار --limit-messages=.

    أُضيف في الإصدارة 209.

capture [خدمة...]
    مشابه لـ monitor لكنه يكتب المخرجات بصيغة pcapng (للتفاصيل، انظر PCAP Next Generation (pcapng) Capture File Format[1]). تأكد من توجيه المخرجات القياسية إلى ملف أو أنبوب. يمكن استخدام أدوات مثل wireshark(1) لتحليل وعرض الملفات الناتجة.

    أُضيف في الإصدارة 218.

tree [خدمة...]
    عرض شجرة كائنات لخدمة واحدة أو أكثر. إذا حُدد خدمة، اعرض شجرة كائنات الخدمات المحددة فقط. وإلا، اعرض جميع أشجار الكائنات لجميع الخدمات على الناقل التي حصلت على اسم معروف واحد على الأقل.

    أُضيف في الإصدارة 218.

introspect خدمة كائن [واجهة]
    عرض الواجهات والطرق والخصائص والإشارات للكائن المحدد (المُعرّف بمساره) على الخدمة المحددة. إذا مُرر معامل الواجهة، يُقتصر المخرجات على أعضاء الواجهة المحددة.

    أُضيف في الإصدارة 218.

call خدمة كائن واجهة طريقة [توقيع [وسيطة...]]
    استدعاء طريقة وعرض الاستجابة. يأخذ اسم خدمة، ومسار كائن، واسم واجهة، واسم طريقة. إذا كان يجب تمرير معاملات إلى استدعاء الطريقة، يلزم سلسلة توقيع، متبوعة بالوسائط، كل منها مُنسق كسلسلة. للتفاصيل حول التنسيق المستخدم، انظر أدناه. لكتم مخرجات البيانات المُعادة، استخدم الخيار --quiet.

    أُضيف في الإصدارة 218.

emit كائن واجهة إشارة [توقيع [وسيطة...]]
    إصدار إشارة. يأخذ مسار كائن، واسم واجهة، واسم طريقة. إذا كان يجب تمرير معاملات، يلزم سلسلة توقيع، متبوعة بالوسائط، كل منها مُنسق كسلسلة. للتفاصيل حول التنسيق المستخدم، انظر أدناه. لتحديد وجهة الإشارة، استخدم الخيار --destination=.

    أُضيف في الإصدارة 242.

wait [خدمة] كائن واجهة إشارة
    انتظار إشارة. يأخذ مسار كائن، واسم واجهة، واسم إشارة. استخدم الخيار --limit-messages= لانتظار أكثر من إشارة واحدة قبل الخروج. لكتم مخرجات البيانات المُعادة، استخدم الخيار --quiet. يمكن حذف اسم الخدمة، وفي هذه الحالة سيطابق busctl الإشارات من أي مُرسل.

    أُضيف في الإصدار 257.

get-property خدمة كائن واجهة خاصية...
    استرجاع القيمة الحالية لخاصية كائن واحدة أو أكثر. يأخذ اسم خدمة، ومسار كائن، واسم واجهة، واسم خاصية. يمكن تحديد خصائص متعددة مرة واحدة، وفي هذه الحالة ستُعرض قيمها واحدة تلو الأخرى، مفصولة بأسطر جديدة. المخرجات، افتراضياً، بصيغة موجزة. استخدم --verbose للحصول على صيغة مخرجات أكثر تفصيلاً.

    أُضيف في الإصدارة 218.

set-property خدمة كائن واجهة خاصية توقيع وسيطة...
    تعيين القيمة الحالية لخاصية كائن. يأخذ اسم خدمة، مسار كائن، اسم واجهة، اسم خاصية، توقيع خاصية، متبوعًا بقائمة من المعاملات المنسقة كسلاسل نصية.

    أُضيف في الإصدارة 218.

help
    أظهر مساعدة بناء جملة الأمر.

    أُضيف في الإصدارة 209.

الخيارات

الخيارات التالية مفهومة:

--address=ADDRESS
    الاتصال بالناقل المحدد بواسطة ADDRESS بدلاً من استخدام المبدئيات المناسبة لناقل النظام أو المستخدم (انظر خيارات --system و --user).

    أُضيف في الإصدارة 209.

--show-machine
    عند عرض قائمة الأقران، إظهار عمود يحتوي على أسماء الحاويات التي ينتمون إليها. انظر systemd-machined.service(8).

    أُضيف في الإصدارة 209.

--unique
    عند عرض قائمة الأقران، إظهار الأسماء "الفريدة" فقط (من الشكل ":number.number").

    أُضيف في الإصدارة 209.

--acquired
    عكس --unique — سيتم عرض الأسماء "المعروفة" فقط.

    أُضيف في الإصدارة 209.

--activatable
    عند عرض قائمة الأقران، إظهار الأقران التي لم يتم تنشيطها بعد، ولكن قد يتم تشغيلها آليًا إذا تم الوصول إليها.

    أُضيف في الإصدارة 209.

--match=MATCH
    عند عرض الرسائل المتبادلة، إظهار المجموعة الفرعية المطابقة لـ MATCH فقط. انظر sd_bus_add_match(3).

    أُضيف في الإصدارة 209.

--size=
    عند استخدامه مع أمر capture، يحدد الحد الأقصى لحجم رسالة الناقل للالتقاط ("snaplen"). المبدئي هو 4096 بايت.

    أُضيف في الإصدارة 218.

--list
    عند استخدامه مع أمر tree، يعرض قائمة مسطحة من مسارات الكائنات بدلاً من شجرة.

    أُضيف في الإصدارة 218.

-q، --quiet
    عند استخدامه مع أمر call، يمنع عرض حمولة رسالة الاستجابة. لاحظ أنه حتى إذا تم تحديد هذا الخيار، ستظل الأخطاء المرتجعة مطبوعة وستشير الأداة إلى النجاح أو الفشل برمز خروج العملية.

    أُضيف في الإصدارة 218.

--verbose
    عند استخدامه مع أمر call أو get-property، يعرض المخرجات بتنسيق أكثر تفصيلاً.

    أُضيف في الإصدارة 218.

--xml-interface
    عند استخدامه مع استدعاء introspect، تفريغ وصف XML المستلم من استدعاء D-Bus org.freedesktop.DBus.Introspectable.Introspect بدلاً من المخرجات العادية.

    أُضيف في الإصدار 243.

--expect-reply=BOOL
    عند استخدامه مع أمر call، يحدد ما إذا كان busctl سينتظر اكتمال استدعاء الأسلوب، وإخراج بيانات استجابة الأسلوب المرتجعة، وإرجاع النجاح أو الفشل عبر رمز خروج العملية. إذا تم تعيين هذا إلى "no"، سيتم إصدار استدعاء الأسلوب ولكن لا يُتوقع أي استجابة، وتنتهي الأداة فورًا، وبالتالي لا يمكن عرض أي استجابة، ولا يتم إرجاع أي نجاح أو فشل عبر رمز الخروج. لقمع إخراج حمولة رسالة الرد فقط، استخدم --quiet أعلاه. المبدئي هو "yes".

    أُضيف في الإصدارة 218.

--auto-start=BOOL
    عند استخدامه مع أمر call أو emit، يحدد ما إذا كان استدعاء الأسلوب يجب أن ينشط ضمنيًا الخدمة المستدعاة، إذا لم تكن قيد التشغيل بعد ولكنها مهيأة للبدء آليًا. المبدئي هو "yes".

    أُضيف في الإصدارة 218.

--allow-interactive-authorization=BOOL
    عند استخدامه مع أمر call، يحدد ما إذا كانت الخدمات قد تفرض الاستيثاق التفاعلي أثناء تنفيذ العملية، إذا كانت سياسة الأمان مهيأة لذلك. المبدئي هو "yes".

    أُضيف في الإصدارة 218.

--timeout=ثوانٍ
    عند استخدامه مع أمر call، يحدد الحد الأقصى للوقت لانتظار اكتمال استدعاء الأسلوب. عند استخدامه مع أمر monitor، منذ الإصدار v257، يحدد الحد الأقصى للوقت لانتظار الرسائل قبل الخروج آليًا. إذا لم يتم تحديد وحدة زمنية، يفترض الثواني. الوحدات الأخرى المعتادة مفهومة أيضًا (ms, us, s, min, h, d, w, month, y). لاحظ أن هذا المهلة لا تنطبق إذا تم استخدام --expect-reply=no، عند دمجه مع أمر call، لأن الأداة لا تنتظر أي رسالة رد حينها. عندما لا يتم تحديده أو عند تعيينه إلى 0، يفترض المبدئي "25s" لأمر call، ويتم تعطيله لأمر monitor.

    أُضيف في الإصدارة 218.

--limit-messages=NUMBER, -N NUMBER
    عند استخدامه مع أمر monitor، إذا تم تمكينه، سيجعل busctl يخرج عند استلام وطباعة العدد المحدد من الرسائل. هذا مفيد بالاقتران مع --match=، لانتظار العدد المحدد من مرات حدوث رسائل D-Bus محددة. بينما إذا لم يتم تحديده أو تم تعيينه إلى القيمة الخاصة "infinity"، فالمبدئي هو الاستمرار في المراقبة دون قيود.

    عند استخدامه مع أمر wait، سيجعل busctl يخرج عند استلام وطباعة العدد المحدد من إشارات DBus. تعيينه إلى القيمة الخاصة "infinity" سيدعم busctl لاستقبال وطباعة الإشارات باستمرار دون قيود. عندما لا يتم تحديد شيء، المبدئي هو الخروج فورًا بعد استلام وطباعة الإشارة الأولى.

    أُضيف في الإصدار 257.

--augment-creds=BOOL
    يتحكم فيما إذا كانت بيانات الاعتماد المبلغ عنها بواسطة list أو status ستُعزز ببيانات من /proc/. عند تشغيل هذا، قد تكون البيانات المعروضة غير متسقة، لأن البيانات المقروءة من /proc/ قد تكون أحدث من بقية معلومات الاعتماد. المبدئي هو "yes".

    أُضيف في الإصدارة 218.

--watch-bind=BOOL
    يتحكم فيما إذا كان سيُنتظر ظهور مقبس الناقل AF_UNIX المحدد في نظام الملفات قبل الاتصال به. المبدئي هو إيقاف. عند التمكين، ستُراقب الأداة نظام الملفات حتى يُنشأ المقبس ثم تتصل به.

    أُضيف في الإصدارة 237.

--destination=SERVICE
    يأخذ اسم خدمة. عند استخدامه مع أمر emit، يُصدر إشارة إلى الخدمة المحددة.

    أُضيف في الإصدارة 242.

--user
    تحدث مع مدير خدمة المستدعِي، بدلاً من مدير خدمة النظام.

--system
    تحدث مع مدير خدمة النظام. هذا هو المبدئي الضمني.

-H، --host=
    نفّذ العملية عن بُعد. حدد اسم مضيف، أو اسم مستخدم واسم مضيف يفصل بينهما "@" للاتصال به. يمكن اختيارياً إلحاق اسم المضيف بمنفذ يستمع إليه ssh، مفصولاً بـ ":"، ثم اسم حاوية، مفصولاً بـ "/"، مما يوصل مباشرة بحاوية معينة على المضيف المحدد. سيستخدم هذا SSH للتحدث إلى نسخة مدير الحاسوب البعيد. يمكن سرد أسماء الحاويات باستخدام machinectl -H المضيف. ضع عناوين IPv6بين قوسين.

-M، --machine=
    نفّذ العملية على حاوية محلية. حدد اسم الحاوية للاتصال بها، مسبوقًا اختياريًا باسم مستخدم للاتصال به وحرف "@" كفاصل. إذا استُخدمت السلسلة الخاصة ".host" بدلاً من اسم الحاوية، فسيُجرى اتصال بالنظام المحلي (وهو أمر مفيد للاتصال بناقل مستخدم معين: "--user --machine=lennart@.host"). إذا لم تُستخدم صيغة "@"، فسيُتصل كمستخدم جذر (root). إذا استُخدمت صيغة "@"، فيمكن حذف الجانب الأيسر أو الأيمن (ولكن ليس كلاهما) وفي هذه الحالة يُفترض اسم المستخدم المحلي و ".host".

-C، --capsule=
    نفذ العملية على كبسولة. حدد اسم الكبسولة للاتصال بها. راجع capsule@.service(5) لمزيد من التفاصيل حول الكبسولات.

    أُضيف في الإصدار 256.

-l، --full
    لا تُختصر المخرجات في أمر list.

    أُضيف في الإصدار 245.

--json=وضع
    يظهر المخرجات منسقة بصيغة JSON. يتوقع أحد الخيارات: "short" (لأقصر مخرج ممكن دون أي مسافات زائدة أو فواصل أسطر)، أو "pretty" (لنسخة جميلة من المخرج نفسه، مع إزاحة وفواصل أسطر) أو "off" (لإيقاف مخرجات JSON، وهو الخيار المبدئي).

-j
    يكافئ --json=pretty إذا كان يعمل على طرفية، و --json=short في الحالات الأخرى.

--no-pager
    لا تمرر المخرجات إلى برنامج عرض (pager).

--no-legend
    لا تطبع مفتاح الرموز، أي ترويسات الأعمدة والتذييل المزود بالتلميحات.

-h، --help
    اطبع نص مساعدة قصير واخرج.

--version
    اطبع سلسلة إصدار قصيرة واخرج.

تنسيق المعاملات

يأخذ أمرا call و set-property سلسلة توقيع متبوعة بقائمة من المعاملات المنسقة كسلسلة (للتفاصيل حول سلاسل توقيع D-Bus، انظر فصل نظام الأنواع من مواصفات D-Bus[2]). للأنواع البسيطة، يجب أن يكون كل معامل يتبع التوقيع ببساطة قيمة المعامل المنسقة كسلسلة. يمكن تنسيق القيم المنطقية الموجبة كـ "true" أو "yes" أو "on" أو "1"؛ والقيم المنطقية السالبة كـ "false" أو "no" أو "off" أو "0". للمصفوفات، يجب تحديد وسيط عددي لعدد الإدخالات متبوعًا بالإدخالات. للمتغيرات، يجب تحديد توقيع المحتويات، متبوعًا بالمحتويات. للقواميس والهياكل، يجب تحديد محتوياتها مباشرة.

على سبيل المثال،

    s jawoll

هو تنسيق سلسلة واحدة "jawoll".

    as 3 hello world foobar

هو تنسيق مصفوفة سلاسل بثلاثة إدخالات: "hello" و "world" و "foobar".

    a{sv} 3 One s Eins Two u 2 Yes b true

هو تنسيق مصفوفة قاموس تربط السلاسل بالمتغيرات، وتتكون من ثلاثة إدخالات. السلسلة "One" تُسند إليها السلسلة "Eins". السلسلة "Two" يُسند إليها العدد الصحيح غير الموقع 32 بت 2. السلسلة "Yes" يُسند إليها قيمة منطقية موجبة.

لاحظ أن أوامر call و get-property و introspect ستُولد أيضًا مخرجات بهذا التنسيق للبيانات المرتجعة. نظرًا لأن هذا التنسيق أحيانًا يكون موجزًا جدًا بحيث لا يُفهم بسهولة، فقد تُولد أوامر call و get-property مخرجات أكثر تفصيلاً ومتعددة الأسطر عند تمرير خيار --verbose.

أمثلة

مثال 1. كتابة وقراءة خاصية

يكتب الأمران التاليان أولاً خاصية ثم يقرآنها مرة أخرى. توجد الخاصية على كائن "/org/freedesktop/systemd1" لخدمة "org.freedesktop.systemd1". اسم الخاصية هو "LogLevel" على واجهة "org.freedesktop.systemd1.Manager". تحتوي الخاصية على سلسلة واحدة:

    # busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
    # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
    s "debug"

مثال 2. مخرجات موجزة ومفصلة

يقرأ الأمران التاليان خاصية تحتوي على مصفوفة من السلاسل، ويعرضانها أولاً بتنسيق موجز، متبوعًا بالتنسيق المفصل:

    $ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
    as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
    $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
    ARRAY "s" {
            STRING "LANG=en_US.UTF-8";
            STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
    };

مثال 3. استدعاء أسلوب

يستدعي الأمر التالي أسلوب "StartUnit" على واجهة "org.freedesktop.systemd1.Manager" لكائن "/org/freedesktop/systemd1" لخدمة "org.freedesktop.systemd1"، ويمرر له سلسلتين "cups.service" و "replace". كنتيجة لاستدعاء الأسلوب، يُستقبل معامل مسار كائن واحد ويُعرض:

    # busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
    o "/org/freedesktop/systemd1/job/42684"

انظر أيضًا

dbus-daemon(1), D-Bus[3], sd-bus(3), varlinkctl(1), systemd(1), machinectl(1), wireshark(1)

ملاحظات

1.  تنسيق ملف الالتقاط PCAP Next Generation (pcapng)
    https://github.com/pcapng/pcapng/

2.  فصل نظام الأنواع من مواصفات D-Bus
    https://dbus.freedesktop.org/doc/dbus-specification.html#type-system

3.  D-Bus
    https://www.freedesktop.org/wiki/Software/dbus

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.