الأوامر¶
الأوامر
التالية
مفهومة:
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
--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".
للمصفوفات،
يجب تحديد
وسيط عددي
لعدد
الإدخالات
متبوعًا
بالإدخالات.
للمتغيرات،
يجب تحديد
توقيع
المحتويات،
متبوعًا
بالمحتويات.
للقواميس
والهياكل،
يجب تحديد
محتوياتها
مباشرة.
على سبيل
المثال،
هو تنسيق
سلسلة
واحدة "jawoll".
هو تنسيق
مصفوفة
سلاسل
بثلاثة
إدخالات: "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"