From: Sven Eden Date: Wed, 19 Jul 2017 11:46:39 +0000 (+0200) Subject: Prep v233.3: Add missing documentation for API functions exported by elogind. (unrevi... X-Git-Tag: v233.3~8 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=56c19a4f2a0091a3fe23712cbbc6c6e379572ffe Prep v233.3: Add missing documentation for API functions exported by elogind. (unreviewed) --- diff --git a/Makefile-man.am b/Makefile-man.am index f43808bdc..b25bb0043 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -11,11 +11,36 @@ MANPAGES += \ man/elogind.8 \ man/loginctl.1 \ man/logind.conf.5 \ + man/sd-bus.3 \ man/sd-event.3 \ man/sd_booted.3 \ + man/sd_bus_add_match.3 \ + man/sd_bus_creds_get_pid.3 \ + man/sd_bus_creds_new_from_pid.3 \ + man/sd_bus_default.3 \ + man/sd_bus_error.3 \ + man/sd_bus_error_add_map.3 \ + man/sd_bus_get_fd.3 \ + man/sd_bus_message_append.3 \ + man/sd_bus_message_append_array.3 \ + man/sd_bus_message_append_basic.3 \ + man/sd_bus_message_append_strv.3 \ + man/sd_bus_message_read_basic.3 \ + man/sd_bus_negotiate_fds.3 \ + man/sd_bus_new.3 \ + man/sd_bus_process.3 \ + man/sd_bus_request_name.3 \ + man/sd_bus_track_add_name.3 \ + man/sd_bus_track_new.3 \ + man/sd_event_add_child.3 \ + man/sd_event_add_defer.3 \ man/sd_event_add_io.3 \ + man/sd_event_add_signal.3 \ + man/sd_event_add_time.3 \ man/sd_event_exit.3 \ + man/sd_event_new.3 \ man/sd_event_now.3 \ + man/sd_event_run.3 \ man/sd_event_set_watchdog.3 \ man/sd_event_source_get_event.3 \ man/sd_event_source_get_pending.3 \ @@ -25,73 +50,352 @@ MANPAGES += \ man/sd_event_source_set_priority.3 \ man/sd_event_source_set_userdata.3 \ man/sd_event_source_unref.3 \ + man/sd_event_wait.3 \ man/sd_id128_get_machine.3 \ man/sd_id128_randomize.3 \ man/sd_id128_to_string.3 \ + man/sd_is_fifo.3 \ + man/sd_listen_fds.3 \ man/sd_machine_get_class.3 \ man/sd_notify.3 \ man/sd_watchdog_enabled.3 MANPAGES_ALIAS += \ + man/SD_BUS_ERROR_END.3 \ + man/SD_BUS_ERROR_MAKE_CONST.3 \ + man/SD_BUS_ERROR_MAP.3 \ + man/SD_BUS_ERROR_NULL.3 \ + man/SD_EVENT_ARMED.3 \ + man/SD_EVENT_EXITING.3 \ + man/SD_EVENT_FINISHED.3 \ + man/SD_EVENT_INITIAL.3 \ man/SD_EVENT_OFF.3 \ man/SD_EVENT_ON.3 \ man/SD_EVENT_ONESHOT.3 \ + man/SD_EVENT_PENDING.3 \ + man/SD_EVENT_PREPARING.3 \ man/SD_EVENT_PRIORITY_IDLE.3 \ man/SD_EVENT_PRIORITY_IMPORTANT.3 \ man/SD_EVENT_PRIORITY_NORMAL.3 \ + man/SD_EVENT_RUNNING.3 \ + man/SD_LISTEN_FDS_START.3 \ + man/sd_bus_creds_get_audit_login_uid.3 \ + man/sd_bus_creds_get_audit_session_id.3 \ + man/sd_bus_creds_get_augmented_mask.3 \ + man/sd_bus_creds_get_cgroup.3 \ + man/sd_bus_creds_get_cmdline.3 \ + man/sd_bus_creds_get_comm.3 \ + man/sd_bus_creds_get_description.3 \ + man/sd_bus_creds_get_egid.3 \ + man/sd_bus_creds_get_euid.3 \ + man/sd_bus_creds_get_exe.3 \ + man/sd_bus_creds_get_fsgid.3 \ + man/sd_bus_creds_get_fsuid.3 \ + man/sd_bus_creds_get_gid.3 \ + man/sd_bus_creds_get_mask.3 \ + man/sd_bus_creds_get_owner_uid.3 \ + man/sd_bus_creds_get_ppid.3 \ + man/sd_bus_creds_get_selinux_context.3 \ + man/sd_bus_creds_get_session.3 \ + man/sd_bus_creds_get_sgid.3 \ + man/sd_bus_creds_get_slice.3 \ + man/sd_bus_creds_get_suid.3 \ + man/sd_bus_creds_get_supplementary_gids.3 \ + man/sd_bus_creds_get_tid.3 \ + man/sd_bus_creds_get_tid_comm.3 \ + man/sd_bus_creds_get_tty.3 \ + man/sd_bus_creds_get_uid.3 \ + man/sd_bus_creds_get_unique_name.3 \ + man/sd_bus_creds_get_unit.3 \ + man/sd_bus_creds_get_user_slice.3 \ + man/sd_bus_creds_get_user_unit.3 \ + man/sd_bus_creds_get_well_known_names.3 \ + man/sd_bus_creds_has_bounding_cap.3 \ + man/sd_bus_creds_has_effective_cap.3 \ + man/sd_bus_creds_has_inheritable_cap.3 \ + man/sd_bus_creds_has_permitted_cap.3 \ + man/sd_bus_creds_ref.3 \ + man/sd_bus_creds_unref.3 \ + man/sd_bus_creds_unrefp.3 \ + man/sd_bus_default_system.3 \ + man/sd_bus_default_user.3 \ + man/sd_bus_error_copy.3 \ + man/sd_bus_error_free.3 \ + man/sd_bus_error_get_errno.3 \ + man/sd_bus_error_has_name.3 \ + man/sd_bus_error_is_set.3 \ + man/sd_bus_error_map.3 \ + man/sd_bus_error_set.3 \ + man/sd_bus_error_set_const.3 \ + man/sd_bus_error_set_errno.3 \ + man/sd_bus_error_set_errnof.3 \ + man/sd_bus_error_set_errnofv.3 \ + man/sd_bus_error_setf.3 \ + man/sd_bus_message_append_array_iovec.3 \ + man/sd_bus_message_append_array_memfd.3 \ + man/sd_bus_message_append_array_space.3 \ + man/sd_bus_negotiate_creds.3 \ + man/sd_bus_negotiate_timestamp.3 \ + man/sd_bus_open.3 \ + man/sd_bus_open_system.3 \ + man/sd_bus_open_system_machine.3 \ + man/sd_bus_open_system_remote.3 \ + man/sd_bus_open_user.3 \ + man/sd_bus_ref.3 \ + man/sd_bus_release_name.3 \ + man/sd_bus_track_add_sender.3 \ + man/sd_bus_track_contains.3 \ + man/sd_bus_track_count.3 \ + man/sd_bus_track_count_name.3 \ + man/sd_bus_track_count_sender.3 \ + man/sd_bus_track_first.3 \ + man/sd_bus_track_get_bus.3 \ + man/sd_bus_track_get_recursive.3 \ + man/sd_bus_track_get_userdata.3 \ + man/sd_bus_track_next.3 \ + man/sd_bus_track_ref.3 \ + man/sd_bus_track_remove_name.3 \ + man/sd_bus_track_remove_sender.3 \ + man/sd_bus_track_set_recursive.3 \ + man/sd_bus_track_set_userdata.3 \ + man/sd_bus_track_unref.3 \ + man/sd_bus_track_unrefp.3 \ + man/sd_bus_unref.3 \ + man/sd_bus_unrefp.3 \ + man/sd_event.3 \ + man/sd_event_add_exit.3 \ + man/sd_event_add_post.3 \ + man/sd_event_child_handler_t.3 \ + man/sd_event_default.3 \ + man/sd_event_dispatch.3 \ man/sd_event_get_exit_code.3 \ + man/sd_event_get_iteration.3 \ + man/sd_event_get_state.3 \ + man/sd_event_get_tid.3 \ man/sd_event_get_watchdog.3 \ + man/sd_event_handler_t.3 \ man/sd_event_io_handler_t.3 \ + man/sd_event_loop.3 \ + man/sd_event_prepare.3 \ + man/sd_event_ref.3 \ + man/sd_event_signal_handler_t.3 \ man/sd_event_source.3 \ + man/sd_event_source_get_child_pid.3 \ man/sd_event_source_get_description.3 \ man/sd_event_source_get_enabled.3 \ man/sd_event_source_get_io_events.3 \ man/sd_event_source_get_io_fd.3 \ man/sd_event_source_get_io_revents.3 \ man/sd_event_source_get_priority.3 \ + man/sd_event_source_get_signal.3 \ + man/sd_event_source_get_time.3 \ + man/sd_event_source_get_time_accuracy.3 \ + man/sd_event_source_get_time_clock.3 \ man/sd_event_source_get_userdata.3 \ man/sd_event_source_ref.3 \ man/sd_event_source_set_io_events.3 \ man/sd_event_source_set_io_fd.3 \ + man/sd_event_source_set_time.3 \ + man/sd_event_source_set_time_accuracy.3 \ man/sd_event_source_unrefp.3 \ + man/sd_event_time_handler_t.3 \ + man/sd_event_unref.3 \ + man/sd_event_unrefp.3 \ man/sd_id128_from_string.3 \ man/sd_id128_get_boot.3 \ man/sd_id128_get_invocation.3 \ man/sd_id128_get_machine_app_specific.3 \ + man/sd_is_mq.3 \ + man/sd_is_socket.3 \ + man/sd_is_socket_inet.3 \ + man/sd_is_socket_sockaddr.3 \ + man/sd_is_socket_unix.3 \ + man/sd_is_special.3 \ + man/sd_listen_fds_with_names.3 \ man/sd_machine_get_ifindices.3 \ man/sd_notifyf.3 \ man/sd_pid_notify.3 \ man/sd_pid_notify_with_fds.3 \ man/sd_pid_notifyf.3 +man/SD_BUS_ERROR_END.3: man/sd_bus_error_add_map.3 +man/SD_BUS_ERROR_MAKE_CONST.3: man/sd_bus_error.3 +man/SD_BUS_ERROR_MAP.3: man/sd_bus_error_add_map.3 +man/SD_BUS_ERROR_NULL.3: man/sd_bus_error.3 +man/SD_EVENT_ARMED.3: man/sd_event_wait.3 +man/SD_EVENT_EXITING.3: man/sd_event_wait.3 +man/SD_EVENT_FINISHED.3: man/sd_event_wait.3 +man/SD_EVENT_INITIAL.3: man/sd_event_wait.3 man/SD_EVENT_OFF.3: man/sd_event_source_set_enabled.3 man/SD_EVENT_ON.3: man/sd_event_source_set_enabled.3 man/SD_EVENT_ONESHOT.3: man/sd_event_source_set_enabled.3 +man/SD_EVENT_PENDING.3: man/sd_event_wait.3 +man/SD_EVENT_PREPARING.3: man/sd_event_wait.3 man/SD_EVENT_PRIORITY_IDLE.3: man/sd_event_source_set_priority.3 man/SD_EVENT_PRIORITY_IMPORTANT.3: man/sd_event_source_set_priority.3 man/SD_EVENT_PRIORITY_NORMAL.3: man/sd_event_source_set_priority.3 +man/SD_EVENT_RUNNING.3: man/sd_event_wait.3 +man/SD_LISTEN_FDS_START.3: man/sd_listen_fds.3 +man/sd_bus_creds_get_audit_login_uid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_audit_session_id.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_augmented_mask.3: man/sd_bus_creds_new_from_pid.3 +man/sd_bus_creds_get_cgroup.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_cmdline.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_comm.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_description.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_egid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_euid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_exe.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_fsgid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_fsuid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_gid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_mask.3: man/sd_bus_creds_new_from_pid.3 +man/sd_bus_creds_get_owner_uid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_ppid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_selinux_context.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_session.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_sgid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_slice.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_suid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_supplementary_gids.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_tid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_tid_comm.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_tty.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_uid.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_unique_name.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_unit.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_user_slice.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_user_unit.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_well_known_names.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_has_bounding_cap.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_has_effective_cap.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_has_inheritable_cap.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_has_permitted_cap.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_ref.3: man/sd_bus_creds_new_from_pid.3 +man/sd_bus_creds_unref.3: man/sd_bus_creds_new_from_pid.3 +man/sd_bus_creds_unrefp.3: man/sd_bus_creds_new_from_pid.3 +man/sd_bus_default_system.3: man/sd_bus_default.3 +man/sd_bus_default_user.3: man/sd_bus_default.3 +man/sd_bus_error_copy.3: man/sd_bus_error.3 +man/sd_bus_error_free.3: man/sd_bus_error.3 +man/sd_bus_error_get_errno.3: man/sd_bus_error.3 +man/sd_bus_error_has_name.3: man/sd_bus_error.3 +man/sd_bus_error_is_set.3: man/sd_bus_error.3 +man/sd_bus_error_map.3: man/sd_bus_error_add_map.3 +man/sd_bus_error_set.3: man/sd_bus_error.3 +man/sd_bus_error_set_const.3: man/sd_bus_error.3 +man/sd_bus_error_set_errno.3: man/sd_bus_error.3 +man/sd_bus_error_set_errnof.3: man/sd_bus_error.3 +man/sd_bus_error_set_errnofv.3: man/sd_bus_error.3 +man/sd_bus_error_setf.3: man/sd_bus_error.3 +man/sd_bus_message_append_array_iovec.3: man/sd_bus_message_append_array.3 +man/sd_bus_message_append_array_memfd.3: man/sd_bus_message_append_array.3 +man/sd_bus_message_append_array_space.3: man/sd_bus_message_append_array.3 +man/sd_bus_negotiate_creds.3: man/sd_bus_negotiate_fds.3 +man/sd_bus_negotiate_timestamp.3: man/sd_bus_negotiate_fds.3 +man/sd_bus_open.3: man/sd_bus_default.3 +man/sd_bus_open_system.3: man/sd_bus_default.3 +man/sd_bus_open_system_machine.3: man/sd_bus_default.3 +man/sd_bus_open_system_remote.3: man/sd_bus_default.3 +man/sd_bus_open_user.3: man/sd_bus_default.3 +man/sd_bus_ref.3: man/sd_bus_new.3 +man/sd_bus_release_name.3: man/sd_bus_request_name.3 +man/sd_bus_track_add_sender.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_contains.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_count.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_count_name.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_count_sender.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_first.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_get_bus.3: man/sd_bus_track_new.3 +man/sd_bus_track_get_recursive.3: man/sd_bus_track_new.3 +man/sd_bus_track_get_userdata.3: man/sd_bus_track_new.3 +man/sd_bus_track_next.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_ref.3: man/sd_bus_track_new.3 +man/sd_bus_track_remove_name.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_remove_sender.3: man/sd_bus_track_add_name.3 +man/sd_bus_track_set_recursive.3: man/sd_bus_track_new.3 +man/sd_bus_track_set_userdata.3: man/sd_bus_track_new.3 +man/sd_bus_track_unref.3: man/sd_bus_track_new.3 +man/sd_bus_track_unrefp.3: man/sd_bus_track_new.3 +man/sd_bus_unref.3: man/sd_bus_new.3 +man/sd_bus_unrefp.3: man/sd_bus_new.3 +man/sd_event.3: man/sd_event_new.3 +man/sd_event_add_exit.3: man/sd_event_add_defer.3 +man/sd_event_add_post.3: man/sd_event_add_defer.3 +man/sd_event_child_handler_t.3: man/sd_event_add_child.3 +man/sd_event_default.3: man/sd_event_new.3 +man/sd_event_dispatch.3: man/sd_event_wait.3 man/sd_event_get_exit_code.3: man/sd_event_exit.3 +man/sd_event_get_iteration.3: man/sd_event_wait.3 +man/sd_event_get_state.3: man/sd_event_wait.3 +man/sd_event_get_tid.3: man/sd_event_new.3 man/sd_event_get_watchdog.3: man/sd_event_set_watchdog.3 +man/sd_event_handler_t.3: man/sd_event_add_defer.3 man/sd_event_io_handler_t.3: man/sd_event_add_io.3 +man/sd_event_loop.3: man/sd_event_run.3 +man/sd_event_prepare.3: man/sd_event_wait.3 +man/sd_event_ref.3: man/sd_event_new.3 +man/sd_event_signal_handler_t.3: man/sd_event_add_signal.3 man/sd_event_source.3: man/sd_event_add_io.3 +man/sd_event_source_get_child_pid.3: man/sd_event_add_child.3 man/sd_event_source_get_description.3: man/sd_event_source_set_description.3 man/sd_event_source_get_enabled.3: man/sd_event_source_set_enabled.3 man/sd_event_source_get_io_events.3: man/sd_event_add_io.3 man/sd_event_source_get_io_fd.3: man/sd_event_add_io.3 man/sd_event_source_get_io_revents.3: man/sd_event_add_io.3 man/sd_event_source_get_priority.3: man/sd_event_source_set_priority.3 +man/sd_event_source_get_signal.3: man/sd_event_add_signal.3 +man/sd_event_source_get_time.3: man/sd_event_add_time.3 +man/sd_event_source_get_time_accuracy.3: man/sd_event_add_time.3 +man/sd_event_source_get_time_clock.3: man/sd_event_add_time.3 man/sd_event_source_get_userdata.3: man/sd_event_source_set_userdata.3 man/sd_event_source_ref.3: man/sd_event_source_unref.3 man/sd_event_source_set_io_events.3: man/sd_event_add_io.3 man/sd_event_source_set_io_fd.3: man/sd_event_add_io.3 +man/sd_event_source_set_time.3: man/sd_event_add_time.3 +man/sd_event_source_set_time_accuracy.3: man/sd_event_add_time.3 man/sd_event_source_unrefp.3: man/sd_event_source_unref.3 +man/sd_event_time_handler_t.3: man/sd_event_add_time.3 +man/sd_event_unref.3: man/sd_event_new.3 +man/sd_event_unrefp.3: man/sd_event_new.3 man/sd_id128_from_string.3: man/sd_id128_to_string.3 man/sd_id128_get_boot.3: man/sd_id128_get_machine.3 man/sd_id128_get_invocation.3: man/sd_id128_get_machine.3 man/sd_id128_get_machine_app_specific.3: man/sd_id128_get_machine.3 +man/sd_is_mq.3: man/sd_is_fifo.3 +man/sd_is_socket.3: man/sd_is_fifo.3 +man/sd_is_socket_inet.3: man/sd_is_fifo.3 +man/sd_is_socket_sockaddr.3: man/sd_is_fifo.3 +man/sd_is_socket_unix.3: man/sd_is_fifo.3 +man/sd_is_special.3: man/sd_is_fifo.3 +man/sd_listen_fds_with_names.3: man/sd_listen_fds.3 man/sd_machine_get_ifindices.3: man/sd_machine_get_class.3 man/sd_notifyf.3: man/sd_notify.3 man/sd_pid_notify.3: man/sd_notify.3 man/sd_pid_notify_with_fds.3: man/sd_notify.3 man/sd_pid_notifyf.3: man/sd_notify.3 +man/SD_BUS_ERROR_END.html: man/sd_bus_error_add_map.html + $(html-alias) + +man/SD_BUS_ERROR_MAKE_CONST.html: man/sd_bus_error.html + $(html-alias) + +man/SD_BUS_ERROR_MAP.html: man/sd_bus_error_add_map.html + $(html-alias) + +man/SD_BUS_ERROR_NULL.html: man/sd_bus_error.html + $(html-alias) + +man/SD_EVENT_ARMED.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_EXITING.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_FINISHED.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_INITIAL.html: man/sd_event_wait.html + $(html-alias) + man/SD_EVENT_OFF.html: man/sd_event_source_set_enabled.html $(html-alias) @@ -101,6 +405,12 @@ man/SD_EVENT_ON.html: man/sd_event_source_set_enabled.html man/SD_EVENT_ONESHOT.html: man/sd_event_source_set_enabled.html $(html-alias) +man/SD_EVENT_PENDING.html: man/sd_event_wait.html + $(html-alias) + +man/SD_EVENT_PREPARING.html: man/sd_event_wait.html + $(html-alias) + man/SD_EVENT_PRIORITY_IDLE.html: man/sd_event_source_set_priority.html $(html-alias) @@ -110,18 +420,318 @@ man/SD_EVENT_PRIORITY_IMPORTANT.html: man/sd_event_source_set_priority.html man/SD_EVENT_PRIORITY_NORMAL.html: man/sd_event_source_set_priority.html $(html-alias) +man/SD_EVENT_RUNNING.html: man/sd_event_wait.html + $(html-alias) + +man/SD_LISTEN_FDS_START.html: man/sd_listen_fds.html + $(html-alias) + +man/sd_bus_creds_get_audit_login_uid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_audit_session_id.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_augmented_mask.html: man/sd_bus_creds_new_from_pid.html + $(html-alias) + +man/sd_bus_creds_get_cgroup.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_cmdline.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_comm.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_description.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_egid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_euid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_exe.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_fsgid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_fsuid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_gid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_mask.html: man/sd_bus_creds_new_from_pid.html + $(html-alias) + +man/sd_bus_creds_get_owner_uid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_ppid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_selinux_context.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_session.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_sgid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_slice.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_suid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_supplementary_gids.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_tid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_tid_comm.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_tty.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_uid.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_unique_name.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_unit.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_user_slice.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_user_unit.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_get_well_known_names.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_has_bounding_cap.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_has_effective_cap.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_has_inheritable_cap.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_has_permitted_cap.html: man/sd_bus_creds_get_pid.html + $(html-alias) + +man/sd_bus_creds_ref.html: man/sd_bus_creds_new_from_pid.html + $(html-alias) + +man/sd_bus_creds_unref.html: man/sd_bus_creds_new_from_pid.html + $(html-alias) + +man/sd_bus_creds_unrefp.html: man/sd_bus_creds_new_from_pid.html + $(html-alias) + +man/sd_bus_default_system.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_default_user.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_error_copy.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_free.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_get_errno.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_has_name.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_is_set.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_map.html: man/sd_bus_error_add_map.html + $(html-alias) + +man/sd_bus_error_set.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_set_const.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_set_errno.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_set_errnof.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_set_errnofv.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_setf.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_message_append_array_iovec.html: man/sd_bus_message_append_array.html + $(html-alias) + +man/sd_bus_message_append_array_memfd.html: man/sd_bus_message_append_array.html + $(html-alias) + +man/sd_bus_message_append_array_space.html: man/sd_bus_message_append_array.html + $(html-alias) + +man/sd_bus_negotiate_creds.html: man/sd_bus_negotiate_fds.html + $(html-alias) + +man/sd_bus_negotiate_timestamp.html: man/sd_bus_negotiate_fds.html + $(html-alias) + +man/sd_bus_open.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_open_system.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_open_system_machine.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_open_system_remote.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_open_user.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_ref.html: man/sd_bus_new.html + $(html-alias) + +man/sd_bus_release_name.html: man/sd_bus_request_name.html + $(html-alias) + +man/sd_bus_track_add_sender.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_contains.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_count.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_count_name.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_count_sender.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_first.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_get_bus.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_get_recursive.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_get_userdata.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_next.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_ref.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_remove_name.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_remove_sender.html: man/sd_bus_track_add_name.html + $(html-alias) + +man/sd_bus_track_set_recursive.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_set_userdata.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_unref.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_track_unrefp.html: man/sd_bus_track_new.html + $(html-alias) + +man/sd_bus_unref.html: man/sd_bus_new.html + $(html-alias) + +man/sd_bus_unrefp.html: man/sd_bus_new.html + $(html-alias) + +man/sd_event.html: man/sd_event_new.html + $(html-alias) + +man/sd_event_add_exit.html: man/sd_event_add_defer.html + $(html-alias) + +man/sd_event_add_post.html: man/sd_event_add_defer.html + $(html-alias) + +man/sd_event_child_handler_t.html: man/sd_event_add_child.html + $(html-alias) + +man/sd_event_default.html: man/sd_event_new.html + $(html-alias) + +man/sd_event_dispatch.html: man/sd_event_wait.html + $(html-alias) + man/sd_event_get_exit_code.html: man/sd_event_exit.html $(html-alias) +man/sd_event_get_iteration.html: man/sd_event_wait.html + $(html-alias) + +man/sd_event_get_state.html: man/sd_event_wait.html + $(html-alias) + +man/sd_event_get_tid.html: man/sd_event_new.html + $(html-alias) + man/sd_event_get_watchdog.html: man/sd_event_set_watchdog.html $(html-alias) +man/sd_event_handler_t.html: man/sd_event_add_defer.html + $(html-alias) + man/sd_event_io_handler_t.html: man/sd_event_add_io.html $(html-alias) +man/sd_event_loop.html: man/sd_event_run.html + $(html-alias) + +man/sd_event_prepare.html: man/sd_event_wait.html + $(html-alias) + +man/sd_event_ref.html: man/sd_event_new.html + $(html-alias) + +man/sd_event_signal_handler_t.html: man/sd_event_add_signal.html + $(html-alias) + man/sd_event_source.html: man/sd_event_add_io.html $(html-alias) +man/sd_event_source_get_child_pid.html: man/sd_event_add_child.html + $(html-alias) + man/sd_event_source_get_description.html: man/sd_event_source_set_description.html $(html-alias) @@ -140,6 +750,18 @@ man/sd_event_source_get_io_revents.html: man/sd_event_add_io.html man/sd_event_source_get_priority.html: man/sd_event_source_set_priority.html $(html-alias) +man/sd_event_source_get_signal.html: man/sd_event_add_signal.html + $(html-alias) + +man/sd_event_source_get_time.html: man/sd_event_add_time.html + $(html-alias) + +man/sd_event_source_get_time_accuracy.html: man/sd_event_add_time.html + $(html-alias) + +man/sd_event_source_get_time_clock.html: man/sd_event_add_time.html + $(html-alias) + man/sd_event_source_get_userdata.html: man/sd_event_source_set_userdata.html $(html-alias) @@ -152,9 +774,24 @@ man/sd_event_source_set_io_events.html: man/sd_event_add_io.html man/sd_event_source_set_io_fd.html: man/sd_event_add_io.html $(html-alias) +man/sd_event_source_set_time.html: man/sd_event_add_time.html + $(html-alias) + +man/sd_event_source_set_time_accuracy.html: man/sd_event_add_time.html + $(html-alias) + man/sd_event_source_unrefp.html: man/sd_event_source_unref.html $(html-alias) +man/sd_event_time_handler_t.html: man/sd_event_add_time.html + $(html-alias) + +man/sd_event_unref.html: man/sd_event_new.html + $(html-alias) + +man/sd_event_unrefp.html: man/sd_event_new.html + $(html-alias) + man/sd_id128_from_string.html: man/sd_id128_to_string.html $(html-alias) @@ -167,6 +804,27 @@ man/sd_id128_get_invocation.html: man/sd_id128_get_machine.html man/sd_id128_get_machine_app_specific.html: man/sd_id128_get_machine.html $(html-alias) +man/sd_is_mq.html: man/sd_is_fifo.html + $(html-alias) + +man/sd_is_socket.html: man/sd_is_fifo.html + $(html-alias) + +man/sd_is_socket_inet.html: man/sd_is_fifo.html + $(html-alias) + +man/sd_is_socket_sockaddr.html: man/sd_is_fifo.html + $(html-alias) + +man/sd_is_socket_unix.html: man/sd_is_fifo.html + $(html-alias) + +man/sd_is_special.html: man/sd_is_fifo.html + $(html-alias) + +man/sd_listen_fds_with_names.html: man/sd_listen_fds.html + $(html-alias) + man/sd_machine_get_ifindices.html: man/sd_machine_get_class.html $(html-alias) @@ -187,12 +845,37 @@ if HAVE_PAM MANPAGES += \ man/pam_elogind.8 \ man/sd_get_seats.3 \ + man/sd_login_monitor_new.3 \ + man/sd_pid_get_session.3 \ man/sd_seat_get_active.3 \ - man/sd_session_is_active.3 + man/sd_session_is_active.3 \ + man/sd_uid_get_state.3 MANPAGES_ALIAS += \ man/sd_get_machine_names.3 \ man/sd_get_sessions.3 \ man/sd_get_uids.3 \ + man/sd_login_monitor.3 \ + man/sd_login_monitor_flush.3 \ + man/sd_login_monitor_get_events.3 \ + man/sd_login_monitor_get_fd.3 \ + man/sd_login_monitor_get_timeout.3 \ + man/sd_login_monitor_unref.3 \ + man/sd_login_monitor_unrefp.3 \ + man/sd_peer_get_cgroup.3 \ + man/sd_peer_get_machine_name.3 \ + man/sd_peer_get_owner_uid.3 \ + man/sd_peer_get_session.3 \ + man/sd_peer_get_slice.3 \ + man/sd_peer_get_unit.3 \ + man/sd_peer_get_user_slice.3 \ + man/sd_peer_get_user_unit.3 \ + man/sd_pid_get_cgroup.3 \ + man/sd_pid_get_machine_name.3 \ + man/sd_pid_get_owner_uid.3 \ + man/sd_pid_get_slice.3 \ + man/sd_pid_get_unit.3 \ + man/sd_pid_get_user_slice.3 \ + man/sd_pid_get_user_unit.3 \ man/sd_seat_can_graphical.3 \ man/sd_seat_can_multi_session.3 \ man/sd_seat_can_tty.3 \ @@ -209,10 +892,36 @@ MANPAGES_ALIAS += \ man/sd_session_get_type.3 \ man/sd_session_get_uid.3 \ man/sd_session_get_vt.3 \ - man/sd_session_is_remote.3 + man/sd_session_is_remote.3 \ + man/sd_uid_get_display.3 \ + man/sd_uid_get_seats.3 \ + man/sd_uid_get_sessions.3 \ + man/sd_uid_is_on_seat.3 man/sd_get_machine_names.3: man/sd_get_seats.3 man/sd_get_sessions.3: man/sd_get_seats.3 man/sd_get_uids.3: man/sd_get_seats.3 +man/sd_login_monitor.3: man/sd_login_monitor_new.3 +man/sd_login_monitor_flush.3: man/sd_login_monitor_new.3 +man/sd_login_monitor_get_events.3: man/sd_login_monitor_new.3 +man/sd_login_monitor_get_fd.3: man/sd_login_monitor_new.3 +man/sd_login_monitor_get_timeout.3: man/sd_login_monitor_new.3 +man/sd_login_monitor_unref.3: man/sd_login_monitor_new.3 +man/sd_login_monitor_unrefp.3: man/sd_login_monitor_new.3 +man/sd_peer_get_cgroup.3: man/sd_pid_get_session.3 +man/sd_peer_get_machine_name.3: man/sd_pid_get_session.3 +man/sd_peer_get_owner_uid.3: man/sd_pid_get_session.3 +man/sd_peer_get_session.3: man/sd_pid_get_session.3 +man/sd_peer_get_slice.3: man/sd_pid_get_session.3 +man/sd_peer_get_unit.3: man/sd_pid_get_session.3 +man/sd_peer_get_user_slice.3: man/sd_pid_get_session.3 +man/sd_peer_get_user_unit.3: man/sd_pid_get_session.3 +man/sd_pid_get_cgroup.3: man/sd_pid_get_session.3 +man/sd_pid_get_machine_name.3: man/sd_pid_get_session.3 +man/sd_pid_get_owner_uid.3: man/sd_pid_get_session.3 +man/sd_pid_get_slice.3: man/sd_pid_get_session.3 +man/sd_pid_get_unit.3: man/sd_pid_get_session.3 +man/sd_pid_get_user_slice.3: man/sd_pid_get_session.3 +man/sd_pid_get_user_unit.3: man/sd_pid_get_session.3 man/sd_seat_can_graphical.3: man/sd_seat_get_active.3 man/sd_seat_can_multi_session.3: man/sd_seat_get_active.3 man/sd_seat_can_tty.3: man/sd_seat_get_active.3 @@ -230,6 +939,10 @@ man/sd_session_get_type.3: man/sd_session_is_active.3 man/sd_session_get_uid.3: man/sd_session_is_active.3 man/sd_session_get_vt.3: man/sd_session_is_active.3 man/sd_session_is_remote.3: man/sd_session_is_active.3 +man/sd_uid_get_display.3: man/sd_uid_get_state.3 +man/sd_uid_get_seats.3: man/sd_uid_get_state.3 +man/sd_uid_get_sessions.3: man/sd_uid_get_state.3 +man/sd_uid_is_on_seat.3: man/sd_uid_get_state.3 man/sd_get_machine_names.html: man/sd_get_seats.html $(html-alias) @@ -239,6 +952,72 @@ man/sd_get_sessions.html: man/sd_get_seats.html man/sd_get_uids.html: man/sd_get_seats.html $(html-alias) +man/sd_login_monitor.html: man/sd_login_monitor_new.html + $(html-alias) + +man/sd_login_monitor_flush.html: man/sd_login_monitor_new.html + $(html-alias) + +man/sd_login_monitor_get_events.html: man/sd_login_monitor_new.html + $(html-alias) + +man/sd_login_monitor_get_fd.html: man/sd_login_monitor_new.html + $(html-alias) + +man/sd_login_monitor_get_timeout.html: man/sd_login_monitor_new.html + $(html-alias) + +man/sd_login_monitor_unref.html: man/sd_login_monitor_new.html + $(html-alias) + +man/sd_login_monitor_unrefp.html: man/sd_login_monitor_new.html + $(html-alias) + +man/sd_peer_get_cgroup.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_peer_get_machine_name.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_peer_get_owner_uid.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_peer_get_session.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_peer_get_slice.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_peer_get_unit.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_peer_get_user_slice.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_peer_get_user_unit.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_pid_get_cgroup.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_pid_get_machine_name.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_pid_get_owner_uid.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_pid_get_slice.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_pid_get_unit.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_pid_get_user_slice.html: man/sd_pid_get_session.html + $(html-alias) + +man/sd_pid_get_user_unit.html: man/sd_pid_get_session.html + $(html-alias) + man/sd_seat_can_graphical.html: man/sd_seat_get_active.html $(html-alias) @@ -290,6 +1069,18 @@ man/sd_session_get_vt.html: man/sd_session_is_active.html man/sd_session_is_remote.html: man/sd_session_is_active.html $(html-alias) +man/sd_uid_get_display.html: man/sd_uid_get_state.html + $(html-alias) + +man/sd_uid_get_seats.html: man/sd_uid_get_state.html + $(html-alias) + +man/sd_uid_get_sessions.html: man/sd_uid_get_state.html + $(html-alias) + +man/sd_uid_is_on_seat.html: man/sd_uid_get_state.html + $(html-alias) + endif if HAVE_PYTHON @@ -311,11 +1102,36 @@ EXTRA_DIST += \ man/loginctl.xml \ man/logind.conf.xml \ man/pam_elogind.xml \ + man/sd-bus.xml \ man/sd-event.xml \ man/sd_booted.xml \ + man/sd_bus_add_match.xml \ + man/sd_bus_creds_get_pid.xml \ + man/sd_bus_creds_new_from_pid.xml \ + man/sd_bus_default.xml \ + man/sd_bus_error.xml \ + man/sd_bus_error_add_map.xml \ + man/sd_bus_get_fd.xml \ + man/sd_bus_message_append.xml \ + man/sd_bus_message_append_array.xml \ + man/sd_bus_message_append_basic.xml \ + man/sd_bus_message_append_strv.xml \ + man/sd_bus_message_read_basic.xml \ + man/sd_bus_negotiate_fds.xml \ + man/sd_bus_new.xml \ + man/sd_bus_process.xml \ + man/sd_bus_request_name.xml \ + man/sd_bus_track_add_name.xml \ + man/sd_bus_track_new.xml \ + man/sd_event_add_child.xml \ + man/sd_event_add_defer.xml \ man/sd_event_add_io.xml \ + man/sd_event_add_signal.xml \ + man/sd_event_add_time.xml \ man/sd_event_exit.xml \ + man/sd_event_new.xml \ man/sd_event_now.xml \ + man/sd_event_run.xml \ man/sd_event_set_watchdog.xml \ man/sd_event_source_get_event.xml \ man/sd_event_source_get_pending.xml \ @@ -325,14 +1141,20 @@ EXTRA_DIST += \ man/sd_event_source_set_priority.xml \ man/sd_event_source_set_userdata.xml \ man/sd_event_source_unref.xml \ + man/sd_event_wait.xml \ man/sd_get_seats.xml \ man/sd_id128_get_machine.xml \ man/sd_id128_randomize.xml \ man/sd_id128_to_string.xml \ + man/sd_is_fifo.xml \ + man/sd_listen_fds.xml \ + man/sd_login_monitor_new.xml \ man/sd_machine_get_class.xml \ man/sd_notify.xml \ + man/sd_pid_get_session.xml \ man/sd_seat_get_active.xml \ man/sd_session_is_active.xml \ + man/sd_uid_get_state.xml \ man/sd_watchdog_enabled.xml \ man/standard-conf.xml \ man/standard-options.xml \ diff --git a/Makefile.am b/Makefile.am index aae170ce4..7e47d3926 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1519,7 +1519,7 @@ valgrind-tests: $(TESTS) exported-%: % $(AM_V_GEN)$(NM) -g --defined-only $(builddir)/.libs/$(<:.la=.so) 2>&1 /dev/null | grep " T " | cut -d" " -f3 > $@ -exported: $(addprefix exported-, $(lib_LTLIBRARIES)) +exported: $(addprefix exported-, $(rootlib_LTLIBRARIES)) $(AM_V_GEN)cat $^ > $@ .PHONY: check-api-docs diff --git a/man/sd-bus.xml b/man/sd-bus.xml new file mode 100644 index 000000000..0ecabab11 --- /dev/null +++ b/man/sd-bus.xml @@ -0,0 +1,114 @@ + + + + + + + + + sd-bus + systemd + + + + Documentation + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd-bus + 3 + + + + sd-bus + A lightweight D-Bus IPC client library + + + + + #include <systemd/sd-bus.h> + + + + pkg-config --cflags --libs libelogind + + + + + + Description + + sd-bus.h provides an implementation of a D-Bus IPC client. See + + for more information about D-Bus IPC. + + + See + sd-bus-errors3, + sd_bus_creds_get_pid3, + sd_bus_creds_new_from_pid3, + sd_bus_default3, + sd_bus_error3, + sd_bus_error_add_map3, + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3, + sd_bus_message_append3, + sd_bus_message_append_array3, + sd_bus_message_append_basic3, + sd_bus_message_append_string_memfd3, + sd_bus_message_append_strv3, + sd_bus_message_can_send3, + sd_bus_message_get_cookie3, + sd_bus_message_get_monotonic_usec3, + sd_bus_negotiate_fds3, + sd_bus_new3, + sd_bus_path_encode3, + sd_bus_request_name3, + sd_bus_send3, + sd_bus_set_address3, + sd_bus_set_allow_interactive_authorization3 + sd_bus_set_description3, + sd_bus_set_prepare3, + sd_bus_start3, + sd_bus_track_add_name3, + sd_bus_track_new3, + for more information about the functions available. + + + + + + See Also + + systemd1, + sd-event3, + busctl1, + dbus-daemon1, + dbus-send1 + + + + diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml new file mode 100644 index 000000000..8bcf7164a --- /dev/null +++ b/man/sd_bus_add_match.xml @@ -0,0 +1,119 @@ + + + + + + + + + sd_bus_add_match + systemd + + + + Julian + Orth + ju.orth@gmail.com + + + + + + sd_bus_add_match + 3 + + + + sd_bus_add_match + + Add a match rule for message dispatching + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_add_match + sd_bus *bus + sd_bus_slot **slot + const char *match + sd_bus_message_handler_t callback + void *userdata + + + + typedef int (*sd_bus_message_handler_t) + sd_bus_message *m + void *userdata + sd_bus_error *ret_error + + + + + + Description + + + sd_bus_add_match() adds a match rule used to dispatch + incoming messages. The syntax of the rule passed in + match is described in the + D-Bus Specification. + + + + The message m passed to the callback is only + borrowed, that is, the callback should not call + sd_bus_message_unref3 + on it. If the callback wants to hold on to the message beyond the lifetime + of the callback, it needs to call + sd_bus_message_ref3 + to create a new reference. + + + + If an error occurs during the callback invocation, the callback should + return a negative error number. If it wants other callbacks that match the + same rule to be called, it should return 0. Otherwise it should return a + positive integer. + + + + + Return Value + + + On success, sd_bus_add_match() returns 0 or a + positive integer. On failure, it returns a negative errno-style error + code. + + + + + See Also + + + systemd1, + sd-bus3, + + + + diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml new file mode 100644 index 000000000..29cb9bd32 --- /dev/null +++ b/man/sd_bus_creds_get_pid.xml @@ -0,0 +1,566 @@ + + + + + + + + + sd_bus_creds_get_pid + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_creds_get_pid + 3 + + + + sd_bus_creds_get_pid + sd_bus_creds_get_ppid + sd_bus_creds_get_tid + sd_bus_creds_get_uid + sd_bus_creds_get_euid + sd_bus_creds_get_suid + sd_bus_creds_get_fsuid + sd_bus_creds_get_gid + sd_bus_creds_get_egid + sd_bus_creds_get_sgid + sd_bus_creds_get_fsgid + sd_bus_creds_get_supplementary_gids + sd_bus_creds_get_comm + sd_bus_creds_get_tid_comm + sd_bus_creds_get_exe + sd_bus_creds_get_cmdline + sd_bus_creds_get_cgroup + sd_bus_creds_get_unit + sd_bus_creds_get_slice + sd_bus_creds_get_user_unit + sd_bus_creds_get_user_slice + sd_bus_creds_get_session + sd_bus_creds_get_owner_uid + sd_bus_creds_has_effective_cap + sd_bus_creds_has_permitted_cap + sd_bus_creds_has_inheritable_cap + sd_bus_creds_has_bounding_cap + sd_bus_creds_get_selinux_context + sd_bus_creds_get_audit_session_id + sd_bus_creds_get_audit_login_uid + sd_bus_creds_get_tty + sd_bus_creds_get_unique_name + sd_bus_creds_get_well_known_names + sd_bus_creds_get_description + + Retrieve fields from a credentials object + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_creds_get_pid + sd_bus_creds *c + pid_t *pid + + + + int sd_bus_creds_get_ppid + sd_bus_creds *c + pid_t *ppid + + + + int sd_bus_creds_get_tid + sd_bus_creds *c + pid_t *tid + + + + int sd_bus_creds_get_uid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_get_euid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_get_suid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_get_fsuid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_get_gid + sd_bus_creds *c + gid_t *gid + + + + int sd_bus_creds_get_egid + sd_bus_creds *c + gid_t *gid + + + + int sd_bus_creds_get_sgid + sd_bus_creds *c + gid_t *gid + + + + int sd_bus_creds_get_fsgid + sd_bus_creds *c + gid_t *gid + + + + int sd_bus_creds_get_supplementary_gids + sd_bus_creds *c + const gid_t **gids + + + + int sd_bus_creds_get_comm + sd_bus_creds *c + const char **comm + + + + int sd_bus_creds_get_tid_comm + sd_bus_creds *c + const char **comm + + + + int sd_bus_creds_get_exe + sd_bus_creds *c + const char **exe + + + + int sd_bus_creds_get_cmdline + sd_bus_creds *c + char ***cmdline + + + + int sd_bus_creds_get_cgroup + sd_bus_creds *c + const char **cgroup + + + + int sd_bus_creds_get_unit + sd_bus_creds *c + const char **unit + + + + int sd_bus_creds_get_slice + sd_bus_creds *c + const char **slice + + + + int sd_bus_creds_get_user_unit + sd_bus_creds *c + const char **unit + + + + int sd_bus_creds_get_user_slice + sd_bus_creds *c + const char **slice + + + + int sd_bus_creds_get_session + sd_bus_creds *c + const char **slice + + + + int sd_bus_creds_get_owner_uid + sd_bus_creds *c + uid_t *uid + + + + int sd_bus_creds_has_effective_cap + sd_bus_creds *c + int capability + + + + int sd_bus_creds_has_permitted_cap + sd_bus_creds *c + int capability + + + + int sd_bus_creds_has_inheritable_cap + sd_bus_creds *c + int capability + + + + int sd_bus_creds_has_bounding_cap + sd_bus_creds *c + int capability + + + + int sd_bus_creds_get_selinux_context + sd_bus_creds *c + const char **context + + + + int sd_bus_creds_get_audit_session_id + sd_bus_creds *c + uint32_t *sessionid + + + + int sd_bus_creds_get_audit_login_uid + sd_bus_creds *c + uid_t *loginuid + + + + int sd_bus_creds_get_tty + sd_bus_creds *c + const char **tty + + + + int sd_bus_creds_get_unique_name + sd_bus_creds *c + const char **name + + + + int sd_bus_creds_get_well_known_names + sd_bus_creds *c + char ***name + + + + int sd_bus_creds_get_description + sd_bus_creds *c + const char **name + + + + + + + Description + + These functions return credential information from an + sd_bus_creds object. Credential objects may + be created with + sd_bus_creds_new_from_pid3, + in which case they describe the credentials of the process + identified by the specified PID, with + sd_bus_get_name_creds3, + in which case they describe the credentials of a bus peer + identified by the specified bus name, with + sd_bus_get_owner_creds3, + in which case they describe the credentials of the creator of a + bus, or with + sd_bus_message_get_creds3, + in which case they describe the credentials of the sender of the + message. + + Not all credential fields are part of every + sd_bus_creds object. Use + sd_bus_creds_get_mask3 + to determine the mask of fields available. + + sd_bus_creds_get_pid() will retrieve + the PID (process identifier). Similarly, + sd_bus_creds_get_ppid() will retrieve the + parent PID. Note that PID 1 has no parent process, in which case + -ENXIO is returned. + + sd_bus_creds_get_tid() will retrieve the + TID (thread identifier). + + sd_bus_creds_get_uid() will retrieve + the numeric UID (user identifier). Similarly, + sd_bus_creds_get_euid() returns the effective + UID, sd_bus_creds_get_suid() the saved UID + and sd_bus_creds_get_fsuid() the file system + UID. + + sd_bus_creds_get_gid() will retrieve the + numeric GID (group identifier). Similarly, + sd_bus_creds_get_egid() returns the effective + GID, sd_bus_creds_get_sgid() the saved GID + and sd_bus_creds_get_fsgid() the file system + GID. + + sd_bus_creds_get_supplementary_gids() + will retrieve the supplementary GIDs list. + + sd_bus_creds_get_comm() will retrieve the + comm field (truncated name of the executable, as stored in + /proc/pid/comm). + + + sd_bus_creds_get_tid_comm() will retrieve + the comm field of the thread (as stored in + /proc/pid/task/tid/comm). + + + sd_bus_creds_get_exe() will retrieve + the path to the program executable (as stored in the + /proc/pid/exe + link, but with the (deleted) suffix removed). Note + that kernel threads do not have an executable path, in which case + -ENXIO is returned. + + sd_bus_creds_get_cmdline() will + retrieve an array of command line arguments (as stored in + /proc/pid/cmdline). Note + that kernel threads do not have a command line, in which case + -ENXIO is returned. + + sd_bus_creds_get_cgroup() will retrieve + the control group path. See cgroups.txt. + + + sd_bus_creds_get_unit() will retrieve + the systemd unit name (in the system instance of systemd) that the + process is a part of. See + systemd.unit5. For + processes that are not part of a unit, returns -ENXIO. + + + sd_bus_creds_get_user_unit() will + retrieve the systemd unit name (in the user instance of systemd) + that the process is a part of. See + systemd.unit5. For + processes that are not part of a user unit, returns -ENXIO. + + + sd_bus_creds_get_slice() will retrieve + the systemd slice (a unit in the system instance of systemd) that + the process is a part of. See + systemd.slice5. Similarly, + sd_bus_creds_get_user_slice() retrieves the + systemd slice of the process, in the user instance of systemd. + + + sd_bus_creds_get_session() will + retrieve the identifier of the login session that the process is + a part of. See + systemd-logind.service8. For + processes that are not part of a session, returns -ENXIO. + + + sd_bus_creds_get_owner_uid() will + retrieve the numeric UID (user identifier) of the user who owns + the login session that the process is a part of. See + systemd-logind.service8. + For processes that are not part of a session, returns -ENXIO. + + + sd_bus_creds_has_effective_cap() will check whether the capability specified by + capability was set in the effective capabilities mask. A positive return value means that it + was set, zero means that it was not set, and a negative return value indicates an error. See capabilities7 and the + AmbientCapabilities= and CapabilityBoundingSet= settings in + systemd.exec5. + + + sd_bus_creds_has_permitted_cap() is + similar to sd_bus_creds_has_effective_cap(), + but will check the permitted capabilities mask. + + sd_bus_creds_has_inheritable_cap() is + similar to sd_bus_creds_has_effective_cap(), + but will check the inheritable capabilities mask. + + sd_bus_creds_has_bounding_cap() is + similar to sd_bus_creds_has_effective_cap(), + but will check the bounding capabilities mask. + + sd_bus_creds_get_selinux_context() will + retrieve the SELinux security context (label) of the process. + + sd_bus_creds_get_audit_session_id() + will retrieve the audit session identifier of the process. Returns + -ENXIO for processes that are not part of an audit session. + + sd_bus_creds_get_audit_login_uid() will + retrieve the audit user login identifier (the identifier of the + user who is "responsible" for the session). Returns -ENXIO for + processes that are not part of an audit session. + + sd_bus_creds_get_tty() will retrieve + the controlling TTY, without the prefixing "/dev/". Returns -ENXIO + for processes that have no controlling TTY. + + sd_bus_creds_get_unique_name() will + retrieve the D-Bus unique name. See The + D-Bus specification. + + sd_bus_creds_get_well_known_names() will + retrieve the set of D-Bus well-known names. See The + D-Bus specification. + + sd_bus_creds_get_description() will + retrieve a descriptive name of the bus connection of the + peer. This name is useful to discern multiple bus connections by + the same peer, and may be altered by the peer with the + sd_bus_set_description3 + call. + + All functions that take a const + char** parameter will store the answer there as an + address of a NUL-terminated string. It will be valid as long as + c remains valid, and should not be freed or + modified by the caller. + + All functions that take a char*** + parameter will store the answer there as an address of an array + of strings. Each individual string is NUL-terminated, and the + array is NULL-terminated as a whole. It will be valid as long as + c remains valid, and should not be freed or + modified by the caller. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error code. + + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENODATA + + The given field is not available in the + credentials object c. + + + + + -ENXIO + + The given field is not specified for the described + process or peer. This will be returned by + sd_bus_get_unit(), + sd_bus_get_slice(), + sd_bus_get_user_unit(), + sd_bus_get_user_slice(), + sd_bus_get_session(), and + sd_bus_get_owner_uid() if the process is + not part of a systemd system unit, systemd user unit, systemd + slice, or logind session. It will also be returned by + sd_bus_creds_get_exe() and + sd_bus_creds_get_cmdline() for kernel + threads (since these are not started from an executable binary, + nor have a command line), and by + sd_bus_creds_get_audit_session_id() and + sd_bus_creds_get_audit_login_uid() when + the process is not part of an audit session, and + sd_bus_creds_get_tty() if the process has + no controlling TTY. + + + + + + -EINVAL + + Specified pointer parameter is NULL. + + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + sd_bus_creds_get_pid() and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_creds_new_from_pid2, + fork2, + execve2, + credentials7, + free3, + proc5, + systemd.journal-fields7 + + + + diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml new file mode 100644 index 000000000..fe4911c4a --- /dev/null +++ b/man/sd_bus_creds_new_from_pid.xml @@ -0,0 +1,353 @@ + + + + + + + + + sd_bus_creds_new_from_pid + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_creds_new_from_pid + 3 + + + + sd_bus_creds_new_from_pid + sd_bus_creds_get_mask + sd_bus_creds_get_augmented_mask + sd_bus_creds_ref + sd_bus_creds_unref + sd_bus_creds_unrefp + + Retrieve credentials object for the specified PID + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_creds_new_from_pid + pid_t pid + uint64_t creds_mask + sd_bus_creds **ret + + + + uint64_t sd_bus_creds_get_mask + sd_bus_creds *c + + + + uint64_t sd_bus_creds_get_augmented_mask + sd_bus_creds *c + + + + sd_bus_creds *sd_bus_creds_ref + sd_bus_creds *c + + + + sd_bus_creds *sd_bus_creds_unref + sd_bus_creds *c + + + + void sd_bus_creds_unrefp + sd_bus_creds **c + + + + + SD_BUS_CREDS_PID, + SD_BUS_CREDS_PPID, + SD_BUS_CREDS_TID, + SD_BUS_CREDS_UID, + SD_BUS_CREDS_EUID, + SD_BUS_CREDS_SUID, + SD_BUS_CREDS_FSUID, + SD_BUS_CREDS_GID, + SD_BUS_CREDS_EGID, + SD_BUS_CREDS_SGID, + SD_BUS_CREDS_FSGID, + SD_BUS_CREDS_SUPPLEMENTARY_GIDS, + SD_BUS_CREDS_COMM, + SD_BUS_CREDS_TID_COMM, + SD_BUS_CREDS_EXE, + SD_BUS_CREDS_CMDLINE, + SD_BUS_CREDS_CGROUP, + SD_BUS_CREDS_UNIT, + SD_BUS_CREDS_SLICE, + SD_BUS_CREDS_USER_UNIT, + SD_BUS_CREDS_USER_SLICE, + SD_BUS_CREDS_SESSION, + SD_BUS_CREDS_OWNER_UID, + SD_BUS_CREDS_EFFECTIVE_CAPS, + SD_BUS_CREDS_PERMITTED_CAPS, + SD_BUS_CREDS_INHERITABLE_CAPS, + SD_BUS_CREDS_BOUNDING_CAPS, + SD_BUS_CREDS_SELINUX_CONTEXT, + SD_BUS_CREDS_AUDIT_SESSION_ID, + SD_BUS_CREDS_AUDIT_LOGIN_UID, + SD_BUS_CREDS_TTY, + SD_BUS_CREDS_UNIQUE_NAME, + SD_BUS_CREDS_WELL_KNOWN_NAMES, + SD_BUS_CREDS_DESCRIPTION, + SD_BUS_CREDS_AUGMENT, + _SD_BUS_CREDS_ALL + + + + + Description + + sd_bus_creds_new_from_pid() creates a + new credentials object and fills it with information about the + process pid. The pointer to this object + will be stored in the ret pointer. Note that + credential objects may also be created and retrieved via + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3 + and + sd_bus_message_get_creds3. + + The information that will be stored is determined by + creds_mask. It may contain a subset of ORed + constants SD_BUS_CREDS_PID, + SD_BUS_CREDS_PPID, + SD_BUS_CREDS_TID, + SD_BUS_CREDS_UID, + SD_BUS_CREDS_EUID, + SD_BUS_CREDS_SUID, + SD_BUS_CREDS_FSUID, + SD_BUS_CREDS_GID, + SD_BUS_CREDS_EGID, + SD_BUS_CREDS_SGID, + SD_BUS_CREDS_FSGID, + SD_BUS_CREDS_SUPPLEMENTARY_GIDS, + SD_BUS_CREDS_COMM, + SD_BUS_CREDS_TID_COMM, + SD_BUS_CREDS_EXE, + SD_BUS_CREDS_CMDLINE, + SD_BUS_CREDS_CGROUP, + SD_BUS_CREDS_UNIT, + SD_BUS_CREDS_SLICE, + SD_BUS_CREDS_USER_UNIT, + SD_BUS_CREDS_USER_SLICE, + SD_BUS_CREDS_SESSION, + SD_BUS_CREDS_OWNER_UID, + SD_BUS_CREDS_EFFECTIVE_CAPS, + SD_BUS_CREDS_PERMITTED_CAPS, + SD_BUS_CREDS_INHERITABLE_CAPS, + SD_BUS_CREDS_BOUNDING_CAPS, + SD_BUS_CREDS_SELINUX_CONTEXT, + SD_BUS_CREDS_AUDIT_SESSION_ID, + SD_BUS_CREDS_AUDIT_LOGIN_UID, + SD_BUS_CREDS_TTY, + SD_BUS_CREDS_UNIQUE_NAME, + SD_BUS_CREDS_WELL_KNOWN_NAMES, and + SD_BUS_CREDS_DESCRIPTION. Use the special + value _SD_BUS_CREDS_ALL to request all + supported fields. The SD_BUS_CREDS_AUGMENT + constant may not be ORed into the mask for invocations of + sd_bus_creds_new_from_pid(). + + Fields can be retrieved from the credentials object using + sd_bus_creds_get_pid3 + and other functions which correspond directly to the constants + listed above. + + A mask of fields which were actually successfully retrieved + can be retrieved with + sd_bus_creds_get_mask(). If the credentials + object was created with + sd_bus_creds_new_from_pid(), this will be a + subset of fields requested in creds_mask. + + + Similar to sd_bus_creds_get_mask(), the + function sd_bus_creds_get_augmented_mask() + returns a bitmask of field constants. The mask indicates which + credential fields have been retrieved in a non-atomic fashion. For + credential objects created via + sd_bus_creds_new_from_pid(), this mask will be + identical to the mask returned by + sd_bus_creds_get_mask(). However, for + credential objects retrieved via + sd_bus_get_name_creds(), this mask will be set + for the credential fields that could not be determined atomically + at peer connection time, and which were later added by reading + augmenting credential data from + /proc. Similarly, for credential objects + retrieved via sd_bus_get_owner_creds(), the + mask is set for the fields that could not be determined atomically + at bus creation time, but have been augmented. Similarly, for + credential objects retrieved via + sd_bus_message_get_creds(), the mask is set + for the fields that could not be determined atomically at message + sending time, but have been augmented. The mask returned by + sd_bus_creds_get_augmented_mask() is always a + subset of (or identical to) the mask returned by + sd_bus_creds_get_mask() for the same + object. The latter call hence returns all credential fields + available in the credential object, the former then marks the + subset of those that have been augmented. Note that augmented + fields are unsuitable for authorization decisions, as they may be + retrieved at different times, thus being subject to races. Hence, + augmented fields should be used exclusively for informational + purposes. + + + sd_bus_creds_ref() creates a new + reference to the credentials object c. This + object will not be destroyed until + sd_bus_creds_unref() has been called as many + times plus once more. Once the reference count has dropped to zero, + c cannot be used anymore, so further + calls to sd_bus_creds_ref(c) or + sd_bus_creds_unref(c) are illegal. + + sd_bus_creds_unref() destroys a reference + to c. + + sd_bus_creds_unrefp() is similar to + sd_bus_creds_unref() but takes a pointer to a + pointer to an sd_bus_creds object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. + + sd_bus_creds_ref(), + sd_bus_creds_unref() and + sd_bus_creds_unrefp() execute no operation if + the passed in bus credentials object is + NULL. + + + + + Return Value + + On success, sd_bus_creds_new_from_pid() + returns 0 or a positive integer. On failure, it returns a negative + errno-style error code. + + sd_bus_creds_get_mask() returns the + mask of successfully acquired fields. + + sd_bus_creds_get_augmented_mask() + returns the mask of fields that have been augmented from data in + /proc, and are thus not suitable for + authorization decisions. + + sd_bus_creds_ref() always returns the + argument. + + sd_bus_creds_unref() always returns + NULL. + + + + Reference ownership + + Function sd_bus_creds_new_from_pid() + creates a new object and the caller owns the sole reference. When + not needed anymore, this reference should be destroyed with + sd_bus_creds_unref3. + + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ESRCH + + Specified pid could not + be found. + + + + -EINVAL + + Specified parameter is invalid + (NULL in case of output + parameters). + + + + -ENOMEM + + Memory allocation failed. + + + + -EOPNOTSUPP + + One of the requested fields is unknown to the local system. + + + + + + Notes + + sd_bus_creds_new_from_pid() and the + other calls described here are available as a shared library, + which can be compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_creds_get_pid3, + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3, + sd_bus_message_get_creds3 + + + + diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml new file mode 100644 index 000000000..7e853d6fe --- /dev/null +++ b/man/sd_bus_default.xml @@ -0,0 +1,312 @@ + + + + + + + + + sd_bus_default + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_default + 3 + + + + sd_bus_default + sd_bus_default_user + sd_bus_default_system + + sd_bus_open + sd_bus_open_user + sd_bus_open_system + sd_bus_open_system_remote + sd_bus_open_system_machine + + Acquire a connection to a system or user bus + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_default + sd_bus **bus + + + + int sd_bus_default_user + sd_bus **bus + + + + int sd_bus_default_system + sd_bus **bus + + + + int sd_bus_open + sd_bus **bus + + + + int sd_bus_open_user + sd_bus **bus + + + + int sd_bus_open_system + sd_bus **bus + + + + int sd_bus_open_system_remote + sd_bus **bus + const char *host + + + + int sd_bus_open_system_machine + sd_bus **bus + const char *machine + + + + + + + Description + + sd_bus_default() acquires a bus + connection object to the user bus when invoked in user context, or + to the system bus otherwise. The connection object is associated + with the calling thread. Each time the function is invoked from + the same thread, the same object is returned, but its reference + count is increased by one, as long as at least one reference is + kept. When the last reference to the connection is dropped (using + the + sd_bus_unref3 + call), the connection is terminated. Note that the connection is + not automatically terminated when the associated thread ends. It + is important to drop the last reference to the bus connection + explicitly before the thread ends, as otherwise, the connection will + leak. Also, queued but unread or unwritten messages keep the + bus referenced, see below. + + sd_bus_default_user() returns a user + bus connection object associated with the calling thread. + sd_bus_default_system() is similar, but + connects to the system bus. Note that + sd_bus_default() is identical to these two + calls, depending on the execution context. + + sd_bus_open() creates a new, + independent bus connection to the user bus when invoked in user + context, or the system bus + otherwise. sd_bus_open_user() is similar, but + connects only to the user bus. + sd_bus_open_system() does the same, but + connects to the system bus. In contrast to + sd_bus_default(), + sd_bus_default_user(), and + sd_bus_default_system(), these calls return + new, independent connection objects that are not associated with + the invoking thread and are not shared between multiple + invocations. It is recommended to share connections per thread to + efficiently make use the available resources. Thus, it is + recommended to use sd_bus_default(), + sd_bus_default_user() and + sd_bus_default_system() to connect to the + user or system buses. + + If the $DBUS_SESSION_BUS_ADDRESS environment + variable is set + (cf. environ7), + it will be used as the address of the user bus. This variable can + contain multiple addresses separated by ;. If + this variable is not set, a suitable default for the default user + D-Bus instance will be used. + + If the $DBUS_SYSTEM_BUS_ADDRESS + environment variable is set, it will be used as the address of the + system bus. This variable uses the same syntax as + $DBUS_SESSION_BUS_ADDRESS. If this variable is + not set, a suitable default for the default system D-Bus instance + will be used. + + sd_bus_open_system_remote() connects to + the system bus on the specified host using + ssh1. host + consists of an optional user name followed by the + @ symbol, and the hostname. + + + sd_bus_open_system_machine() connects + to the system bus in the specified machine, + where machine is the name of a local + container. See + machinectl1 + for more information about the "machine" concept. Note that + connections into local containers are only available to privileged + processes at this time. + + These calls allocate a bus connection object and initiate + the connection to a well-known bus of some form. An alternative to + using these high-level calls is to create an unconnected bus + object with + sd_bus_new3 + and to connect it with + sd_bus_start3. + + + + + + Reference ownership + The functions sd_bus_open(), + sd_bus_open_user(), + sd_bus_open_system(), + sd_bus_open_system_remote(), and + sd_bus_open_system_machine() return a new + connection object and the caller owns the sole reference. When not + needed anymore, this reference should be destroyed with + sd_bus_unref3. + + + The functions sd_bus_default(), + sd_bus_default_user() and + sd_bus_default_system() do not necessarily + create a new object, but increase the connection reference of an + existing connection object by one. Use + sd_bus_unref3 + to drop the reference. + + Queued but unwritten/unread messages also keep a reference + to their bus connection object. For this reason, even if an + application dropped all references to a bus connection, it might + not get destroyed right away. Until all incoming queued + messages are read, and until all outgoing unwritten messages are + written, the bus object will stay + alive. sd_bus_flush() may be used to write + all outgoing queued messages so they drop their references. To + flush the unread incoming messages, use + sd_bus_close(), which will also close the bus + connection. When using the default bus logic, it is a good idea to + first invoke sd_bus_flush() followed by + sd_bus_close() when a thread or process + terminates, and thus its bus connection object should be + freed. + + The life cycle of the default bus connection should be the + responsibility of the code that creates/owns the thread the + default bus connection object is associated with. Library code + should neither call sd_bus_flush() nor + sd_bus_close() on default bus objects unless + it does so in its own private, self-allocated thread. Library code + should not use the default bus object in other threads unless it + is clear that the program using it will life cycle the bus + connection object and flush and close it before exiting from the + thread. In libraries where it is not clear that the calling + program will life cycle the bus connection object, it is hence + recommended to use sd_bus_open_system() + instead of sd_bus_default_system() and + related calls. + + + + Return Value + + On success, these calls return 0 or a positive + integer. On failure, these calls return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The specified parameters are invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + -ESOCKTNOSUPPORT + + The protocol version required to connect to the selected bus is not supported. + + + + In addition, any further connection-related errors may be + by returned. See sd_bus_send3. + + + + Notes + + sd_bus_open_user() and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_ref3, + sd_bus_unref3, + ssh1, + systemd-machined.service8, + machinectl1 + + + + diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml new file mode 100644 index 000000000..6f93a74ca --- /dev/null +++ b/man/sd_bus_error.xml @@ -0,0 +1,389 @@ + + + + + + + + + sd_bus_error + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_error + 3 + + + + sd_bus_error + SD_BUS_ERROR_MAKE_CONST + SD_BUS_ERROR_NULL + sd_bus_error_free + sd_bus_error_set + sd_bus_error_setf + sd_bus_error_set_const + sd_bus_error_set_errno + sd_bus_error_set_errnof + sd_bus_error_set_errnofv + sd_bus_error_get_errno + sd_bus_error_copy + sd_bus_error_is_set + sd_bus_error_has_name + + sd-bus error handling + + + + + #include <systemd/sd-bus.h> + + typedef struct { + const char *name; + const char *message; + … +} sd_bus_error; + + + SD_BUS_ERROR_MAKE_CONST(name, message) + + + SD_BUS_ERROR_NULL + + + + void sd_bus_error_free + sd_bus_error *e + + + + int sd_bus_error_set + sd_bus_error *e + const char *name + const char *message + + + + int sd_bus_error_setf + sd_bus_error *e + const char *name + const char *format + … + + + + int sd_bus_error_set_const + sd_bus_error *e + const char *name + const char *message + + + + int sd_bus_error_set_errno + sd_bus_error *e + int error + + + + int sd_bus_error_set_errnof + sd_bus_error *e + int error + const char *format + … + + + + int sd_bus_error_set_errnofv + sd_bus_error *e + int error + const char *format + va_list ap + + + + int sd_bus_error_get_errno + const sd_bus_error *e + + + + int sd_bus_error_copy + sd_bus_error *dst + const sd_bus_error *e + + + + int sd_bus_error_is_set + const sd_bus_error *e + + + + int sd_bus_error_has_name + const sd_bus_error *e + const char *name + + + + + + + Description + + The sd_bus_error structure carries + information about a D-Bus error condition. The functions described + below may be used to set and query fields in this structure. The + name field contains a short identifier + of an error. It should follow the rules for error names described + in the D-Bus specification, subsection Valid + Names. A number of common, standardized error names are + described in + sd-bus-errors3, + but additional domain-specific errors may be defined by + applications. The message field usually + contains a human-readable string describing the details, but might + be NULL. An unset sd_bus_error structure + should have both fields initialized to NULL. Set an error + structure to SD_BUS_ERROR_NULL in order to + reset both fields to NULL. When no longer necessary, resources + held by the sd_bus_errorstructure should + be destroyed with sd_bus_error_free(). + + sd_bus_error_set() sets an error + structure to the specified name and message strings. The strings + will be copied into internal, newly allocated memory. It is + essential to free the error structure again when it is not + required anymore (see above). The function will return an + errno-like negative value (see errno3) + determined from the specified error name. Various well-known + D-Bus errors are converted to well-known errno + counterparts, and the other ones to -EIO. See + sd-bus-errors3 + for a list of well-known error names. Additional error mappings + may be defined with + sd_bus_error_add_map3. If + e is NULL, no error structure is initialized, + but the error is still converted into an + errno-style error. If + name is NULL, it is + assumed that no error occurred, and 0 is returned. This means that + this function may be conveniently used in a + return statement. If + message is NULL, no message is set. This + call can fail if no memory may be allocated for the name and + message strings, in which case an + SD_BUS_ERROR_NO_MEMORY error might be set + instead and -ENOMEM be returned. Do not use this call on error + structures that are already initialized. If you intend to reuse an + error structure, free the old data stored in it with + sd_bus_error_free() first. + + sd_bus_error_setf() is similar to + sd_bus_error_set(), but takes a printf3 + format string and corresponding arguments to generate the + message field. + + sd_bus_error_set_const() is similar to + sd_bus_error_set(), but the string parameters + are not copied internally, and must hence remain constant and + valid for the lifetime of e. Use this call + to avoid memory allocations when setting error structures. Since + this call does not allocate memory, it will not fail with an + out-of-memory condition as + sd_bus_error_set() can, as described + above. Alternatively, the + SD_BUS_ERROR_MAKE_CONST() macro may be used + to generate a literal, constant bus error structure + on-the-fly. + + sd_bus_error_set_errno() will set + name from an + errno-like value that is converted to a D-Bus + error. strerror_r3 + will be used to set message. Well-known + D-Bus error names will be used for name + if applicable, otherwise a name in the + System.Error. namespace will be generated. The + sign of the specified error number is ignored. The absolute value + is used implicitly. The call always returns a negative value, for + convenient usage in return statements. This + call might fail due to lack of memory, in which case an + SD_BUS_ERROR_NO_MEMORY error is set instead, + and -ENOMEM is returned. + + sd_bus_error_set_errnof() is similar to + sd_bus_error_set_errno(), but in addition to + error, takes a printf3 + format string and corresponding arguments. The + message field will be generated from + format and the arguments. + + sd_bus_error_set_errnofv() is similar to + sd_bus_error_set_errnof(), but takes the + format string parameters as va_arg3 + parameter list. + + sd_bus_error_get_errno() converts the + name field of an error structure to an + errno-like (positive) value using the same + rules as sd_bus_error_set(). If + e is NULL, 0 will be + returned. + + sd_bus_error_copy() will initialize + dst using the values in + e. If the strings in + e were set using + sd_bus_set_error_const(), they will be shared. + Otherwise, they will be copied. Returns a converted + errno-like, negative error code. + + sd_bus_error_is_set() will return a + non-zero value if e is + non-NULL and an error has been set, + false otherwise. + + sd_bus_error_has_name() will return a + non-zero value if e is + non-NULL and an error with the same + name has been set, + false otherwise. + + sd_bus_error_free() will destroy + resources held by e. The parameter itself + will not be deallocated, and must be free3d + by the caller if necessary. The function may also be called safely + on unset errors (error structures with both fields set to NULL), + in which case it performs no operation. This call will reset the + error structure after freeing the data, so that all fields are set + to NULL. The structure may be reused afterwards. + + + + Return Value + + The functions sd_bus_error_set(), + sd_bus_error_setf(), and + sd_bus_error_set_const(), when successful, + return the negative errno value corresponding to the + name parameter. The functions + sd_bus_error_set_errno(), + sd_bus_error_set_errnof() and + sd_bus_error_set_errnofv(), when successful, + return the negative value of the error + parameter. If an error occurs, one of the negative error values + listed below will be returned. + + sd_bus_error_get_errno() returns + false when e is + NULL, and a positive errno value mapped from + e->name otherwise. + + sd_bus_error_copy() returns 0 or a + positive integer on success, and a negative error value converted + from the error name otherwise. + + sd_bus_error_is_set() returns a + non-zero value when e and the + name field are + non-NULL, zero otherwise. + + sd_bus_error_has_name() returns a + non-zero value when e is + non-NULL and the + name field is equal to + name, zero otherwise. + + + + Reference ownership + sd_bus_error is not reference + counted. Users should destroy resources held by it by calling + sd_bus_error_free(). Usually, error structures + are allocated on the stack or passed in as function parameters, + but they may also be allocated dynamically, in which case it is + the duty of the caller to free3 + the memory held by the structure itself after freeing its contents + with sd_bus_error_free(). + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + Error was already set in + sd_bus_error structure when one the + error-setting functions was called. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + sd_bus_set_error() and other functions + described here are available as a shared library, which can be + compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd-bus-errors3, + sd_bus_error_add_map3, + errno3, + strerror_r3 + + + + diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml new file mode 100644 index 000000000..f38fae7eb --- /dev/null +++ b/man/sd_bus_error_add_map.xml @@ -0,0 +1,173 @@ + + + + + + + + + sd_bus_error_add_map + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_error_add_map + 3 + + + + sd_bus_error_add_map + sd_bus_error_map + SD_BUS_ERROR_MAP + SD_BUS_ERROR_END + + Additional sd-dbus error mappings + + + + + #include <systemd/sd-bus.h> + + typedef struct { + const char *name; + int code; + … +} sd_bus_error_map; + + + + + SD_BUS_ERROR_MAP(name, code) + + + SD_BUS_ERROR_MAP_END + + + + int sd_bus_error_add_map + const sd_bus_map *map + + + + + + Description + + The sd_bus_error_add_map() call may be + used to register additional mappings for converting D-Bus errors + to Linux errno-style errors. The mappings + defined with this call are consulted by calls such as + sd_bus_error_set3 + or + sd_bus_error_get_errno3. By + default, a number of generic, standardized mappings are known, as + documented in + sd-bus-errors3. Use + this call to add further, application-specific mappings. + + The function takes a pointer to an array of + sd_bus_error_map structures. A reference + to the specified array is added to the lookup tables for error + mappings. Note that the structure is not copied, and that it is hence + essential that the array stays available and constant during the + entire remaining runtime of the process. + + The mapping array should be put together with a series of + SD_BUS_ERROR_MAP() macro invocations that + take a literal name string and a (positive) + errno-style error number. The last entry of the + array should be an invocation of the + SD_BUS_ERROR_MAP_END macro. The array should not be + put together without use of these two macros. + + Note that the call is idempotent: it is safe to invoke it + multiple times with the parameter, which will only add the passed + mapping array once. + + Note that the memory allocated by this call is not intended + to be freed during the lifetime of the process. It should not be + freed explicitly. + + + + Return Value + + sd_bus_error_add_map() returns a + positive value when the new array was added to the lookup + tables. It returns zero when the same array was already added + before. On error, a negative errno-style error + code is returned. See below for known error codes. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The specified mapping array is invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_error3, + sd-bus-errors3, + errno3, + strerror_r3 + + + + diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml new file mode 100644 index 000000000..9f7019069 --- /dev/null +++ b/man/sd_bus_get_fd.xml @@ -0,0 +1,101 @@ + + + + + + + + + sd_bus_get_fd + systemd + + + + Julian + Orth + ju.orth@gmail.com + + + + + + sd_bus_get_fd + 3 + + + + sd_bus_get_fd + + Get the file descriptor connected to the message bus + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_get_fd + sd_bus *bus + + + + + + Description + + + sd_bus_get_fd() returns the file descriptor used to + communicate with the message bus. This descriptor can be used with + select3, + poll3, + or similar functions to wait for incoming messages. + + + + If the bus was created with the + sd_bus_set_fd3 + function, then the input_fd used in that call is + returned. + + + + + Return Value + + + Returns the file descriptor used for incoming messages from the message + bus. + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_set_fd3, + + + + diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml new file mode 100644 index 000000000..48a022d11 --- /dev/null +++ b/man/sd_bus_message_append.xml @@ -0,0 +1,269 @@ + + + + + + + + + sd_bus_message_append + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append + 3 + + + + sd_bus_message_append + + Attach fields to a D-Bus message based on a type + string + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append + sd_bus_message *m + const char *types + … + + + + + + Description + + The sd_bus_message_append() function + appends a sequence of fields to the D-Bus message object + m. The type string + types describes the types of the field + arguments that follow. For each type specified in the type string, + one or more arguments need to be specified, in the same order as + declared in the type string. + + The type string is composed of the elements shown in the + table below. It contains zero or more single "complete types". + Each complete type may be one of the basic types or a fully + described container type. A container type may be a structure with + the contained types, a variant, an array with its element type, or + a dictionary entry with the contained types. The type string is + NUL-terminated. + + In case of a basic type, one argument of the corresponding + type is expected. + + A structure is denoted by a sequence of complete types + between ( and ). This + sequence cannot be empty — it must contain at least one type. + Arguments corresponding to this nested sequence follow the same + rules as if they were not nested. + + A variant is denoted by v. Corresponding + arguments must begin with a type string denoting a complete type, + and following that, arguments corresponding to the specified type. + + + An array is denoted by a followed by a + complete type. Corresponding arguments must begin with the number of + entries in the array, followed by the entries themselves, + matching the element type of the array. + + A dictionary is an array of dictionary entries, denoted by + a followed by a pair of complete types between + { and }. The first of those + types must be a basic type. Corresponding arguments must begin + with the number of dictionary entries, followed by a pair of + values for each entry matching the element type of + the dictionary entries. + + For further details on the D-Bus type system, please consult + the D-Bus + Specification. + + + Item type specifiers + + + + + + + + + + a + SD_BUS_TYPE_ARRAY + array + determined by array type and size + int, followed by array contents + + + + v + SD_BUS_TYPE_VARIANT + variant + determined by the type argument + signature string, followed by variant contents + + + + ( + SD_BUS_TYPE_STRUCT_BEGIN + array start + determined by the nested types + structure contents + + + ) + SD_BUS_TYPE_STRUCT_END + array end + + + + { + SD_BUS_TYPE_DICT_ENTRY_BEGIN + dictionary entry start + determined by the nested types + dictionary contents + + + } + SD_BUS_TYPE_DICT_ENTRY_END + dictionary entry end + + + +
+ + For types "s" and "g" (unicode string or signature), the pointer may be + NULL, which is equivalent to an empty string. See + sd_bus_message_append_basic3 + for the precise interpretation of those and other types. + + + + + Types String Grammar + + types ::= complete_type* +complete_type ::= basic_type | variant | structure | array | dictionary +basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" | + "b" | "h" | + "s" | "o" | "g" +variant ::= "v" +structure ::= "(" complete_type+ ")" +array ::= "a" complete_type +dictionary ::= "a" "{" basic_type complete_type "}" + + + + + Examples + + Append a single basic type (the string a string): + + + sd_bus_message *m; +… +sd_bus_message_append(m, "s", "a string"); + + Append all types of integers: + + uint8_t y = 1; +int16_t n = 2; +uint16_t q = 3; +int32_t i = 4; +uint32_t u = 5; +int32_t x = 6; +uint32_t t = 7; +double d = 8.0; +sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d); + + Append a structure composed of a string and a D-Bus path: + + sd_bus_message_append(m, "(so)", "a string", "/a/path"); + + + Append an array of UNIX file descriptors: + + sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO); + + + Append a variant, with the real type "g" (signature), + and value "sdbusisgood": + + sd_bus_message_append(m, "v", "g", "sdbusisgood"); + + Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}: + + + sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL); + + + + + Return Value + + On success, this call returns 0 or a positive + integer. On failure, this call returns a negative + errno-style error code. + + + + + + Notes + + sd_bus_open_user() and other functions + described here are available as a shared library, which can be + compiled and linked to with the + libelogind-bus pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append_basic3, + sd_bus_message_append_array3 + + + + diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml new file mode 100644 index 000000000..70f1f7889 --- /dev/null +++ b/man/sd_bus_message_append_array.xml @@ -0,0 +1,213 @@ + + + + + + + + + sd_bus_message_append_array + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_array + 3 + + + + sd_bus_message_append_array + sd_bus_message_append_array_memfd + sd_bus_message_append_array_iovec + sd_bus_message_append_array_space + + Append an array of fields to a D-Bus + message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_array + sd_bus_message *m + char type + char void *ptr + size_t size + + + + int sd_bus_message_append_array_memfd + sd_bus_message *m + char type + int memfd + uint64_t offset + uint64_t size + + + + int sd_bus_message_append_array_iovec + sd_bus_message *m + char type + const struct iovec *iov + unsigned n + + + + int sd_bus_message_append_array_space + char type + size_t size + void **ptr + + + + + + Description + + The sd_bus_message_append_array() + function appends an array to a D-Bus message + m. A container will be opened, the array + contents appended, and the container closed. The parameter + type determines how the pointer + p is interpreted. + type must be one of the "trivial" types + y, n, q, + i, u, x, + t, d (but not + b), as defined by the Basic + Types section of the D-Bus specification, and listed in + sd_bus_message_append_basic3. + Pointer p must point to an array of size + size bytes containing items of the + respective type. Size size must be a + multiple of the size of the type type. As a + special case, p may be + NULL, if size is 0. + The memory pointed to by p is copied into + the memory area containing the message and stays in possession of + the caller. The caller may hence freely change the data after this + call without affecting the message the array was appended + to. + + The sd_bus_message_append_array_memfd() + function appends an array of a trivial type to message + m, similar to + sd_bus_message_append_array(). The contents + of the memory file descriptor memfd + starting at the specified offset and of the specified size is + used as the contents of the array. The offset and size must be a + multiple of the size of the type + type. However, as a special exception, if + the offset is specified as zero and the size specified as + UINT64_MAX the full memory file descriptor contents is used. The + memory file descriptor is sealed by this call if it has not been + sealed yet, and cannot be modified after this call. See + memfd_create2 + for details about memory file descriptors. Appending arrays with + memory file descriptors enables efficient zero-copy data transfer, + as the memory file descriptor may be passed as-is to the + destination, without copying the memory in it to the destination + process. Not all protocol transports support passing memory file + descriptors between participants, in which case this call will + automatically fall back to copying. Also, as memory file + descriptor passing is inefficient for smaller amounts of data, + copying might still be enforced even where memory file descriptor + passing is supported. + + The sd_bus_message_append_array_iovec() + function appends an array of a trivial type to the message + m, similar to + sd_bus_message_append_array(). Contents of + the I/O vector array iov are used as the + contents of the array. The total size of + iov payload (the sum of + iov_len fields) must be a multiple of + the size of the type type. The + iov argument must point to + n I/O vector structures. Each structure may + have the iov_base field set, in which + case the memory pointed to will be copied into the message, or + unset (set to zero), in which case a block of zeros of length + iov_len bytes will be inserted. The + memory pointed at by iov may be changed + after this call. + + The sd_bus_message_append_array_space() + function appends space for an array of a trivial type to message + m. It behaves the same as + sd_bus_message_append_array(), but instead of + copying items to the message, it returns a pointer to the + destination area to the caller in pointer + p. The caller should subsequently write the + array contents to this memory. Modifications to the memory + pointed to should only occur until the next operation on the bus + message is invoked. Most importantly, the memory should not be + altered anymore when another field has been added to the message + or the message has been sealed. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, they return a negative errno-style error code. + + + + + + Notes + + sd_bus_append_array() and other + functions described here are available as a shared library, which + can be compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + sd_bus_message_append_basic3, + memfd_create2, + The D-Bus specification + + + + diff --git a/man/sd_bus_message_append_basic.xml b/man/sd_bus_message_append_basic.xml new file mode 100644 index 000000000..90abca809 --- /dev/null +++ b/man/sd_bus_message_append_basic.xml @@ -0,0 +1,295 @@ + + + + + + + + + sd_bus_message_append_basic + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_basic + 3 + + + + sd_bus_message_append_basic + + Attach a single field to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_basic + sd_bus_message *m + char type + const void *p + + + + + + Description + + sd_bus_message_append_basic() appends a + single field to the message m. The + parameter type determines how the pointer + p is interpreted. + type must be one of the basic types as + defined by the Basic + Types section of the D-Bus specification, and listed in + the table below. + + + + Item type specifiers + + + + + + + + + + Specifier + Constant + Description + Size + Expected C Type + + + + + y + SD_BUS_TYPE_BYTE + unsigned integer + 1 byte + uint8_t + + + + b + SD_BUS_TYPE_BOOLEAN + boolean + 4 bytes + int + + + + n + SD_BUS_TYPE_INT16 + signed integer + 2 bytes + int16_t + + + + q + SD_BUS_TYPE_UINT16 + unsigned integer + 2 bytes + uint16_t + + + + i + SD_BUS_TYPE_INT32 + signed integer + 4 bytes + int32_t + + + + u + SD_BUS_TYPE_UINT32 + unsigned integer + 4 bytes + uint32_t + + + + x + SD_BUS_TYPE_INT64 + signed integer + 8 bytes + int64_t + + + + t + SD_BUS_TYPE_UINT64 + unsigned integer + 8 bytes + uint64_t + + + + d + SD_BUS_TYPE_DOUBLE + floating-point + 8 bytes + double + + + + s + SD_BUS_TYPE_STRING + Unicode string + variable + char[] + + + + o + SD_BUS_TYPE_OBJECT_PATH + object path + variable + char[] + + + + g + SD_BUS_TYPE_SIGNATURE + signature + variable + char[] + + + + h + SD_BUS_TYPE_UNIX_FD + UNIX file descriptor + 4 bytes + int + + + +
+ + The value of the parameter is copied into a memory area held + by the message object, stays in the possession of the caller and + may hence be freely changed after this call without affecting the + bus message it has been added to. If type + is h (UNIX file descriptor), the descriptor is + duplicated by this call and the passed descriptor stays in + possession of the caller. + + For types s, o, and + g, the parameter p is + interpreted as a pointer to a NUL-terminated + character sequence. As a special case, a NULL + pointer is interpreted as an empty string. The string should be + valid Unicode string encoded as UTF-8. In case of the two latter + types, the additional requirements for a D-Bus object path or + type signature should be satisfied. Those requirements should be + verified by the recipient of the message. + + + + + Return Value + + On success, this call returns 0 or a positive integer. On + failure, it returns a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + Specified parameter is invalid. + + + + + -EPERM + + Message has been sealed. + + + + + -ESTALE + + Message is in invalid state. + + + + + -ENXIO + + Message cannot be appended to. + + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_bus_append_basic() function + described here is available as a shared library, which can be + compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + The D-Bus specification + + + + diff --git a/man/sd_bus_message_append_strv.xml b/man/sd_bus_message_append_strv.xml new file mode 100644 index 000000000..8b7178637 --- /dev/null +++ b/man/sd_bus_message_append_strv.xml @@ -0,0 +1,116 @@ + + + + + + + + + sd_bus_message_append_strv + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_strv + 3 + + + + sd_bus_message_append_strv + + Attach an array of strings to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_strv + sd_bus_message *m + char **l + + + + + + Description + + The sd_bus_message_append function can be + used to append an array of strings to message + m. The parameter l + shall point to a NULL-terminated array of pointers + to NUL-terminated strings. Each string must + satisfy the same constraints as described for the + s type in + sd_bus_message_append_basic3. + + + The memory pointed at by p and the + contents of the strings themselves are copied into the memory area + containing the message and may be changed after this call. Note + that the signature of l parameter is to be + treated as const char *const *, and the contents + will not be modified. + + + + Return Value + + On success, this call returns 0 or a positive integer. On + failure, a negative errno-style error code is returned. + + + + + + Notes + + The sd_bus_append_append_strv() function + described here is available as a shared library, which can be + compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + sd_bus_message_append_array3, + The D-Bus specification + + + + diff --git a/man/sd_bus_message_read_basic.xml b/man/sd_bus_message_read_basic.xml new file mode 100644 index 000000000..6a4640315 --- /dev/null +++ b/man/sd_bus_message_read_basic.xml @@ -0,0 +1,113 @@ + + + + + + + + + sd_bus_message_read_basic + systemd + + + + Julian + Orth + ju.orth@gmail.com + + + + + + sd_bus_message_read_basic + 3 + + + + sd_bus_message_read_basic + + Read a basic type from a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_read_basic + sd_bus_message *m + char type + void *p + + + + + + Description + + + sd_bus_message_read_basic() reads a basic type from a + message and advances the read position in the message. The set of basic + types and their ascii codes passed in type are + described in the D-Bus + Specification. + + + + If p is not NULL, it should contain a pointer to an + appropriate object. For example, if type is + 'y', the object passed in p + should have type uint8_t *. If type + is 's', the object passed in p + should have type const char **. Note that, if the basic type + is a pointer (e.g., const char * in the case of a string), + the pointer is only borrowed and the contents must be copied if they are + to be used after the end of the messages lifetime. Similarly, during the + lifetime of such a pointer, the message must not be modified. + + + + If there is no object of the specified type at the current position in the + message, an error is returned. + + + + + Return Value + + + On success, sd_bus_message_read_basic() returns 0 or + a positive integer. On failure, it returns a negative errno-style error + code. + + + + + See Also + + + systemd1, + sd-bus3, + + + + diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml new file mode 100644 index 000000000..61c972008 --- /dev/null +++ b/man/sd_bus_negotiate_fds.xml @@ -0,0 +1,186 @@ + + + + + + + + + sd_bus_negotiate_fds + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_negotiate_fds + 3 + + + + sd_bus_negotiate_fds + sd_bus_negotiate_timestamp + sd_bus_negotiate_creds + + Control feature negotiation on bus connections + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_negotiate_fds + sd_bus *bus + int b + + + + int sd_bus_negotiate_timestamp + sd_bus *bus + int b + + + + int sd_bus_negotiate_creds + sd_bus *bus + int b + uint64_t mask + + + + + + Description + + sd_bus_negotiate_fds() controls whether + file descriptor passing shall be negotiated for the specified bus + connection. It takes a bus object and a boolean, which, when true, + enables file descriptor passing, and, when false, disables + it. Note that not all transports and servers support file + descriptor passing. In particular, networked transports generally + do not support file descriptor passing. To find out whether file + descriptor passing is available after negotiation, use + sd_bus_can_send3 + and pass SD_BUS_TYPE_UNIX_FD. Note that file + descriptor passing is always enabled for both sending and + receiving or for neither, but never only in one direction. By + default, file descriptor passing is negotiated for all + connections. + + Note that when bus activation is used, it is highly + recommended to set the + setting in the .busname unit file to the same + setting as negotiated by the program ultimately activated. By + default, file descriptor passing is enabled for both. + + sd_bus_negotiate_timestamp() controls whether implicit sender + timestamps shall be attached automatically to all incoming messages. Takes a bus object and a + boolean, which, when true, enables timestamping, and, when false, disables it. Use + sd_bus_message_get_monotonic_usec3, + sd_bus_message_get_realtime_usec3, + sd_bus_message_get_seqnum3 + to query the timestamps of incoming messages. If negotiation is disabled or not supported, these + calls will fail with -ENODATA. Note that currently no transports support + timestamping of messages. By default, message timestamping is not negotiated for + connections. + + sd_bus_negotiate_creds() controls whether and which implicit sender + credentials shall be attached automatically to all incoming messages. Takes a bus object and a + boolean indicating whether to enable or disable the credential parts encoded in the bit mask + value argument. Note that not all transports support attaching sender credentials to messages, + or do not support all types of sender credential parameters, or might suppress them under + certain circumstances for individual messages. Specifically, dbus1 only supports + SD_BUS_CREDS_UNIQUE_NAME. The sender credentials are suitable for + authorization decisions. By default, only SD_BUS_CREDS_WELL_KNOWN_NAMES and + SD_BUS_CREDS_UNIQUE_NAME are enabled. In fact, these two credential fields + are always sent along and cannot be turned off. + + The sd_bus_negotiate_fds() function may + be called only before the connection has been started with + sd_bus_start3. Both + sd_bus_negotiate_timestamp() and + sd_bus_negotiate_creds() may also be called + after a connection has been set up. Note that, when operating on a + connection that is shared between multiple components of the same + program (for example via + sd_bus_default3), + it is highly recommended to only enable additional per message + metadata fields, but never disable them again, in order not to + disable functionality needed by other components. + + + + Return Value + + On success, these functions return 0 or a + positive integer. On failure, they return a negative errno-style + error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EPERM + + The bus connection has already been started. + + + + + + Notes + + sd_bus_negotiate_fds() and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_start3, + sd_bus_message_can_send3, + sd_bus_message_get_monotonic_usec3, + sd_bus_message_get_realtime_usec3, + sd_bus_message_get_seqnum3, + sd_bus_message_get_creds3, + systemd.busname5 + + + + diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml new file mode 100644 index 000000000..2eeba78e8 --- /dev/null +++ b/man/sd_bus_new.xml @@ -0,0 +1,189 @@ + + + + + + + + + sd_bus_new + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_new + 3 + + + + sd_bus_new + sd_bus_ref + sd_bus_unref + sd_bus_unrefp + + Create a new bus object and create or destroy references to it + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_new + sd_bus **bus + + + + sd_bus *sd_bus_ref + sd_bus *bus + + + + sd_bus *sd_bus_unref + sd_bus *bus + + + + void sd_bus_unrefp + sd_bus **bus + + + + + + Description + + sd_bus_new() creates a new bus + object. This object is reference-counted, and will be destroyed + when all references are gone. Initially, the caller of this + function owns the sole reference and the bus object will not be + connected to any bus. To connect it to a bus, make sure + to set an address with + sd_bus_set_address3 + or a related call, and then start the connection with + sd_bus_start3. + + In most cases, it is a better idea to invoke + sd_bus_default_user3, + sd_bus_default_system3 + or related calls instead of the more low-level + sd_bus_new() and + sd_bus_start(). The higher-level calls not + only allocate a bus object but also start the connection to a + well-known bus in a single function invocation. + + sd_bus_ref() increases the reference + counter of bus by one. + + sd_bus_unref() decreases the reference + counter of bus by one. Once the reference + count has dropped to zero, bus is destroyed + and cannot be used anymore, so further calls to + sd_bus_ref() or + sd_bus_unref() are illegal. + + sd_bus_unrefp() is similar to + sd_bus_unref() but takes a pointer to a + pointer to an sd_bus object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, in order to + allocate a bus object that is freed automatically as the code + block is left: + + { + __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; + int r; + … + r = sd_bus_default(&bus); + if (r < 0) + fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); + … +} + + sd_bus_ref(), + sd_bus_unref() and + sd_bus_unrefp() execute no operation if the + passed in bus object is NULL. + + + + Return Value + + On success, sd_bus_new() returns 0 or a + positive integer. On failure, it returns a negative errno-style + error code. + + sd_bus_ref() always returns the argument. + + + sd_bus_unref() always returns + NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + sd_bus_new() and other functions + described here are available as a shared library, which can be + compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_default_user3, + sd_bus_default_system3, + sd_bus_open_user3, + sd_bus_open_system3 + + + + diff --git a/man/sd_bus_process.xml b/man/sd_bus_process.xml new file mode 100644 index 000000000..4b9f52e52 --- /dev/null +++ b/man/sd_bus_process.xml @@ -0,0 +1,111 @@ + + + + + + + + + sd_bus_process + systemd + + + + Julian + Orth + ju.orth@gmail.com + + + + + + sd_bus_process + 3 + + + + sd_bus_process + + Drive the connection + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_process + sd_bus *bus + sd_bus_message **r + + + + + + Description + + + sd_bus_process() drives the connection between the + message bus and the client. That is, it handles connecting, + authentication, and message processing. It should be called in a loop + until no further progress can be made or an error occurs. + + + + Once no further progress can be made, + sd_bus_wait3 + should be called. Alternatively the user can wait for incoming data on + the file descriptor returned by + sd_bus_get_fd3. + + + + sd_bus_process processes at most one incoming + message per call. If the parameter r is not NULL + and the call processed a message, *r is set to this message. + The caller owns a reference to this message and should call + sd_bus_message_unref3 + when the message is no longer needed. If r is not + NULL, progress was made, but no message was processed, *r is + set to NULL. + + + + + Return Value + + + If progress was made, a positive integer is returned. If no progress was + made, 0 is returned. If an error occurs, a negative errno-style error code + is returned. + + + + + See Also + + + systemd1, + sd-bus3, + + + + diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml new file mode 100644 index 000000000..520e6fb84 --- /dev/null +++ b/man/sd_bus_request_name.xml @@ -0,0 +1,213 @@ + + + + + + + + + sd_bus_request_name + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_request_name + 3 + + + + sd_bus_request_name + sd_bus_release_name + Request or release a well-known service name on a bus + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_request_name + sd_bus *bus + const char *name + uint64_t flags + + + + int sd_bus_release_name + sd_bus *bus + const char *name + + + + + + Description + + sd_bus_request_name() requests a + well-known service name on a bus. It takes a bus connection, a + valid bus name and a flags parameter. The flags parameter is a + combination of the following flags: + + + + SD_BUS_NAME_ALLOW_REPLACEMENT + + After acquiring the name successfully, permit + other peers to take over the name when they try to acquire it + with the SD_BUS_NAME_REPLACE_EXISTING flag + set. If SD_BUS_NAME_ALLOW_REPLACEMENT is + not set on the original request, such a request by other peers + will be denied. + + + + SD_BUS_NAME_REPLACE_EXISTING + + Take over the name if it is already acquired + by another peer, and that other peer has permitted takeover by + setting SD_BUS_NAME_ALLOW_REPLACEMENT while + acquiring it. + + + + SD_BUS_NAME_QUEUE + + Queue the acquisition of the name when the + name is already taken. + + + + sd_bus_release_name() releases an + acquired well-known name. It takes a bus connection and a valid + bus name as parameters. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code. + + If SD_BUS_NAME_QUEUE is specified, + sd_bus_request_name() will return 0 when the + name is already taken by another peer and the client has been + added to the queue for the name. In that case, the caller can + subscribe to NameOwnerChanged signals to be + notified when the name is successfully acquired. + sd_bus_request_name() returns > 0 when the + name has immediately been acquired successfully. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EALREADY + + The caller already is the owner of the + specified name. + + + + -EEXIST + + The name has already been acquired by a + different peer, and SD_BUS_NAME_REPLACE_EXISTING was not + specified or the other peer did not specify + SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the + name. + + + + -ESRCH + + It was attempted to release a name that is + currently not registered on the bus. + + + + -EADDRINUSE + + It was attempted to release a name that is + owned by a different peer on the bus. + + + + -EINVAL + + A specified parameter is invalid. This is also + generated when the requested name is a special service name + reserved by the D-Bus specification, or when the operation is + requested on a connection that does not refer to a + bus. + + + + -ENOTCONN + + The bus connection has been + disconnected. + + + + -ECHILD + + The bus connection has been created in a + different process than the current one. + + + + + + Notes + + The sd_bus_acquire_name() and + sd_bus_release_name() interfaces are + available as a shared library, which can be compiled and linked to + with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3 + + + + diff --git a/man/sd_bus_track_add_name.xml b/man/sd_bus_track_add_name.xml new file mode 100644 index 000000000..e15db4459 --- /dev/null +++ b/man/sd_bus_track_add_name.xml @@ -0,0 +1,261 @@ + + + + + + + + + sd_bus_track_add_name + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_track_add_name + 3 + + + + sd_bus_track_add_name + sd_bus_track_add_sender + sd_bus_track_remove_name + sd_bus_track_remove_sender + sd_bus_track_count + sd_bus_track_count_sender + sd_bus_track_count_name + sd_bus_track_contains + sd_bus_track_first + sd_bus_track_next + + Add, remove and retrieve bus peers tracked in a bus peer tracking object + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_track_add_name + sd_bus_track* t + const char* name + + + + int sd_bus_track_add_sender + sd_bus_track* t + sd_bus_message* message + + + + int sd_bus_track_remove_name + sd_bus_track* t + const char* name + + + + int sd_bus_track_remove_sender + sd_bus_track* t + sd_bus_message* message + + + + unsigned sd_bus_track_count + sd_bus_track* t + + + + int sd_bus_track_count_name + sd_bus_track* t + const char* name + + + + int sd_bus_track_count_sender + sd_bus_track* t + sd_bus_message* message + + + + int sd_bus_track_contains + sd_bus_track* t + const char* name + + + + const char* sd_bus_track_first + sd_bus_track* t + + + + const char* sd_bus_track_next + sd_bus_track* t + + + + + + + Description + + sd_bus_track_add_name() adds a peer to track to a bus peer tracking object. The first + argument should refer to a bus peer tracking object created with + sd_bus_track_new3, the second + name should refer to a D-Bus peer name to track, either in unique or well-known service format. If the name is not + tracked yet it will be added to the list of names to track. If it already is being tracked and non-recursive mode + is enabled, no operation is executed by this call. If recursive mode is enabled a per-name counter is increased by + one each time this call is invoked, and sd_bus_track_remove_name() has to be called as many + times as sd_bus_track_add_name() was invoked before in order to stop tracking of the name. Use + sd_bus_track_set_recursive3 to + switch from the default non-recursive mode to recursive mode, or back. Note that the specified name is tracked as + it is, well-known names are not resolved to unique names by this call. Note that multiple bus peer tracking objects + may track the same name. + + sd_bus_track_remove_name() undoes the effect of + sd_bus_track_add_name() and removes a bus peer name from the list of peers to watch. Depending + on whether non-recursive or recursive mode is enabled for the bus peer tracking object this call will either remove + the name fully from the tracking object, or will simply decrement the per-name counter by one, removing the name + only when the counter reaches zero (see above). Note that a bus peer disconnecting from the bus will implicitly + remove its names fully from the bus peer tracking object, regardless of the current per-name counter. + + sd_bus_track_add_sender() and sd_bus_track_remove_sender() are + similar to sd_bus_track_add_name() and sd_bus_track_remove_name() but + take a bus message as argument. The sender of this bus message is determined and added to/removed from the bus peer + tracking object. As messages always originate from unique names, and never from well-known names this means that + this call will effectively only add unique names to the bus peer tracking object. + + sd_bus_track_count() returns the number of names currently being tracked by the + specified bus peer tracking object. Note that this function always returns the actual number of names tracked, and + hence if sd_bus_track_add_name() has been invoked multiple times for the same name it is only + counted as one, regardless if recursive mode is used or not. + + sd_bus_track_count_name() returns the current per-name counter for the specified + name. If non-recursive mode is used this returns either 1 or 0, depending on whether the specified name has been + added to the tracking object before, or not. If recursive mode has been enabled, values larger than 1 may be + returned too, in case sd_bus_track_add_name() has been called multiple times for the same + name. + + sd_bus_track_count_sender() is similar to + sd_bus_track_count_name(), but takes a bus message object and returns the per-name counter + matching the sender of the message. + + sd_bus_track_contains() may be used to determine whether the specified name has been + added at least once to the specified bus peer tracking object. + + sd_bus_track_first() and sd_bus_track_next() may be used to + enumerate all names currently being tracked by the passed bus peer tracking + object. sd_bus_track_first() returns the first entry in the object, and resets an internally + maintained read index. Each subsequent invocation of sd_bus_track_next() returns the next name + contained in the bus object. If the end is reached NULL is returned. If no names have been + added to the object yet sd_bus_track_first() will return NULL + immediately. The order in which names are returned is undefined; in particular which name is considered the first + returned is not defined. If recursive mode is enabled and the same name has been added multiple times to the bus + peer tracking object it is only returned once by this enumeration. If new names are added to or existing names + removed from the bus peer tracking object while it is being enumerated the enumeration ends on the next invocation + of sd_bus_track_next() as NULL is returned. + + + + Return Value + + On success, sd_bus_track_add_name() and sd_bus_track_add_sender() + return 0 if the specified name has already been added to the bus peer tracking object before and positive if it + hasn't. On failure, they return a negative errno-style error code. + + sd_bus_track_remove_name() and sd_bus_track_remove_sender() return + positive if the specified name was previously tracked by the bus peer tracking object and has now been removed. In + non-recursive mode, 0 is returned if the specified name was not being tracked yet. In recursive mode + -EUNATCH is returned in this case. On failure, they return a negative errno-style error + code. + + sd_bus_track_count() returns the number of names currently being tracked, or 0 on + failure. + + sd_bus_track_count_name() and sd_bus_track_count_sender() return + the current per-name counter for the specified name or the sender of the specified message. Zero is returned for + names that are not being tracked yet, a positive value for names added at least once. Larger values than 1 are only + returned in recursive mode. On failure, a negative errno-style error code is returned. + + sd_bus_track_contains() returns the passed name if it exists in the bus peer tracking + object. On failure, and if the name has not been added yet NULL is returned. + + sd_bus_track_first() and sd_bus_track_next() return the first/next + name contained in the bus peer tracking object, and NULL if the end of the enumeration is + reached and on error. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EUNATCH + + sd_bus_track_remove_name() or + sd_bus_track_remove_sender() have been invoked for a name not previously added to the bus + peer object. + + + + -EINVAL + + Specified parameter is invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + + + + Notes + + sd_bus_track_add_name() and the other calls described here are available as a shared library, + which can be compiled and linked to with the libelogind pkg-config1 file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_track_new3 + + + + diff --git a/man/sd_bus_track_new.xml b/man/sd_bus_track_new.xml new file mode 100644 index 000000000..4917f2e37 --- /dev/null +++ b/man/sd_bus_track_new.xml @@ -0,0 +1,263 @@ + + + + + + + + + sd_bus_track_new + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_track_new + 3 + + + + sd_bus_track_new + sd_bus_track_ref + sd_bus_track_unref + sd_bus_track_unrefp + sd_bus_track_set_recursive + sd_bus_track_get_recursive + sd_bus_track_get_bus + sd_bus_track_get_userdata + sd_bus_track_set_userdata + + Track bus peers + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_track_new + sd_bus* bus + sd_bus_track** ret + sd_bus_track_handler_t handler + void* userdata + + + + sd_bus_track *sd_bus_track_ref + sd_bus_track *t + + + + sd_bus_track *sd_bus_track_unref + sd_bus_track *t + + + + void sd_bus_track_unrefp + sd_bus_track **t + + + + int sd_bus_track_get_recursive + sd_bus_track *t + + + + int sd_bus_track_set_recursive + sd_bus_track *t + int b + + + + sd_bus* sd_bus_track_get_bus + sd_bus_track *t + + + + void* sd_bus_track_get_userdata + sd_bus_track *t + + + + void* sd_bus_track_set_userdata + sd_bus_track *t + void *userdata + + + + + + + Description + + sd_bus_track_new() creates a new bus peer tracking object. The object is allocated for + the specified bus, and returned in the *ret parameter. After use, the object should be freed + again by dropping the acquired reference with sd_bus_track_unref() (see below). A bus peer + tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of + one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as + long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers + have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to + specific bus peers are added via + sd_bus_track_add_name3 or + sd_bus_track_add_sender(). They may be dropped again via + sd_bus_track_remove_name() and + sd_bus_track_remove_sender(). Alternatively, references on peers are removed automatically + when they disconnect from the bus. If non-NULL the handler may specify a function that is + invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via + sd_bus_track_remove_name() or implicitly because the peer disconnected from the bus. The final + argument userdata may be used to attach a generic user data pointer to the object. This + pointer is passed to the handler callback when it is invoked. + + sd_bus_track_ref() creates a new reference to a bus peer tracking object. This object + will not be destroyed until sd_bus_track_unref() has been called as many times plus once + more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to + sd_bus_track_ref() or sd_bus_track_unref() on the same object are + illegal. + + sd_bus_track_unref() destroys a reference to a bus peer tracking object. + + sd_bus_track_unrefp() is similar to sd_bus_track_unref() but takes + a pointer to a pointer to an sd_bus_track object. This call is useful in conjunction with GCC's and + LLVM's Clean-up Variable + Attribute. Note that this function is defined as inline function. + + sd_bus_track_ref(), sd_bus_track_unref() and + sd_bus_track_unrefp() execute no operation if the passed in bus peer tracking object is + NULL. + + Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may + optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked + or not tracked. In this mode invoking sd_bus_track_add_name() multiple times in a row for the + same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if + necessary, and executes no operation if the peer is already being tracked. A single invocation of + sd_bus_track_remove_name() removes the reference on the peer again, regardless how many times + sd_bus_track_add_name() was called before. If operating in recursive mode, the number of times + sd_bus_track_add_name() is invoked for the same peer name is counted and + sd_bus_track_remove_name() must be called the same number of times before the peer is not + tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is + irrelevant and the tracking of the specific peer is immediately + removed. sd_bus_track_get_recursive() may be used to determine whether the bus peer tracking + object is operating in recursive mode. sd_bus_track_set_recursive() may be used to enable or + disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and + sd_bus_track_get_recursive() for a newly allocated object hence returns a value equal to + zero. Use sd_bus_track_set_recursive() to enable recursive mode, right after allocation. It + takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which + sd_bus_track_add_name() was already invoked at least once (and which hence track already one + or more peers) may not be switched from recursive to non-recursive mode anymore. + + sd_bus_track_get_bus() returns the bus object the bus peer tracking object belongs + to. It returns the bus object initially passed to sd_bus_track_new() when the object was + allocated. + + sd_bus_track_get_userdata() returns the generic user data pointer set on the bus peer + tracking object at the time of creation using sd_bus_track_new() or at a later time, using + sd_bus_track_set_userdata(). + + + + Return Value + + On success, sd_bus_track_new() and sd_bus_track_set_recursive() + return 0 or a positive integer. On failure, they return a negative errno-style error code. + + sd_bus_track_ref() always returns the argument. + + sd_bus_track_unref() always returns NULL. + + sd_bus_track_get_recursive() returns 0 if non-recursive mode is selected (default), and + greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned. + + sd_bus_track_get_bus() returns the bus object associated to the bus peer tracking + object. + + sd_bus_track_get_userdata() returns the generic user data pointer associated with the + bus peer tracking object. sd_bus_track_set_userdata() returns the previous user data pointer + set. + + + + + Reference ownership + + The sd_bus_track_new() function creates a new object and the caller owns the sole + reference. When not needed anymore, this reference should be destroyed with + sd_bus_track_unref(). + + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EBUSY + + Bus peers have already been added to the bus peer tracking object and + sd_bus_track_set_recursive() was called to change tracking mode. + + + + -EINVAL + + Specified parameter is invalid + (NULL in case of output + parameters). + + + + -ENOMEM + + Memory allocation failed. + + + + + + + Notes + + sd_bus_track_new() and the other calls described here are available as a shared library, + which can be compiled and linked to with the libelogind pkg-config1 file. + + + + See Also + + + systemd1, + sd-bus3 + sd_bus_track_add_name3 + + + + diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml new file mode 100644 index 000000000..1e7cbf56e --- /dev/null +++ b/man/sd_event_add_child.xml @@ -0,0 +1,246 @@ + + + + + + + + + sd_event_add_child + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_add_child + 3 + + + + sd_event_add_child + sd_event_source_get_child_pid + sd_event_child_handler_t + + Add a child process state change event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_child_handler_t) + sd_event_source *s + const siginfo_t *si + void *userdata + + + + int sd_event_add_child + sd_event *event + sd_event_source **source + pid_t pid + int options + sd_event_child_handler_t handler + void *userdata + + + + int sd_event_source_get_child_pid + sd_event_source *source + pid_t *pid + + + + + + + Description + + sd_event_add_child() adds a new child + process state change event source to an event loop. The event loop + object is specified in the event parameter, + the event source object is returned in the + source parameter. The + pid parameter specifies the PID of the + process to watch. The handler must + reference a function to call when the process changes state. The + handler function will be passed the + userdata pointer, which may be chosen + freely by the caller. The handler also receives a pointer to a + siginfo_t structure containing + information about the child process event. The + options parameter determines which state + changes will be watched for. It must contain an OR-ed mask of + WEXITED (watch for the child process + terminating), WSTOPPED (watch for the child + process being stopped by a signal), and + WCONTINUED (watch for the child process being + resumed by a signal). See waitid2 + for further information. + + Only a single handler may be installed for a specific + child process. The handler is enabled for a single event + (SD_EVENT_ONESHOT), but this may be changed + with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the second parameter of + sd_event_add_child() is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed. + + Note that the handler function is + invoked at a time where the child process is not reaped yet (and + thus still is exposed as a zombie process by the kernel). However, + the child will be reaped automatically after the function + returns. Child processes for which no child process state change + event sources are installed will not be reaped by the event loop + implementation. + + If both a child process state change event source and a + SIGCHLD signal event source is installed in + the same event loop, the configured event source priorities decide + which event source is dispatched first. If the signal handler is + processed first, it should leave the child processes for which + child process state change event sources are installed unreaped. + + sd_event_source_get_child_pid() + retrieves the configured PID of a child process state change event + source created previously with + sd_event_add_child(). It takes the event + source object as the source parameter and a + pointer to a pid_t variable to return the process ID + in. + + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. This includes + specifying an empty mask in options or a mask + which contains values different than a combination of + WEXITED, WSTOPPED, and + WCONTINUED. + + + + + + -EBUSY + + A handler is already installed for this + child process. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EDOM + + The passed event source is not a child process event source. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + waitid2 + + + + diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml new file mode 100644 index 000000000..f8ac3e40a --- /dev/null +++ b/man/sd_event_add_defer.xml @@ -0,0 +1,216 @@ + + + + + + + + + sd_event_add_defer + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_add_defer + 3 + + + + sd_event_add_defer + sd_event_add_post + sd_event_add_exit + sd_event_handler_t + + Add static event sources to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_handler_t) + sd_event_source *s + void *userdata + + + + int sd_event_add_defer + sd_event *event + sd_event_source **source + sd_event_handler_t handler + void *userdata + + + + int sd_event_add_post + sd_event *event + sd_event_source **source + sd_event_handler_t handler + void *userdata + + + + int sd_event_add_exit + sd_event *event + sd_event_source **source + sd_event_handler_t handler + void *userdata + + + + + + + Description + + These three functions add new static event sources to an + event loop. The event loop object is specified in the + event parameter, the event source object is + returned in the source parameter. The event + sources are enabled statically and will "fire" when the event loop + is run and the conditions described below are met. The handler + function will be passed the userdata + pointer, which may be chosen freely by the caller. + + sd_event_add_defer() adds a new event + source that will be dispatched instantly, before the event loop + goes to sleep again and waits for new events. By default, the + handler will be called once + (SD_EVENT_ONESHOT). Note that if the event + source is set to SD_EVENT_ON the event loop + will never go to sleep again, but continuously call the handler, + possibly interleaved with other event sources. + + sd_event_add_post() adds a new event + source that is run before the event loop will sleep and wait + for new events, but only after at least one other non-post event + source was dispatched. By default, the source is enabled + permanently (SD_EVENT_ON). Note that this + event source type will still allow the event loop to go to sleep + again, even if set to SD_EVENT_ON, as long as + no other event source is ever triggered. + + sd_event_add_exit() adds a new event + source that will be dispatched when the event loop is terminated + with sd_event_exit3. + + The + sd_event_source_set_enabled3 + function may be used to enable the event source permanently + (SD_EVENT_ON) or to make it fire just once + (SD_EVENT_ONESHOT). + + If the handler function returns a negative error code, it + will be disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + SD_EVENT_OFF with + sd_event_source_set_enabled3. + + If the second parameter of these functions is passed as + NULL no reference to the event source object is returned. In this + case the event source is considered "floating", and will be + destroyed implicitly when the event loop itself is + destroyed. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + -ESTALE + + The event loop is already terminated. + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + sd_event_exit3 + + + + diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml new file mode 100644 index 000000000..4c19ada01 --- /dev/null +++ b/man/sd_event_add_signal.xml @@ -0,0 +1,221 @@ + + + + + + + + + sd_event_add_signal + systemd + + + + More text + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_event_add_signal + 3 + + + + sd_event_add_signal + sd_event_source_get_signal + sd_event_signal_handler_t + + Add a UNIX process signal event source to an event + loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_signal_handler_t) + sd_event_source *s + const struct signalfd_siginfo *si + void *userdata + + + + int sd_event_add_signal + sd_event *event + sd_event_source **source + int signal + sd_event_signal_handler_t handler + void *userdata + + + + int sd_event_source_get_signal + sd_event_source *source + + + + + + + Description + + sd_event_add_signal() adds a new UNIX + process signal event source to an event loop. The event loop + object is specified in the event parameter, + and the event source object is returned in the + source parameter. The + signal parameter specifies the numeric + signal to be handled (see signal7). + The handler parameter must reference a + function to call when the signal is received or be + NULL. The handler function will be passed + the userdata pointer, which may be chosen + freely by the caller. The handler also receives a pointer to a + signalfd_siginfo structure containing + information about the received signal. See signalfd2 + for further information. + + Only a single handler may be installed for a specific + signal. The signal will be unblocked by this call, and must be + blocked before this function is called in all threads (using + sigprocmask2). If + the handler is not specified (handler is + NULL), a default handler which causes the + program to exit cleanly will be used. + + By default, the event source is enabled permanently + (SD_EVENT_ON), but this may be changed with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. + + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_signal() is + NULL no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed. + + sd_event_source_get_signal() returns + the configured signal number of an event source created previously + with sd_event_add_signal(). It takes the + event source object as the source + parameter. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + -EBUSY + + A handler is already installed for this + signal or the signal was not blocked previously. + + + + -ESTALE + + The event loop is already terminated. + + + + -ECHILD + + The event loop has been created in a different process. + + + + -EDOM + + The passed event source is not a signal event source. + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_description3, + sd_event_source_set_userdata3, + signal7, + signalfd2 + + + + diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml new file mode 100644 index 000000000..d5e2e9137 --- /dev/null +++ b/man/sd_event_add_time.xml @@ -0,0 +1,313 @@ + + + + + + + + + sd_event_add_time + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_add_time + 3 + + + + sd_event_add_time + sd_event_source_get_time + sd_event_source_set_time + sd_event_source_get_time_accuracy + sd_event_source_set_time_accuracy + sd_event_source_get_time_clock + sd_event_time_handler_t + + Add a timer event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_time_handler_t) + sd_event_source *s + uint64_t usec + void *userdata + + + + int sd_event_add_time + sd_event *event + sd_event_source **source + clockid_t clock + uint64_t usec + uint64_t accuracy + sd_event_time_handler_t handler + void *userdata + + + + int sd_event_source_get_time + sd_event_source *source + uint64_t *usec + + + + int sd_event_source_set_time + sd_event_source *source + uint64_t usec + + + + int sd_event_source_get_time_accuracy + sd_event_source *source + uint64_t *usec + + + + int sd_event_source_set_time_accuracy + sd_event_source *source + uint64_t usec + + + + int sd_event_source_get_time_clock + sd_event_source *source + clockid_t *clock + + + + + + + Description + + sd_event_add_time() adds a new timer event source to an event loop. The event loop + object is specified in the event parameter, the event source object is returned in the + source parameter. The clock parameter takes a clock identifier, one + of CLOCK_REALTIME, CLOCK_MONOTONIC, CLOCK_BOOTTIME, + CLOCK_REALTIME_ALARM, or CLOCK_BOOTTIME_ALARM. See + timerfd_create2 for details + regarding the various types of clocks. The usec parameter specifies the earliest time, in + microseconds (µs), relative to the clock's epoch, when the timer shall be triggered. If a time already in the past + is specified (including 0), this timer source "fires" immediately and is ready to be + dispatched. If the parameter is specified as UINT64_MAX the timer event will never elapse, + which may be used as an alternative to explicitly disabling a timer event source with + sd_event_source_set_enabled3. The + accuracy parameter specifies an additional accuracy value in µs specifying how much the + timer event may be delayed. Use 0 to select the default accuracy (250ms). Use 1µs for maximum + accuracy. Consider specifying 60000000µs (1min) or larger for long-running events that may be delayed + substantially. Picking higher accuracy values allows the system to coalesce timer events more aggressively, + improving power efficiency. The handler parameter shall reference a function to call when + the timer elapses. The handler function will be passed the userdata pointer, which may be + chosen freely by the caller. The handler is also passed the configured trigger time, even if it is actually called + slightly later, subject to the specified accuracy value, the kernel timer slack (see + prctl2), and additional + scheduling latencies. To query the actual time the handler was called use + sd_event_now3. + + By default, the timer will elapse once + (SD_EVENT_ONESHOT), but this may be changed + with + sd_event_source_set_enabled3. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + SD_EVENT_ON mode was requested before. Note + that a timer event set to SD_EVENT_ON will + fire continuously unless its configured time is updated using + sd_event_source_set_time(). + + + To destroy an event source object use + sd_event_source_unref3, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. + + If the second parameter of + sd_event_add_time() is + NULL no reference to the event source object + is returned. In this case the event source is considered + "floating", and will be destroyed implicitly when the event loop + itself is destroyed. + + If the handler to + sd_event_add_time() is + NULL, and the event source fires, this will + be considered a request to exit the event loop. In this case, the + userdata parameter, cast to an integer, is + used for the exit code passed to + sd_event_exit3. + + Use CLOCK_BOOTTIME_ALARM and + CLOCK_REALTIME_ALARM to define event sources + that may wake up the system from suspend. + + In order to set up relative timers (that is, relative to the + current time), retrieve the current time via + sd_event_now3, + add the desired timespan to it, and use the result as + the usec parameter to + sd_event_add_time(). + + In order to set up repetitive timers (that is, timers that + are triggered in regular intervals), set up the timer normally, + for the first invocation. Each time the event handler is invoked, + update the timer's trigger time with + sd_event_source_set_time3 for the next timer + iteration, and reenable the timer using + sd_event_source_set_enabled(). To calculate + the next point in time to pass to + sd_event_source_set_time(), either use as + base the usec parameter passed to the timer + callback, or the timestamp returned by + sd_event_now(). In the former case timer + events will be regular, while in the latter case the scheduling + latency will keep accumulating on the timer. + + sd_event_source_get_time() retrieves + the configured time value of an event source created + previously with sd_event_add_time(). It takes + the event source object and a pointer to a variable to store the + time in, relative to the selected clock's epoch, in µs. + + sd_event_source_set_time() changes the + time of an event source created previously with + sd_event_add_time(). It takes the event + source object and a time relative to the selected clock's epoch, + in µs. + + sd_event_source_get_time_accuracy() + retrieves the configured accuracy value of an event source + created previously with sd_event_add_time(). It + takes the event source object and a pointer to a variable to store + the accuracy in. The accuracy is specified in µs. + + sd_event_source_set_time_accuracy() + changes the configured accuracy of a timer event source created + previously with sd_event_add_time(). It takes + the event source object and accuracy, in µs. + + sd_event_source_get_time_clock() + retrieves the configured clock of an event source created + previously with sd_event_add_time(). It takes + the event source object and a pointer to a variable to store the + clock identifier in. + + + + Return Value + + On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. + + + + Errors + + Returned values may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. + + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EOPNOTSUPP + + The selected clock is not supported by the event loop implementation. + + + + + -EDOM + + The passed event source is not a timer event source. + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + clock_gettime2, + timerfd_create2, + prctl2 + + + + diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml new file mode 100644 index 000000000..12716d7de --- /dev/null +++ b/man/sd_event_new.xml @@ -0,0 +1,246 @@ + + + + + + + + + sd_event_new + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_event_new + 3 + + + + sd_event_new + sd_event_default + sd_event_ref + sd_event_unref + sd_event_unrefp + sd_event_get_tid + sd_event + + Acquire and release an event loop object + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event sd_event; + + + int sd_event_new + sd_event **event + + + + int sd_event_default + sd_event **event + + + + sd_event *sd_event_ref + sd_event *event + + + + sd_event *sd_event_unref + sd_event *event + + + + void sd_event_unrefp + sd_event **event + + + + int sd_event_get_tid + sd_event *event + pid_t *tid + + + + + + + Description + + sd_event_new() allocates a new event + loop object. The event loop object is returned in the + event parameter. After use, drop + the returned reference with + sd_event_unref(). When the last reference is + dropped, the object is freed. + + sd_event_default() acquires a reference + to the default event loop object of the calling thread, possibly + allocating a new object if no default event loop object has been + allocated yet for the thread. After use, drop the returned + reference with sd_event_unref(). When the + last reference is dropped, the event loop is freed. If this + function is called while the object returned from a previous call + from the same thread is still referenced, the same object is + returned again, but the reference is increased by one. It is + recommended to use this call instead of + sd_event_new() in order to share event loop + objects between various components that are dispatched in the same + thread. All threads have exactly either zero or one default event loop + objects associated, but never more. + + After allocating an event loop object, add event sources to + it with + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3 + or + sd_event_add_defer3, + and then execute the event loop using + sd_event_run3. + + sd_event_ref() increases the reference + count of the specified event loop object by one. + + sd_event_unref() decreases the + reference count of the specified event loop object by one. If + the count hits zero, the object is freed. Note that it + is freed regardless of whether it is the default event loop object for a + thread or not. This means that allocating an event loop with + sd_event_default(), then releasing it, and + then acquiring a new one with + sd_event_default() will result in two + distinct objects. Note that, in order to free an event loop object, + all remaining event sources of the event loop also need to be + freed as each keeps a reference to it. + + sd_event_unrefp() is similar to + sd_event_unref() but takes a pointer to a + pointer to an sd_event object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, + in order to allocate an event loop object that is freed + automatically as the code block is left: + + { + __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL; + int r; + … + r = sd_event_default(&event); + if (r < 0) + fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r)); + … +} + + sd_event_ref(), + sd_event_unref() and + sd_event_unrefp() execute no operation if the + passed in event loop object is NULL. + + sd_event_get_tid() retrieves the thread + identifier ("TID") of the thread the specified event loop object + is associated with. This call is only supported for event loops + allocated with sd_event_default(), and + returns the identifier for the thread the event loop is the + default event loop of. See gettid2 + for more information on thread identifiers. + + + + Return Value + + On success, sd_event_new(), + sd_event_default() and + sd_event_get_tid() return 0 or a positive + integer. On failure, they return a negative errno-style error + code. sd_event_ref() always returns a pointer + to the event loop object passed + in. sd_event_unref() always returns + NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate the object. + + + + -EMFILE + + The maximum number of event loops has been allocated. + + + + + -ENXIO + + sd_event_get_tid() was + invoked on an event loop object that was not allocated with + sd_event_default(). + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_add_post3, + sd_event_add_exit3, + sd_event_run3, + gettid2 + + + + diff --git a/man/sd_event_run.xml b/man/sd_event_run.xml new file mode 100644 index 000000000..0f5bac584 --- /dev/null +++ b/man/sd_event_run.xml @@ -0,0 +1,190 @@ + + + + + + + + + sd_event_run + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + sd_event_run + 3 + + + + sd_event_run + sd_event_loop + + Run an event loop + + + + + #include <systemd/sd-event.h> + + + int sd_event_run + sd_event *event + uint64_t usec + + + + int sd_event_loop + sd_event *event + + + + + + Description + + sd_event_run() may be used to run a single + iteration of the event loop specified in the + event parameter. The function waits until an event to + process is available, and dispatches the registered handler for + it. The usec parameter specifies the + maximum time (in microseconds) to wait for an event. Use + (uint64_t) -1 to specify an infinite + timeout. + + sd_event_loop() invokes + sd_event_run() in a loop, thus implementing + the actual event loop. The call returns as soon as exiting was + requested using + sd_event_exit3. + + The event loop object event is + created with + sd_event_new3. + Events sources to wait for and their handlers may be registered + with + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_child3, + sd_event_add_defer3, + sd_event_add_post3 + and + sd_event_add_exit3. + + + For low-level control of event loop execution, use + sd_event_prepare3, + sd_event_wait3 + and + sd_event_dispatch3 + which are wrapped by sd_event_run(). Along + with + sd_event_get_fd3, + these functions allow integration of an + sd-event3 + event loop into foreign event loop implementations. + + + + Return Value + + On failure, these functions return a negative errno-style + error code. sd_event_run() returns a + positive, non-zero integer if an event source was dispatched, and + zero when the specified timeout hit before an event source has + seen any event, and hence no event source was + dispatched. sd_event_loop() returns the exit + code specified when invoking + sd_event_exit(). + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The event parameter is + invalid or NULL. + + + + -EBUSY + + The event loop object is not in the right + state (see + sd_event_prepare3 + for an explanation of possible states). + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + Other errors are possible, too. + + + + + + See Also + + + systemd1, + sd_event_new3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_add_exit3, + sd_event_add_post3, + sd_event_exit3, + sd_event_get_fd3, + sd_event_wait3, + GLib Main Event Loop. + + + + diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml index 6bc122e1c..279eab6bc 100644 --- a/man/sd_event_source_unref.xml +++ b/man/sd_event_source_unref.xml @@ -3,29 +3,29 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> sd_event_source_unref - elogind + systemd @@ -52,7 +52,7 @@ - #include <elogind/sd-event.h> + #include <systemd/sd-event.h> sd_event_source* sd_event_source_unref diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml new file mode 100644 index 000000000..d53090cac --- /dev/null +++ b/man/sd_event_wait.xml @@ -0,0 +1,356 @@ + + + + + + + + + sd_event_wait + systemd + + + + Developer + Tom + Gundersen + teg@jklm.no + + + + + + sd_event_wait + 3 + + + + sd_event_wait + sd_event_prepare + sd_event_dispatch + sd_event_get_state + sd_event_get_iteration + SD_EVENT_INITIAL + SD_EVENT_PREPARING + SD_EVENT_ARMED + SD_EVENT_PENDING + SD_EVENT_RUNNING + SD_EVENT_EXITING + SD_EVENT_FINISHED + + Low-level event loop operations + + + + + #include <systemd/sd-event.h> + + enum { + SD_EVENT_INITIAL, + SD_EVENT_PREPARING, + SD_EVENT_ARMED, + SD_EVENT_PENDING, + SD_EVENT_RUNNING, + SD_EVENT_EXITING, + SD_EVENT_FINISHED, +}; + + + int sd_event_prepare + sd_event *event + + + + int sd_event_wait + sd_event *event + uint64_t usec + + + + int sd_event_dispatch + sd_event *event + + + + int sd_event_get_state + sd_event *event + + + + int sd_event_get_iteration + sd_event *event + uint64_t *ret + + + + + + + Description + + The low-level sd_event_prepare(), + sd_event_wait() and + sd_event_dispatch() functions may be used to + execute specific phases of an event loop. See + sd_event_run3 + and + sd_event_loop3 + for higher-level functions that execute individual but complete + iterations of an event loop or run it continuously. + + sd_event_prepare() checks for pending + events and arms necessary timers. If any events are ready to be + processed ("pending"), it returns a positive, non-zero value, and the caller + should process these events with + sd_event_dispatch(). + + sd_event_dispatch() dispatches the + highest priority event source that has a pending event. On + success, sd_event_dispatch() returns either + zero, which indicates that no further event sources may be + dispatched and exiting of the event loop was requested via + sd_event_exit3; + or a positive non-zero value, which means that an event source was + dispatched and the loop returned to its initial state, and the + caller should initiate the next event loop iteration by invoking + sd_event_prepare() again. + + In case sd_event_prepare() returned + zero, sd_event_wait() should be called to + wait for further events or a timeout. If any events are ready to + be processed, it returns a positive, non-zero value, and the + events should be dispatched with + sd_event_dispatch(). Otherwise, the event + loop returned to its initial state and the next event loop + iteration should be initiated by invoking + sd_event_prepare() again. + + sd_event_get_state() may be used to + determine the state the event loop is currently in. It returns one + of the states described below. + + sd_event_get_iteration() may be used to determine the current iteration of the event + loop. It returns an unsigned 64bit integer containing a counter that increases monotonically with each iteration of + the event loop, starting with 0. The counter is increased at the time of the + sd_event_prepare() invocation. + + All five functions take, as the first argument, the event loop object event that has + been created with sd_event_new(). The timeout for sd_event_wait() is + specified in usec in microseconds. (uint64_t) -1 may be used to + specify an infinite timeout. + + + + State Machine + + The event loop knows the following states, that may be + queried with sd_event_get_state(). + + + + SD_EVENT_INITIAL + + The initial state the event loop is in, + before each event loop iteration. Use + sd_event_prepare() to transition the + event loop into the SD_EVENT_ARMED or + SD_EVENT_PENDING states. + + + + SD_EVENT_PREPARING + + An event source is currently being prepared, + i.e. the preparation handler is currently being executed, as + set with + sd_event_set_prepare3. This + state is only seen in the event source preparation handler + that is invoked from the + sd_event_prepare() call and is + immediately followed by SD_EVENT_ARMED or + SD_EVENT_PENDING. + + + + SD_EVENT_ARMED + + sd_event_prepare() has + been called and no event sources were ready to be + dispatched. Use sd_event_wait() to wait + for new events, and transition into + SD_EVENT_PENDING or back into + SD_EVENT_INITIAL. + + + + SD_EVENT_PENDING + + sd_event_prepare() or + sd_event_wait() have been called and + there were event sources with events pending. Use + sd_event_dispatch() to dispatch the + highest priority event source and transition back to + SD_EVENT_INITIAL, or + SD_EVENT_FINISHED. + + + + SD_EVENT_RUNNING + + A regular event source is currently being + dispatched. This state is only seen in the event source + handler that is invoked from the + sd_event_dispatch() call, and is + immediately followed by SD_EVENT_INITIAL + or SD_EVENT_FINISHED as soon the event + source handler returns. Note that during dispatching of exit + event sources the SD_EVENT_EXITING state + is seen instead. + + + + SD_EVENT_EXITING + + Similar to + SD_EVENT_RUNNING but is the state in + effect while dispatching exit event sources. It is followed by + SD_EVENT_INITIAL or + SD_EVENT_FINISHED as soon as the event + handler returns. + + + + SD_EVENT_FINISHED + + The event loop has exited. All exit event + sources have run. If the event loop is in this state it serves + no purpose anymore, and should be freed. + + + + + A simplified flow chart of the states and the calls to + transition between them is shown below. Note that + SD_EVENT_PREPARING, + SD_EVENT_RUNNING and + SD_EVENT_EXITING are not shown here. + + + INITIAL -<---<---<---<---<---<---<---<---<---<---<---<---\ + | | + | ^ + | | + v ret == 0 | + sd_event_prepare() >--->--->--->--->- ARMED | + | | ^ + | ret > 0 | | + | | | + v v ret == 0 | + PENDING <---<---<---<---<---< sd_event_wait() >--->--->--+ + | ret > 0 ^ + | | + | | + v | + sd_event_dispatch() >--->--->--->--->--->--->--->--->--->--->/ + | ret > 0 + | ret == 0 + | + v + FINISHED + + + + + Return Value + + On success, these functions return 0 or a positive integer. + On failure, they return a negative errno-style error code. In case + of sd_event_prepare() and + sd_event_wait(), a positive, non-zero return + code indicates that events are ready to be processed and zero + indicates that no events are ready. In case of + sd_event_dispatch(), a positive, non-zero + return code indicates that the event loop returned to its initial + state and zero indicates the event loop has + exited. sd_event_get_state() returns a + positive or zero state on success. + + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The event parameter is + invalid or NULL. + + + + -EBUSY + + The event loop object is not in the right + state. + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + + Other errors are possible, too. + + + + + + See Also + + + systemd1, + sd_event_new3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_add_exit3, + sd_event_add_post3, + sd_event_run3, + sd_event_get_fd3, + sd_event_source_set_prepare3 + + + + diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index e7326422b..cc1f2b30c 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -138,7 +138,7 @@ The sd_id128_get_machine(), sd_id128_get_machine_app_specific() sd_id128_get_boot() and sd_id128_get_invocation() interfaces are available as a shared library, which can be compiled and linked to with the - libsystemd libelogind pkg-config1 file. diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml new file mode 100644 index 000000000..0f4f274f6 --- /dev/null +++ b/man/sd_is_fifo.xml @@ -0,0 +1,228 @@ + + + + + + + + + sd_is_fifo + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_is_fifo + 3 + + + + sd_is_fifo + sd_is_socket + sd_is_socket_inet + sd_is_socket_unix + sd_is_socket_sockaddr + sd_is_mq + sd_is_special + Check the type of a file descriptor + + + + + #include <systemd/sd-daemon.h> + + + int sd_is_fifo + int fd + const char *path + + + + int sd_is_socket + int fd + int family + int type + int listening + + + + int sd_is_socket_inet + int fd + int family + int type + int listening + uint16_t port + + + + int sd_is_socket_sockaddr + int fd + int type + const struct sockaddr *addr + unsigned addr_len + int listening + + + + int sd_is_socket_unix + int fd + int type + int listening + const char *path + size_t length + + + + int sd_is_mq + int fd + const char *path + + + + int sd_is_special + int fd + const char *path + + + + + + + Description + + sd_is_fifo() may be called to check + whether the specified file descriptor refers to a FIFO or pipe. If + the path parameter is not + NULL, it is checked whether the FIFO is bound + to the specified file system path. + + sd_is_socket() may be called to check + whether the specified file descriptor refers to a socket. If the + family parameter is not + AF_UNSPEC, it is checked whether the socket + is of the specified family (AF_UNIX, + AF_INET, …). If the type + parameter is not 0, it is checked whether the socket is of the + specified type (SOCK_STREAM, + SOCK_DGRAM, …). If the + listening parameter is positive, it is + checked whether the socket is in accepting mode, i.e. + listen() has been called for it. If + listening is 0, it is checked whether the + socket is not in this mode. If the parameter is negative, no such + check is made. The listening parameter + should only be used for stream sockets and should be set to a + negative value otherwise. + + sd_is_socket_inet() is similar to + sd_is_socket(), but optionally checks the + IPv4 or IPv6 port number the socket is bound to, unless + port is zero. For this call + family must be passed as either + AF_UNSPEC, AF_INET, or + AF_INET6. + + sd_is_socket_sockaddr() is similar to + sd_is_socket_inet(), but checks if the socket is bound to the + address specified by addr. The + family specified by addr must be + either AF_INET or AF_INET6 and + addr_len must be large enough for that family. If + addr specifies a non-zero port, it is also checked if the + socket is bound to this port. In addition, for IPv6, if addr + specifies non-zero sin6_flowinfo or + sin6_scope_id, it is checked if the socket has the same + values. + + sd_is_socket_unix() is similar to + sd_is_socket() but optionally checks the + AF_UNIX path the socket is bound to, unless + the path parameter is + NULL. For normal file system + AF_UNIX sockets, set the + length parameter to 0. For Linux abstract + namespace sockets, set the length to the + size of the address, including the initial 0 byte, and set the + path to the initial 0 byte of the socket + address. + + sd_is_mq() may be called to check + whether the specified file descriptor refers to a POSIX message + queue. If the path parameter is not + NULL, it is checked whether the message queue + is bound to the specified name. + + sd_is_special() may be called to check + whether the specified file descriptor refers to a special file. If + the path parameter is not + NULL, it is checked whether the file + descriptor is bound to the specified file name. Special files in + this context are character device nodes and files in + /proc or /sys. + + + + Return Value + + On failure, these calls return a negative errno-style error + code. If the file descriptor is of the specified type and bound to + the specified address, a positive return value is returned, + otherwise zero. + + + + Notes + + + + Internally, these function use a combination of + fstat() and + getsockname() to check the file descriptor + type and where it is bound to. + + + + See Also + + systemd1, + sd-daemon3, + sd_listen_fds3, + systemd.service5, + systemd.socket5, + ip7, + ipv67, + unix7, + fifo7, + mq_overview7, + socket7. + + + + diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml new file mode 100644 index 000000000..0d3479efb --- /dev/null +++ b/man/sd_listen_fds.xml @@ -0,0 +1,257 @@ + + + + + + + + + sd_listen_fds + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_listen_fds + 3 + + + + sd_listen_fds + sd_listen_fds_with_names + SD_LISTEN_FDS_START + Check for file descriptors passed by the system manager + + + + + #include <systemd/sd-daemon.h> + + #define SD_LISTEN_FDS_START 3 + + + int sd_listen_fds + int unset_environment + + + + int sd_listen_fds_with_names + int unset_environment + char*** names + + + + + + Description + + sd_listen_fds() may be invoked by a + daemon to check for file descriptors passed by the service manager as + part of the socket-based activation logic. It returns the number + of received file descriptors. If no file descriptors have been + received, zero is returned. The first file descriptor may be found + at file descriptor number 3 + (i.e. SD_LISTEN_FDS_START), the remaining + descriptors follow at 4, 5, 6, …, if any. + + If a daemon receives more than one file descriptor, they + will be passed in the same order as configured in the systemd + socket unit file (see + systemd.socket5 + for details). Nonetheless, it is recommended to verify the correct + socket types before using them. To simplify this checking, the + functions + sd_is_fifo3, + sd_is_socket3, + sd_is_socket_inet3, + sd_is_socket_unix3 + are provided. In order to maximize flexibility, it is recommended + to make these checks as loose as possible without allowing + incorrect setups. i.e. often, the actual port number a socket is + bound to matters little for the service to work, hence it should + not be verified. On the other hand, whether a socket is a datagram + or stream socket matters a lot for the most common program logics + and should be checked. + + This function call will set the FD_CLOEXEC flag for all + passed file descriptors to avoid further inheritance to children + of the calling process. + + If multiple socket units activate the same service, the order + of the file descriptors passed to its main process is undefined. + If additional file descriptors have been passed to the service + manager using + sd_pid_notify_with_fds3's + FDSTORE=1 messages, these file descriptors are + passed last, in arbitrary order, and with duplicates + removed. + + If the unset_environment parameter is + non-zero, sd_listen_fds() will unset the + $LISTEN_FDS, $LISTEN_PID and + $LISTEN_FDNAMES environment variables before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + sd_listen_fds() will then return zero, but the + variables are no longer inherited by child processes. + + sd_listen_fds_with_names() is like + sd_listen_fds(), but optionally also returns + an array of strings with identification names for the passed file + descriptors, if that is available and the + names parameter is non-NULL. This + information is read from the $LISTEN_FDNAMES + variable, which may contain a colon-separated list of names. For + socket-activated services, these names may be configured with the + FileDescriptorName= setting in socket unit + files, see + systemd.socket5 + for details. For file descriptors pushed into the file descriptor + store (see above), the name is set via the + FDNAME= field transmitted via + sd_pid_notify_with_fds(). The primary usecase + for these names are services which accept a variety of file + descriptors which are not recognizable with functions like + sd_is_socket() alone, and thus require + identification via a name. It is recommended to rely on named file + descriptors only if identification via + sd_is_socket() and related calls is not + sufficient. Note that the names used are not unique in any + way. The returned array of strings has as many entries as file + descriptors have been received, plus a final NULL pointer + terminating the array. The caller needs to free the array itself + and each of its elements with libc's free() + call after use. If the names parameter is + NULL, the call is entirely equivalent to + sd_listen_fds(). + + Under specific conditions, the following automatic file + descriptor names are returned: + + + + <command>Special names</command> + + + + + + Name + Description + + + + + unknown + The process received no name for the specific file descriptor from the service manager. + + + + stored + The file descriptor originates in the service manager's per-service file descriptor store, and the FDNAME= field was absent when the file descriptor was submitted to the service manager. + + + + connection + The service was activated in per-connection style using Accept=yes in the socket unit file, and the file descriptor is the connection socket. + + + +
+ + + + + Return Value + + On failure, these calls returns a negative errno-style error + code. If + $LISTEN_FDS/$LISTEN_PID was + not set or was not correctly set for this daemon and hence no file + descriptors were received, 0 is returned. Otherwise, the number of + file descriptors passed is returned. The application may find them + starting with file descriptor SD_LISTEN_FDS_START, i.e. file + descriptor 3. + + + + Notes + + + + Internally, sd_listen_fds() checks + whether the $LISTEN_PID environment variable + equals the daemon PID. If not, it returns immediately. Otherwise, + it parses the number passed in the $LISTEN_FDS + environment variable, then sets the FD_CLOEXEC flag for the parsed + number of file descriptors starting from SD_LISTEN_FDS_START. + Finally, it returns the parsed + number. sd_listen_fds_with_names() does the + same but also parses $LISTEN_FDNAMES if + set. + + + + Environment + + + + $LISTEN_PID + $LISTEN_FDS + $LISTEN_FDNAMES + + Set by the service manager for supervised + processes that use socket-based activation. This environment + variable specifies the data + sd_listen_fds() and + sd_listen_fds_with_names() parses. See + above for details. + + + + + + See Also + + + systemd1, + sd-daemon3, + sd_is_fifo3, + sd_is_socket3, + sd_is_socket_inet3, + sd_is_socket_unix3, + sd_pid_notify_with_fds3, + daemon7, + systemd.service5, + systemd.socket5 + + + + diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml new file mode 100644 index 000000000..d91a9d526 --- /dev/null +++ b/man/sd_login_monitor_new.xml @@ -0,0 +1,287 @@ + + + + + + + + + sd_login_monitor_new + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_login_monitor_new + 3 + + + + sd_login_monitor_new + sd_login_monitor_unref + sd_login_monitor_unrefp + sd_login_monitor_flush + sd_login_monitor_get_fd + sd_login_monitor_get_events + sd_login_monitor_get_timeout + sd_login_monitor + Monitor login sessions, seats, users and virtual machines/containers + + + + + #include <systemd/sd-login.h> + + + int sd_login_monitor_new + const char *category + sd_login_monitor **ret + + + + sd_login_monitor *sd_login_monitor_unref + sd_login_monitor *m + + + + void sd_login_monitor_unrefp + sd_login_monitor **m + + + + int sd_login_monitor_flush + sd_login_monitor *m + + + + int sd_login_monitor_get_fd + sd_login_monitor *m + + + + int sd_login_monitor_get_events + sd_login_monitor *m + + + + int sd_login_monitor_get_timeout + sd_login_monitor *m + uint64_t *timeout_usec + + + + + + + Description + + sd_login_monitor_new() may be used to + monitor login sessions, users, seats, and virtual + machines/containers. Via a monitor object a file descriptor can be + integrated into an application defined event loop which is woken + up each time a user logs in, logs out or a seat is added or + removed, or a session, user, seat or virtual machine/container + changes state otherwise. The first parameter takes a string which + can be seat (to get only notifications about + seats being added, removed or changed), session + (to get only notifications about sessions being created or removed + or changed), uid (to get only notifications + when a user changes state in respect to logins) or + machine (to get only notifications when a + virtual machine or container is started or stopped). If + notifications shall be generated in all these conditions, + NULL may be passed. Note that in the future + additional categories may be defined. The second parameter returns + a monitor object and needs to be freed with the + sd_login_monitor_unref() call after + use. + + sd_login_monitor_unref() may be used to + destroy a monitor object. Note that this will invalidate any file + descriptor returned by + sd_login_monitor_get_fd(). + + sd_login_monitor_unrefp() is similar to + sd_login_monitor_unref() but takes a pointer + to a pointer to an sd_login_monitor object. This call + is useful in conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, in order to + allocate a login monitor object that is freed automatically as the + code block is left: + + { + __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL; + int r; + … + r = sd_login_monitor_default(&m); + if (r < 0) + fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r)); + … +} + + sd_login_monitor_flush() may be used to + reset the wakeup state of the monitor object. Whenever an event + causes the monitor to wake up the event loop via the file + descriptor this function needs to be called to reset the wake-up + state. If this call is not invoked, the file descriptor will + immediately wake up the event loop again. + + sd_login_monitor_unref() and + sd_login_monitor_unrefp() execute no + operation if the passed in monitor object is + NULL. + + sd_login_monitor_get_fd() may be used + to retrieve the file descriptor of the monitor object that may be + integrated in an application defined event loop, based around + poll2 + or a similar interface. The application should include the + returned file descriptor as wake-up source for the events mask + returned by sd_login_monitor_get_events(). It + should pass a timeout value as returned by + sd_login_monitor_get_timeout(). Whenever a + wake-up is triggered the file descriptor needs to be reset via + sd_login_monitor_flush(). An application + needs to reread the login state with a function like + sd_get_seats3 + or similar to determine what changed. + + sd_login_monitor_get_events() will + return the poll() mask to wait for. This + function will return a combination of POLLIN, + POLLOUT and similar to fill into the + .events field of struct + pollfd. + + sd_login_monitor_get_timeout() will + return a timeout value for usage in poll(). + This returns a value in microseconds since the epoch of + CLOCK_MONOTONIC for timing out + poll() in timeout_usec. + See + clock_gettime2 + for details about CLOCK_MONOTONIC. If there + is no timeout to wait for this will fill in (uint64_t) + -1 instead. Note that poll() takes + a relative timeout in milliseconds rather than an absolute timeout + in microseconds. To convert the absolute 'µs' timeout into + relative 'ms', use code like the following: + + uint64_t t; +int msec; +sd_login_monitor_get_timeout(m, &t); +if (t == (uint64_t) -1) + msec = -1; +else { + struct timespec ts; + uint64_t n; + clock_getttime(CLOCK_MONOTONIC, &ts); + n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; + msec = t > n ? (int) ((t - n + 999) / 1000) : 0; +} + + The code above does not do any error checking for brevity's + sake. The calculated msec integer can be passed + directly as poll()'s timeout + parameter. + + + + Return Value + + On success, + sd_login_monitor_new(), + sd_login_monitor_flush() and + sd_login_monitor_get_timeout() + return 0 or a positive integer. On success, + sd_login_monitor_get_fd() returns + a Unix file descriptor. On success, + sd_login_monitor_get_events() + returns a combination of POLLIN, + POLLOUT and suchlike. On failure, + these calls return a negative errno-style error + code. + + sd_login_monitor_unref() + always returns NULL. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). The specified category to + watch is not known. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_login_monitor_new(), + sd_login_monitor_unref(), + sd_login_monitor_flush(), + sd_login_monitor_get_fd(), + sd_login_monitor_get_events() and + sd_login_monitor_get_timeout() + interfaces are available as a shared library, which can be + compiled and linked to with the + libelogind pkg-config1 + file. + + + + See Also + + + systemd1, + sd-login3, + sd_get_seats3, + poll2, + clock_gettime2 + + + + diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml new file mode 100644 index 000000000..dc269b538 --- /dev/null +++ b/man/sd_pid_get_session.xml @@ -0,0 +1,359 @@ + + + + + + + + + sd_pid_get_session + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_pid_get_session + 3 + + + + sd_pid_get_session + sd_pid_get_unit + sd_pid_get_user_unit + sd_pid_get_owner_uid + sd_pid_get_machine_name + sd_pid_get_slice + sd_pid_get_user_slice + sd_pid_get_cgroup + sd_peer_get_session + sd_peer_get_unit + sd_peer_get_user_unit + sd_peer_get_owner_uid + sd_peer_get_machine_name + sd_peer_get_slice + sd_peer_get_user_slice + sd_peer_get_cgroup + Determine session, unit, owner of a session, + container/VM or slice of a specific PID or socket + peer + + + + + #include <systemd/sd-login.h> + + + int sd_pid_get_session + pid_t pid + char **session + + + + int sd_pid_get_unit + pid_t pid + char **unit + + + + int sd_pid_get_user_unit + pid_t pid + char **unit + + + + int sd_pid_get_owner_uid + pid_t pid + uid_t *uid + + + + int sd_pid_get_machine_name + pid_t pid + char **name + + + + int sd_pid_get_slice + pid_t pid + char **slice + + + + int sd_pid_get_user_slice + pid_t pid + char **slice + + + + int sd_pid_get_cgroup + pid_t pid + char **cgroup + + + + int sd_peer_get_session + int fd + char **session + + + + int sd_peer_get_unit + int fd + char **unit + + + + int sd_peer_get_user_unit + int fd + char **unit + + + + int sd_peer_get_owner_uid + int fd + uid_t *uid + + + + int sd_peer_get_machine_name + int fd + char **name + + + + int sd_peer_get_slice + int fd + char **slice + + + + int sd_peer_get_user_slice + int fd + char **slice + + + + int sd_peer_get_cgroup + int fd + char **cgroup + + + + + + Description + + sd_pid_get_session() may be used to + determine the login session identifier of a process identified by + the specified process identifier. The session identifier is a + short string, suitable for usage in file system paths. Note that + not all processes are part of a login session (e.g. system service + processes, user processes that are shared between multiple + sessions of the same user, or kernel threads). For processes not + being part of a login session, this function will fail with + -ENODATA. The returned string needs to be freed with the libc + free3 + call after use. + + sd_pid_get_unit() may be used to + determine the systemd system unit (i.e. system service or scope + unit) identifier of a process identified by the specified PID. The + unit name is a short string, suitable for usage in file system + paths. Note that not all processes are part of a system + unit/service (e.g. user processes, or kernel threads). For + processes not being part of a systemd system unit, this function + will fail with -ENODATA. (More specifically, this call will not + work for kernel threads.) The returned string needs to be freed + with the libc free3 + call after use. + + sd_pid_get_user_unit() may be used to + determine the systemd user unit (i.e. user service or scope unit) + identifier of a process identified by the specified PID. This is + similar to sd_pid_get_unit(), but applies to + user units instead of system units. + + sd_pid_get_owner_uid() may be used to + determine the Unix UID (user identifier) of the owner of the + session of a process identified the specified PID. Note that this + function will succeed for user processes which are shared between + multiple login sessions of the same user, whereas + sd_pid_get_session() will fail. For processes + not being part of a login session and not being a shared process + of a user, this function will fail with -ENODATA. + + sd_pid_get_machine_name() may be used + to determine the name of the VM or container is a member of. The + machine name is a short string, suitable for usage in file system + paths. The returned string needs to be freed with the libc + free3 + call after use. For processes not part of a VM or containers, this + function fails with -ENODATA. + + sd_pid_get_slice() may be used to + determine the slice unit the process is a member of. See + systemd.slice5 + for details about slices. The returned string needs to be freed + with the libc + free3 + call after use. + + Similarly, sd_pid_get_user_slice() + returns the user slice (as managed by the user's systemd instance) + of a process. + + sd_pid_get_cgroup() returns the control + group path of the specified process, relative to the root of the + hierarchy. Returns the path without trailing slash, except for + processes located in the root control group, where "/" is + returned. To find the actual control group path in the file system, + the returned path needs to be prefixed with + /sys/fs/cgroup/ (if the unified control group + setup is used), or + /sys/fs/cgroup/HIERARCHY/ + (if the legacy multi-hierarchy control group setup is used). + + If the pid parameter of any of these + functions is passed as 0, the operation is executed for the + calling process. + + The sd_peer_get_session(), + sd_peer_get_unit(), + sd_peer_get_user_unit(), + sd_peer_get_owner_uid(), + sd_peer_get_machine_name(), + sd_peer_get_slice(), + sd_peer_get_user_slice() and + sd_peer_get_cgroup() calls operate similar to + their PID counterparts, but operate on a connected AF_UNIX socket + and retrieve information about the connected peer process. Note + that these fields are retrieved via /proc, + and hence are not suitable for authorization purposes, as they are + subject to races. + + + + Return Value + + On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ESRCH + + The specified PID does not refer to a running + process. + + + + + -BADF + + The specified socket file descriptor was + invalid. + + + + -ENODATA + + The given field is not specified for the described + process or peer. + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The sd_pid_get_session(), + sd_pid_get_unit(), + sd_pid_get_user_unit(), + sd_pid_get_owner_uid(), + sd_pid_get_machine_name(), + sd_pid_get_slice(), + sd_pid_get_user_slice(), + sd_peer_get_session(), + sd_peer_get_unit(), + sd_peer_get_user_unit(), + sd_peer_get_owner_uid(), + sd_peer_get_machine_name(), + sd_peer_get_slice() and + sd_peer_get_user_slice() interfaces are + available as a shared library, which can be compiled and linked to + with the libelogind pkg-config1 + file. + + Note that the login session identifier as + returned by sd_pid_get_session() + is completely unrelated to the process session + identifier as returned by + getsid2. + + + + See Also + + + systemd1, + sd-login3, + sd_session_is_active3, + getsid2, + systemd.slice5, + systemd-machined.service8 + + + + diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml new file mode 100644 index 000000000..eb20c4494 --- /dev/null +++ b/man/sd_uid_get_state.xml @@ -0,0 +1,230 @@ + + + + + + + + + sd_uid_get_state + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_uid_get_state + 3 + + + + sd_uid_get_state + sd_uid_is_on_seat + sd_uid_get_sessions + sd_uid_get_seats + sd_uid_get_display + Determine login state of a specific Unix user ID + + + + + #include <systemd/sd-login.h> + + + int sd_uid_get_state + uid_t uid + char **state + + + + int sd_uid_is_on_seat + uid_t uid + int require_active + const char *seat + + + + int sd_uid_get_sessions + uid_t uid + int require_active + char ***sessions + + + + int sd_uid_get_seats + uid_t uid + int require_active + char ***seats + + + + int sd_uid_get_display + uid_t uid + char **session + + + + + + Description + + sd_uid_get_state() may be used to + determine the login state of a specific Unix user identifier. The + following states are currently known: offline + (user not logged in at all), lingering (user + not logged in, but some user services running), + online (user logged in, but not active, i.e. + has no session in the foreground), active (user + logged in, and has at least one active session, i.e. one session + in the foreground), closing (user not logged + in, and not lingering, but some processes are still around). In + the future additional states might be defined, client code should + be written to be robust in regards to additional state strings + being returned. The returned string needs to be freed with the + libc + free3 + call after use. + + sd_uid_is_on_seat() may be used to + determine whether a specific user is logged in or active on a + specific seat. Accepts a Unix user identifier and a seat + identifier string as parameters. The + require_active parameter is a boolean + value. If non-zero (true), this function will test if the user is + active (i.e. has a session that is in the foreground and accepting + user input) on the specified seat, otherwise (false) only if the + user is logged in (and possibly inactive) on the specified + seat. + + sd_uid_get_sessions() may be used to + determine the current sessions of the specified user. Accepts a + Unix user identifier as parameter. The + require_active parameter controls whether + the returned list shall consist of only those sessions where the + user is currently active (> 0), where the user is currently + online but possibly inactive (= 0), or logged in at all but + possibly closing the session (< 0). The call returns a + NULL terminated string array of session + identifiers in sessions which needs to be + freed by the caller with the libc + free3 + call after use, including all the strings referenced. If the + string array parameter is passed as NULL, the + array will not be filled in, but the return code still indicates + the number of current sessions. Note that instead of an empty + array NULL may be returned and should be + considered equivalent to an empty array. + + Similarly, sd_uid_get_seats() may be + used to determine the list of seats on which the user currently + has sessions. Similar semantics apply, however note that the user + may have multiple sessions on the same seat as well as sessions + with no attached seat and hence the number of entries in the + returned array may differ from the one returned by + sd_uid_get_sessions(). + + sd_uid_get_display() returns the name + of the "primary" session of a user. If the user has graphical + sessions, it will be the oldest graphical session. Otherwise, it + will be the oldest open session. + + + + Return Value + + On success, sd_uid_get_state() returns + 0 or a positive integer. If the test succeeds, + sd_uid_is_on_seat() returns a positive + integer; if it fails, 0. + sd_uid_get_sessions() and + sd_uid_get_seats() return the number of + entries in the returned arrays. + sd_uid_get_display() returns a non-negative + code on success. On failure, these calls return a negative + errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -ENODATA + + The given field is not specified for the described + user. + + + + + -ENXIO + + The specified seat is unknown. + + + + + -EINVAL + + An input parameter was invalid (out of range, + or NULL, where that is not accepted). This is also returned if + the passed user ID is 0xFFFF or 0xFFFFFFFF, which are + undefined on Linux. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + Functions described here are available as a shared library, + and can be compiled and linked to using the + libelogind pkg-config1 + entry. + + + + See Also + + + systemd1, + sd-login3, + sd_pid_get_owner_uid3 + + + +