diff options
35 files changed, 8337 insertions, 10 deletions
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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd-bus" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-bus</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Documentation</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-bus</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-bus</refname> + <refpurpose>A lightweight D-Bus IPC client library</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libelogind</command> + </cmdsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-bus.h</filename> provides an implementation of a D-Bus IPC client. See + <ulink url="https://www.freedesktop.org/software/dbus/" /> + for more information about D-Bus IPC. + </para> + + <para>See + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + for more information about the functions available.</para> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Julian Orth + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_add_match"> + + <refentryinfo> + <title>sd_bus_add_match</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <firstname>Julian</firstname> + <surname>Orth</surname> + <email>ju.orth@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_add_match</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_add_match</refname> + + <refpurpose>Add a match rule for message dispatching</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_add_match</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> + <paramdef>const char *<parameter>match</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>sd_bus_add_match()</function> adds a match rule used to dispatch + incoming messages. The syntax of the rule passed in + <parameter>match</parameter> is described in the + <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. + </para> + + <para> + The message <parameter>m</parameter> passed to the callback is only + borrowed, that is, the callback should not call + <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + on it. If the callback wants to hold on to the message beyond the lifetime + of the callback, it needs to call + <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to create a new reference. + </para> + + <para> + 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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + On success, <function>sd_bus_add_match()</function> returns 0 or a + positive integer. On failure, it returns a negative errno-style error + code. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_creds_get_pid"> + + <refentryinfo> + <title>sd_bus_creds_get_pid</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_creds_get_pid</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_creds_get_pid</refname> + <refname>sd_bus_creds_get_ppid</refname> + <refname>sd_bus_creds_get_tid</refname> + <refname>sd_bus_creds_get_uid</refname> + <refname>sd_bus_creds_get_euid</refname> + <refname>sd_bus_creds_get_suid</refname> + <refname>sd_bus_creds_get_fsuid</refname> + <refname>sd_bus_creds_get_gid</refname> + <refname>sd_bus_creds_get_egid</refname> + <refname>sd_bus_creds_get_sgid</refname> + <refname>sd_bus_creds_get_fsgid</refname> + <refname>sd_bus_creds_get_supplementary_gids</refname> + <refname>sd_bus_creds_get_comm</refname> + <refname>sd_bus_creds_get_tid_comm</refname> + <refname>sd_bus_creds_get_exe</refname> + <refname>sd_bus_creds_get_cmdline</refname> + <refname>sd_bus_creds_get_cgroup</refname> + <refname>sd_bus_creds_get_unit</refname> + <refname>sd_bus_creds_get_slice</refname> + <refname>sd_bus_creds_get_user_unit</refname> + <refname>sd_bus_creds_get_user_slice</refname> + <refname>sd_bus_creds_get_session</refname> + <refname>sd_bus_creds_get_owner_uid</refname> + <refname>sd_bus_creds_has_effective_cap</refname> + <refname>sd_bus_creds_has_permitted_cap</refname> + <refname>sd_bus_creds_has_inheritable_cap</refname> + <refname>sd_bus_creds_has_bounding_cap</refname> + <refname>sd_bus_creds_get_selinux_context</refname> + <refname>sd_bus_creds_get_audit_session_id</refname> + <refname>sd_bus_creds_get_audit_login_uid</refname> + <refname>sd_bus_creds_get_tty</refname> + <refname>sd_bus_creds_get_unique_name</refname> + <refname>sd_bus_creds_get_well_known_names</refname> + <refname>sd_bus_creds_get_description</refname> + + <refpurpose>Retrieve fields from a credentials object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_pid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>pid_t *<parameter>pid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_ppid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>pid_t *<parameter>ppid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_tid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>pid_t *<parameter>tid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_uid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_euid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_suid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_fsuid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_gid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>gid_t *<parameter>gid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_egid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>gid_t *<parameter>gid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_sgid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>gid_t *<parameter>gid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_fsgid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>gid_t *<parameter>gid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_supplementary_gids</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const gid_t **<parameter>gids</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_comm</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>comm</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_tid_comm</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>comm</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_exe</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>exe</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_cmdline</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>char ***<parameter>cmdline</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_cgroup</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>cgroup</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_unit</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_slice</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_user_unit</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_user_slice</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_session</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_owner_uid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_has_effective_cap</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>int <parameter>capability</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_has_permitted_cap</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>int <parameter>capability</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_has_inheritable_cap</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>int <parameter>capability</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_has_bounding_cap</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>int <parameter>capability</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_selinux_context</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>context</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_audit_session_id</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uint32_t *<parameter>sessionid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_audit_login_uid</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>uid_t *<parameter>loginuid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_tty</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>tty</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_unique_name</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_well_known_names</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>char ***<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_get_description</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + <paramdef>const char **<parameter>name</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These functions return credential information from an + <parameter>sd_bus_creds</parameter> object. Credential objects may + be created with + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case they describe the credentials of the process + identified by the specified PID, with + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case they describe the credentials of a bus peer + identified by the specified bus name, with + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case they describe the credentials of the creator of a + bus, or with + <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + in which case they describe the credentials of the sender of the + message.</para> + + <para>Not all credential fields are part of every + <literal>sd_bus_creds</literal> object. Use + <citerefentry><refentrytitle>sd_bus_creds_get_mask</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to determine the mask of fields available.</para> + + <para><function>sd_bus_creds_get_pid()</function> will retrieve + the PID (process identifier). Similarly, + <function>sd_bus_creds_get_ppid()</function> will retrieve the + parent PID. Note that PID 1 has no parent process, in which case + -ENXIO is returned.</para> + + <para><function>sd_bus_creds_get_tid()</function> will retrieve the + TID (thread identifier).</para> + + <para><function>sd_bus_creds_get_uid()</function> will retrieve + the numeric UID (user identifier). Similarly, + <function>sd_bus_creds_get_euid()</function> returns the effective + UID, <function>sd_bus_creds_get_suid()</function> the saved UID + and <function>sd_bus_creds_get_fsuid()</function> the file system + UID.</para> + + <para><function>sd_bus_creds_get_gid()</function> will retrieve the + numeric GID (group identifier). Similarly, + <function>sd_bus_creds_get_egid()</function> returns the effective + GID, <function>sd_bus_creds_get_sgid()</function> the saved GID + and <function>sd_bus_creds_get_fsgid()</function> the file system + GID.</para> + + <para><function>sd_bus_creds_get_supplementary_gids()</function> + will retrieve the supplementary GIDs list.</para> + + <para><function>sd_bus_creds_get_comm()</function> will retrieve the + comm field (truncated name of the executable, as stored in + <filename>/proc/<replaceable>pid</replaceable>/comm</filename>). + </para> + + <para><function>sd_bus_creds_get_tid_comm()</function> will retrieve + the comm field of the thread (as stored in + <filename>/proc/<replaceable>pid</replaceable>/task/<replaceable>tid</replaceable>/comm</filename>). + </para> + + <para><function>sd_bus_creds_get_exe()</function> will retrieve + the path to the program executable (as stored in the + <filename>/proc/<replaceable>pid</replaceable>/exe</filename> + link, but with the <literal> (deleted)</literal> suffix removed). Note + that kernel threads do not have an executable path, in which case + -ENXIO is returned.</para> + + <para><function>sd_bus_creds_get_cmdline()</function> will + retrieve an array of command line arguments (as stored in + <filename>/proc/<replaceable>pid</replaceable>/cmdline</filename>). Note + that kernel threads do not have a command line, in which case + -ENXIO is returned.</para> + + <para><function>sd_bus_creds_get_cgroup()</function> will retrieve + the control group path. See <ulink + url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>. + </para> + + <para><function>sd_bus_creds_get_unit()</function> will retrieve + the systemd unit name (in the system instance of systemd) that the + process is a part of. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For + processes that are not part of a unit, returns -ENXIO. + </para> + + <para><function>sd_bus_creds_get_user_unit()</function> will + retrieve the systemd unit name (in the user instance of systemd) + that the process is a part of. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For + processes that are not part of a user unit, returns -ENXIO. + </para> + + <para><function>sd_bus_creds_get_slice()</function> will retrieve + the systemd slice (a unit in the system instance of systemd) that + the process is a part of. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Similarly, + <function>sd_bus_creds_get_user_slice()</function> retrieves the + systemd slice of the process, in the user instance of systemd. + </para> + + <para><function>sd_bus_creds_get_session()</function> will + retrieve the identifier of the login session that the process is + a part of. See + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. For + processes that are not part of a session, returns -ENXIO. + </para> + + <para><function>sd_bus_creds_get_owner_uid()</function> will + retrieve the numeric UID (user identifier) of the user who owns + the login session that the process is a part of. See + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + For processes that are not part of a session, returns -ENXIO. + </para> + + <para><function>sd_bus_creds_has_effective_cap()</function> will check whether the capability specified by + <parameter>capability</parameter> 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 <citerefentry + project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the + <varname>AmbientCapabilities=</varname> and <varname>CapabilityBoundingSet=</varname> settings in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para><function>sd_bus_creds_has_permitted_cap()</function> is + similar to <function>sd_bus_creds_has_effective_cap()</function>, + but will check the permitted capabilities mask.</para> + + <para><function>sd_bus_creds_has_inheritable_cap()</function> is + similar to <function>sd_bus_creds_has_effective_cap()</function>, + but will check the inheritable capabilities mask.</para> + + <para><function>sd_bus_creds_has_bounding_cap()</function> is + similar to <function>sd_bus_creds_has_effective_cap()</function>, + but will check the bounding capabilities mask.</para> + + <para><function>sd_bus_creds_get_selinux_context()</function> will + retrieve the SELinux security context (label) of the process.</para> + + <para><function>sd_bus_creds_get_audit_session_id()</function> + will retrieve the audit session identifier of the process. Returns + -ENXIO for processes that are not part of an audit session.</para> + + <para><function>sd_bus_creds_get_audit_login_uid()</function> 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.</para> + + <para><function>sd_bus_creds_get_tty()</function> will retrieve + the controlling TTY, without the prefixing "/dev/". Returns -ENXIO + for processes that have no controlling TTY.</para> + + <para><function>sd_bus_creds_get_unique_name()</function> will + retrieve the D-Bus unique name. See <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The + D-Bus specification</ulink>.</para> + + <para><function>sd_bus_creds_get_well_known_names()</function> will + retrieve the set of D-Bus well-known names. See <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">The + D-Bus specification</ulink>.</para> + + <para><function>sd_bus_creds_get_description()</function> 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 + <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call.</para> + + <para>All functions that take a <parameter>const + char**</parameter> parameter will store the answer there as an + address of a NUL-terminated string. It will be valid as long as + <parameter>c</parameter> remains valid, and should not be freed or + modified by the caller.</para> + + <para>All functions that take a <parameter>char***</parameter> + 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 + <parameter>c</parameter> remains valid, and should not be freed or + modified by the caller.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error code. + </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The given field is not available in the + credentials object <parameter>c</parameter>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The given field is not specified for the described + process or peer. This will be returned by + <function>sd_bus_get_unit()</function>, + <function>sd_bus_get_slice()</function>, + <function>sd_bus_get_user_unit()</function>, + <function>sd_bus_get_user_slice()</function>, + <function>sd_bus_get_session()</function>, and + <function>sd_bus_get_owner_uid()</function> 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 + <function>sd_bus_creds_get_exe()</function> and + <function>sd_bus_creds_get_cmdline()</function> for kernel + threads (since these are not started from an executable binary, + nor have a command line), and by + <function>sd_bus_creds_get_audit_session_id()</function> and + <function>sd_bus_creds_get_audit_login_uid()</function> when + the process is not part of an audit session, and + <function>sd_bus_creds_get_tty()</function> if the process has + no controlling TTY. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified pointer parameter is <constant>NULL</constant>. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_creds_get_pid()</function> and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + <constant>libelogind</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_creds_new_from_pid"> + + <refentryinfo> + <title>sd_bus_creds_new_from_pid</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_creds_new_from_pid</refname> + <refname>sd_bus_creds_get_mask</refname> + <refname>sd_bus_creds_get_augmented_mask</refname> + <refname>sd_bus_creds_ref</refname> + <refname>sd_bus_creds_unref</refname> + <refname>sd_bus_creds_unrefp</refname> + + <refpurpose>Retrieve credentials object for the specified PID</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef> + <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef> + <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef> + <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + <para> + <constant>SD_BUS_CREDS_PID</constant>, + <constant>SD_BUS_CREDS_PPID</constant>, + <constant>SD_BUS_CREDS_TID</constant>, + <constant>SD_BUS_CREDS_UID</constant>, + <constant>SD_BUS_CREDS_EUID</constant>, + <constant>SD_BUS_CREDS_SUID</constant>, + <constant>SD_BUS_CREDS_FSUID</constant>, + <constant>SD_BUS_CREDS_GID</constant>, + <constant>SD_BUS_CREDS_EGID</constant>, + <constant>SD_BUS_CREDS_SGID</constant>, + <constant>SD_BUS_CREDS_FSGID</constant>, + <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>, + <constant>SD_BUS_CREDS_COMM</constant>, + <constant>SD_BUS_CREDS_TID_COMM</constant>, + <constant>SD_BUS_CREDS_EXE</constant>, + <constant>SD_BUS_CREDS_CMDLINE</constant>, + <constant>SD_BUS_CREDS_CGROUP</constant>, + <constant>SD_BUS_CREDS_UNIT</constant>, + <constant>SD_BUS_CREDS_SLICE</constant>, + <constant>SD_BUS_CREDS_USER_UNIT</constant>, + <constant>SD_BUS_CREDS_USER_SLICE</constant>, + <constant>SD_BUS_CREDS_SESSION</constant>, + <constant>SD_BUS_CREDS_OWNER_UID</constant>, + <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>, + <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>, + <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>, + <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>, + <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>, + <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>, + <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>, + <constant>SD_BUS_CREDS_TTY</constant>, + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>, + <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, + <constant>SD_BUS_CREDS_DESCRIPTION</constant>, + <constant>SD_BUS_CREDS_AUGMENT</constant>, + <constant>_SD_BUS_CREDS_ALL</constant> + </para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_creds_new_from_pid()</function> creates a + new credentials object and fills it with information about the + process <parameter>pid</parameter>. The pointer to this object + will be stored in the <parameter>ret</parameter> pointer. Note that + credential objects may also be created and retrieved via + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>The information that will be stored is determined by + <parameter>creds_mask</parameter>. It may contain a subset of ORed + constants <constant>SD_BUS_CREDS_PID</constant>, + <constant>SD_BUS_CREDS_PPID</constant>, + <constant>SD_BUS_CREDS_TID</constant>, + <constant>SD_BUS_CREDS_UID</constant>, + <constant>SD_BUS_CREDS_EUID</constant>, + <constant>SD_BUS_CREDS_SUID</constant>, + <constant>SD_BUS_CREDS_FSUID</constant>, + <constant>SD_BUS_CREDS_GID</constant>, + <constant>SD_BUS_CREDS_EGID</constant>, + <constant>SD_BUS_CREDS_SGID</constant>, + <constant>SD_BUS_CREDS_FSGID</constant>, + <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>, + <constant>SD_BUS_CREDS_COMM</constant>, + <constant>SD_BUS_CREDS_TID_COMM</constant>, + <constant>SD_BUS_CREDS_EXE</constant>, + <constant>SD_BUS_CREDS_CMDLINE</constant>, + <constant>SD_BUS_CREDS_CGROUP</constant>, + <constant>SD_BUS_CREDS_UNIT</constant>, + <constant>SD_BUS_CREDS_SLICE</constant>, + <constant>SD_BUS_CREDS_USER_UNIT</constant>, + <constant>SD_BUS_CREDS_USER_SLICE</constant>, + <constant>SD_BUS_CREDS_SESSION</constant>, + <constant>SD_BUS_CREDS_OWNER_UID</constant>, + <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>, + <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>, + <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>, + <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>, + <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>, + <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>, + <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>, + <constant>SD_BUS_CREDS_TTY</constant>, + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>, + <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and + <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special + value <constant>_SD_BUS_CREDS_ALL</constant> to request all + supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant> + constant may not be ORed into the mask for invocations of + <function>sd_bus_creds_new_from_pid()</function>.</para> + + <para>Fields can be retrieved from the credentials object using + <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and other functions which correspond directly to the constants + listed above.</para> + + <para>A mask of fields which were actually successfully retrieved + can be retrieved with + <function>sd_bus_creds_get_mask()</function>. If the credentials + object was created with + <function>sd_bus_creds_new_from_pid()</function>, this will be a + subset of fields requested in <parameter>creds_mask</parameter>. + </para> + + <para>Similar to <function>sd_bus_creds_get_mask()</function>, the + function <function>sd_bus_creds_get_augmented_mask()</function> + 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 + <function>sd_bus_creds_new_from_pid()</function>, this mask will be + identical to the mask returned by + <function>sd_bus_creds_get_mask()</function>. However, for + credential objects retrieved via + <function>sd_bus_get_name_creds()</function>, 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 + <filename>/proc</filename>. Similarly, for credential objects + retrieved via <function>sd_bus_get_owner_creds()</function>, 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 + <function>sd_bus_message_get_creds()</function>, 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 + <function>sd_bus_creds_get_augmented_mask()</function> is always a + subset of (or identical to) the mask returned by + <function>sd_bus_creds_get_mask()</function> 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. + </para> + + <para><function>sd_bus_creds_ref()</function> creates a new + reference to the credentials object <parameter>c</parameter>. This + object will not be destroyed until + <function>sd_bus_creds_unref()</function> has been called as many + times plus once more. Once the reference count has dropped to zero, + <parameter>c</parameter> cannot be used anymore, so further + calls to <function>sd_bus_creds_ref(c)</function> or + <function>sd_bus_creds_unref(c)</function> are illegal.</para> + + <para><function>sd_bus_creds_unref()</function> destroys a reference + to <parameter>c</parameter>.</para> + + <para><function>sd_bus_creds_unrefp()</function> is similar to + <function>sd_bus_creds_unref()</function> but takes a pointer to a + pointer to an <type>sd_bus_creds</type> object. This call is useful in + conjunction with GCC's and LLVM's <ulink + url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up + Variable Attribute</ulink>. Note that this function is defined as + inline function.</para> + + <para><function>sd_bus_creds_ref()</function>, + <function>sd_bus_creds_unref()</function> and + <function>sd_bus_creds_unrefp()</function> execute no operation if + the passed in bus credentials object is + <constant>NULL</constant>.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_creds_new_from_pid()</function> + returns 0 or a positive integer. On failure, it returns a negative + errno-style error code.</para> + + <para><function>sd_bus_creds_get_mask()</function> returns the + mask of successfully acquired fields.</para> + + <para><function>sd_bus_creds_get_augmented_mask()</function> + returns the mask of fields that have been augmented from data in + <filename>/proc</filename>, and are thus not suitable for + authorization decisions.</para> + + <para><function>sd_bus_creds_ref()</function> always returns the + argument.</para> + + <para><function>sd_bus_creds_unref()</function> always returns + <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>Reference ownership</title> + + <para>Function <function>sd_bus_creds_new_from_pid()</function> + creates a new object and the caller owns the sole reference. When + not needed anymore, this reference should be destroyed with + <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ESRCH</constant></term> + + <listitem><para>Specified <parameter>pid</parameter> could not + be found.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid + (<constant>NULL</constant> in case of output + parameters).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EOPNOTSUPP</constant></term> + + <listitem><para>One of the requested fields is unknown to the local system.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_creds_new_from_pid()</function> and the + other calls described here are available as a shared library, + which can be compiled and linked to with the + <constant>libelogind</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_default"> + + <refentryinfo> + <title>sd_bus_default</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_default</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_default</refname> + <refname>sd_bus_default_user</refname> + <refname>sd_bus_default_system</refname> + + <refname>sd_bus_open</refname> + <refname>sd_bus_open_user</refname> + <refname>sd_bus_open_system</refname> + <refname>sd_bus_open_system_remote</refname> + <refname>sd_bus_open_system_machine</refname> + + <refpurpose>Acquire a connection to a system or user bus</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_default</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_default_user</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_default_system</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_user</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_system</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_system_remote</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>host</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_system_machine</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>machine</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_default()</function> 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 + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + 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.</para> + + <para><function>sd_bus_default_user()</function> returns a user + bus connection object associated with the calling thread. + <function>sd_bus_default_system()</function> is similar, but + connects to the system bus. Note that + <function>sd_bus_default()</function> is identical to these two + calls, depending on the execution context.</para> + + <para><function>sd_bus_open()</function> creates a new, + independent bus connection to the user bus when invoked in user + context, or the system bus + otherwise. <function>sd_bus_open_user()</function> is similar, but + connects only to the user bus. + <function>sd_bus_open_system()</function> does the same, but + connects to the system bus. In contrast to + <function>sd_bus_default()</function>, + <function>sd_bus_default_user()</function>, and + <function>sd_bus_default_system()</function>, 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 <function>sd_bus_default()</function>, + <function>sd_bus_default_user()</function> and + <function>sd_bus_default_system()</function> to connect to the + user or system buses.</para> + + <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment + variable is set + (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>), + it will be used as the address of the user bus. This variable can + contain multiple addresses separated by <literal>;</literal>. If + this variable is not set, a suitable default for the default user + D-Bus instance will be used.</para> + + <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> + environment variable is set, it will be used as the address of the + system bus. This variable uses the same syntax as + <varname>$DBUS_SESSION_BUS_ADDRESS</varname>. If this variable is + not set, a suitable default for the default system D-Bus instance + will be used.</para> + + <para><function>sd_bus_open_system_remote()</function> connects to + the system bus on the specified <parameter>host</parameter> using + <citerefentry + project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <parameter>host</parameter> + consists of an optional user name followed by the + <literal>@</literal> symbol, and the hostname. + </para> + + <para><function>sd_bus_open_system_machine()</function> connects + to the system bus in the specified <parameter>machine</parameter>, + where <parameter>machine</parameter> is the name of a local + container. See + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for more information about the "machine" concept. Note that + connections into local containers are only available to privileged + processes at this time.</para> + + <para>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 + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and to connect it with + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + </refsect1> + + <refsect1> + <title>Reference ownership</title> + <para>The functions <function>sd_bus_open()</function>, + <function>sd_bus_open_user()</function>, + <function>sd_bus_open_system()</function>, + <function>sd_bus_open_system_remote()</function>, and + <function>sd_bus_open_system_machine()</function> return a new + connection object and the caller owns the sole reference. When not + needed anymore, this reference should be destroyed with + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para>The functions <function>sd_bus_default()</function>, + <function>sd_bus_default_user()</function> and + <function>sd_bus_default_system()</function> do not necessarily + create a new object, but increase the connection reference of an + existing connection object by one. Use + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to drop the reference.</para> + + <para>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. <function>sd_bus_flush()</function> may be used to write + all outgoing queued messages so they drop their references. To + flush the unread incoming messages, use + <function>sd_bus_close()</function>, which will also close the bus + connection. When using the default bus logic, it is a good idea to + first invoke <function>sd_bus_flush()</function> followed by + <function>sd_bus_close()</function> when a thread or process + terminates, and thus its bus connection object should be + freed.</para> + + <para>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 <function>sd_bus_flush()</function> nor + <function>sd_bus_close()</function> 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 <function>sd_bus_open_system()</function> + instead of <function>sd_bus_default_system()</function> and + related calls.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive + integer. On failure, these calls return a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The specified parameters are invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESOCKTNOSUPPORT</constant></term> + + <listitem><para>The protocol version required to connect to the selected bus is not supported.</para></listitem> + </varlistentry> + </variablelist> + + <para>In addition, any further connection-related errors may be + by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_open_user()</function> and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + <constant>libelogind</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_error"> + + <refentryinfo> + <title>sd_bus_error</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_error</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_error</refname> + <refname>SD_BUS_ERROR_MAKE_CONST</refname> + <refname>SD_BUS_ERROR_NULL</refname> + <refname>sd_bus_error_free</refname> + <refname>sd_bus_error_set</refname> + <refname>sd_bus_error_setf</refname> + <refname>sd_bus_error_set_const</refname> + <refname>sd_bus_error_set_errno</refname> + <refname>sd_bus_error_set_errnof</refname> + <refname>sd_bus_error_set_errnofv</refname> + <refname>sd_bus_error_get_errno</refname> + <refname>sd_bus_error_copy</refname> + <refname>sd_bus_error_is_set</refname> + <refname>sd_bus_error_has_name</refname> + + <refpurpose>sd-bus error handling</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcsynopsisinfo>typedef struct { + const char *name; + const char *message; + … +} sd_bus_error;</funcsynopsisinfo> + + <para> + <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant> + </para> + <para> + <constant>SD_BUS_ERROR_NULL</constant> + </para> + + <funcprototype> + <funcdef>void <function>sd_bus_error_free</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_set</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>const char *<parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_setf</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_set_const</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>const char *<parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_set_errno</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>va_list ap</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_get_errno</function></funcdef> + <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_copy</function></funcdef> + <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef> + <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_is_set</function></funcdef> + <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_error_has_name</function></funcdef> + <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <structname>sd_bus_error</structname> 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 + <structfield>name</structfield> field contains a short identifier + of an error. It should follow the rules for error names described + in the D-Bus specification, subsection <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid + Names</ulink>. A number of common, standardized error names are + described in + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but additional domain-specific errors may be defined by + applications. The <structfield>message</structfield> field usually + contains a human-readable string describing the details, but might + be NULL. An unset <structname>sd_bus_error</structname> structure + should have both fields initialized to NULL. Set an error + structure to <constant>SD_BUS_ERROR_NULL</constant> in order to + reset both fields to NULL. When no longer necessary, resources + held by the <structname>sd_bus_error</structname>structure should + be destroyed with <function>sd_bus_error_free()</function>.</para> + + <para><function>sd_bus_error_set()</function> 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 + <varname>errno</varname>-like negative value (see <citerefentry + project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + determined from the specified error name. Various well-known + D-Bus errors are converted to well-known <varname>errno</varname> + counterparts, and the other ones to <constant>-EIO</constant>. See + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for a list of well-known error names. Additional error mappings + may be defined with + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If + <parameter>e</parameter> is NULL, no error structure is initialized, + but the error is still converted into an + <varname>errno</varname>-style error. If + <parameter>name</parameter> is <constant>NULL</constant>, it is + assumed that no error occurred, and 0 is returned. This means that + this function may be conveniently used in a + <function>return</function> statement. If + <parameter>message</parameter> 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 + <constant>SD_BUS_ERROR_NO_MEMORY</constant> 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 + <function>sd_bus_error_free()</function> first.</para> + + <para><function>sd_bus_error_setf()</function> is similar to + <function>sd_bus_error_set()</function>, but takes a <citerefentry + project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string and corresponding arguments to generate the + <structfield>message</structfield> field.</para> + + <para><function>sd_bus_error_set_const()</function> is similar to + <function>sd_bus_error_set()</function>, but the string parameters + are not copied internally, and must hence remain constant and + valid for the lifetime of <parameter>e</parameter>. 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 + <function>sd_bus_error_set()</function> can, as described + above. Alternatively, the + <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used + to generate a literal, constant bus error structure + on-the-fly.</para> + + <para><function>sd_bus_error_set_errno()</function> will set + <structfield>name</structfield> from an + <varname>errno</varname>-like value that is converted to a D-Bus + error. <citerefentry + project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> + will be used to set <structfield>message</structfield>. Well-known + D-Bus error names will be used for <structfield>name</structfield> + if applicable, otherwise a name in the + <literal>System.Error.</literal> 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 <function>return</function> statements. This + call might fail due to lack of memory, in which case an + <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead, + and -ENOMEM is returned.</para> + + <para><function>sd_bus_error_set_errnof()</function> is similar to + <function>sd_bus_error_set_errno()</function>, but in addition to + <parameter>error</parameter>, takes a <citerefentry + project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string and corresponding arguments. The + <structfield>message</structfield> field will be generated from + <parameter>format</parameter> and the arguments.</para> + + <para><function>sd_bus_error_set_errnofv()</function> is similar to + <function>sd_bus_error_set_errnof()</function>, but takes the + format string parameters as <citerefentry + project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry> + parameter list.</para> + + <para><function>sd_bus_error_get_errno()</function> converts the + <structfield>name</structfield> field of an error structure to an + <varname>errno</varname>-like (positive) value using the same + rules as <function>sd_bus_error_set()</function>. If + <parameter>e</parameter> is <constant>NULL</constant>, 0 will be + returned.</para> + + <para><function>sd_bus_error_copy()</function> will initialize + <parameter>dst</parameter> using the values in + <parameter>e</parameter>. If the strings in + <parameter>e</parameter> were set using + <function>sd_bus_set_error_const()</function>, they will be shared. + Otherwise, they will be copied. Returns a converted + <varname>errno</varname>-like, negative error code.</para> + + <para><function>sd_bus_error_is_set()</function> will return a + non-zero value if <parameter>e</parameter> is + non-<constant>NULL</constant> and an error has been set, + <constant>false</constant> otherwise.</para> + + <para><function>sd_bus_error_has_name()</function> will return a + non-zero value if <parameter>e</parameter> is + non-<constant>NULL</constant> and an error with the same + <parameter>name</parameter> has been set, + <constant>false</constant> otherwise.</para> + + <para><function>sd_bus_error_free()</function> will destroy + resources held by <parameter>e</parameter>. The parameter itself + will not be deallocated, and must be <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d + 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.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The functions <function>sd_bus_error_set()</function>, + <function>sd_bus_error_setf()</function>, and + <function>sd_bus_error_set_const()</function>, when successful, + return the negative errno value corresponding to the + <parameter>name</parameter> parameter. The functions + <function>sd_bus_error_set_errno()</function>, + <function>sd_bus_error_set_errnof()</function> and + <function>sd_bus_error_set_errnofv()</function>, when successful, + return the negative value of the <parameter>error</parameter> + parameter. If an error occurs, one of the negative error values + listed below will be returned.</para> + + <para><function>sd_bus_error_get_errno()</function> returns + <constant>false</constant> when <parameter>e</parameter> is + <constant>NULL</constant>, and a positive errno value mapped from + <parameter>e->name</parameter> otherwise.</para> + + <para><function>sd_bus_error_copy()</function> returns 0 or a + positive integer on success, and a negative error value converted + from the error name otherwise.</para> + + <para><function>sd_bus_error_is_set()</function> returns a + non-zero value when <parameter>e</parameter> and the + <structfield>name</structfield> field are + non-<constant>NULL</constant>, zero otherwise.</para> + + <para><function>sd_bus_error_has_name()</function> returns a + non-zero value when <parameter>e</parameter> is + non-<constant>NULL</constant> and the + <structfield>name</structfield> field is equal to + <parameter>name</parameter>, zero otherwise.</para> + </refsect1> + + <refsect1> + <title>Reference ownership</title> + <para><structname>sd_bus_error</structname> is not reference + counted. Users should destroy resources held by it by calling + <function>sd_bus_error_free()</function>. 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 <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + the memory held by the structure itself after freeing its contents + with <function>sd_bus_error_free()</function>.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Error was already set in + <structname>sd_bus_error</structname> structure when one the + error-setting functions was called.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_set_error()</function> and other functions + described here are available as a shared library, which can be + compiled and linked to with the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_error_add_map"> + + <refentryinfo> + <title>sd_bus_error_add_map</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_error_add_map</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_error_add_map</refname> + <refname>sd_bus_error_map</refname> + <refname>SD_BUS_ERROR_MAP</refname> + <refname>SD_BUS_ERROR_END</refname> + + <refpurpose>Additional sd-dbus error mappings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcsynopsisinfo>typedef struct { + const char *name; + int code; + … +} sd_bus_error_map;</funcsynopsisinfo> + + </funcsynopsis> + + <para> + <constant>SD_BUS_ERROR_MAP(<replaceable>name</replaceable>, <replaceable>code</replaceable>)</constant> + </para> + <para> + <constant>SD_BUS_ERROR_MAP_END</constant> + </para> + + <funcprototype> + <funcdef>int <function>sd_bus_error_add_map</function></funcdef> + <paramdef>const sd_bus_map *<parameter>map</parameter></paramdef> + </funcprototype> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_error_add_map()</function> call may be + used to register additional mappings for converting D-Bus errors + to Linux <varname>errno</varname>-style errors. The mappings + defined with this call are consulted by calls such as + <citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. By + default, a number of generic, standardized mappings are known, as + documented in + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Use + this call to add further, application-specific mappings.</para> + + <para>The function takes a pointer to an array of + <structname>sd_bus_error_map</structname> 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.</para> + + <para>The mapping array should be put together with a series of + <constant>SD_BUS_ERROR_MAP()</constant> macro invocations that + take a literal name string and a (positive) + <varname>errno</varname>-style error number. The last entry of the + array should be an invocation of the + <constant>SD_BUS_ERROR_MAP_END</constant> macro. The array should not be + put together without use of these two macros.</para> + + <para>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.</para> + + <para>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.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_bus_error_add_map()</function> 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 <varname>errno</varname>-style error + code is returned. See below for known error codes.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The specified mapping array is invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + <constant>libelogind</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Julian Orth + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_get_fd"> + + <refentryinfo> + <title>sd_bus_get_fd</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <firstname>Julian</firstname> + <surname>Orth</surname> + <email>ju.orth@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_get_fd</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_get_fd</refname> + + <refpurpose>Get the file descriptor connected to the message bus</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_get_fd</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>sd_bus_get_fd()</function> returns the file descriptor used to + communicate with the message bus. This descriptor can be used with + <citerefentry + project='die-net'><refentrytitle>select</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry + project='die-net'><refentrytitle>poll</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + or similar functions to wait for incoming messages. + </para> + + <para> + If the bus was created with the + <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> + function, then the <parameter>input_fd</parameter> used in that call is + returned. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + Returns the file descriptor used for incoming messages from the message + bus. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_message_append" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_append</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_append</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_append</refname> + + <refpurpose>Attach fields to a D-Bus message based on a type + string</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_append</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>const char *<parameter>types</parameter></paramdef> + <paramdef>…</paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_message_append()</function> function + appends a sequence of fields to the D-Bus message object + <parameter>m</parameter>. The type string + <parameter>types</parameter> 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.</para> + + <para>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 + <constant>NUL</constant>-terminated.</para> + + <para>In case of a basic type, one argument of the corresponding + type is expected.</para> + + <para>A structure is denoted by a sequence of complete types + between <literal>(</literal> and <literal>)</literal>. 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.</para> + + <para>A variant is denoted by <literal>v</literal>. Corresponding + arguments must begin with a type string denoting a complete type, + and following that, arguments corresponding to the specified type. + </para> + + <para>An array is denoted by <literal>a</literal> 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.</para> + + <para>A dictionary is an array of dictionary entries, denoted by + <literal>a</literal> followed by a pair of complete types between + <literal>{</literal> and <literal>}</literal>. 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.</para> + + <para>For further details on the D-Bus type system, please consult + the <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">D-Bus + Specification</ulink>.</para> + + <table> + <title>Item type specifiers</title> + + <tgroup cols='5'> + <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers'])//colspec" /> + <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//thead)" /> + + <tbody> + <xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//tbody/*)" /> + + <row> + <entry><literal>a</literal></entry> + <entry><constant>SD_BUS_TYPE_ARRAY</constant></entry> + <entry>array</entry> + <entry>determined by array type and size</entry> + <entry>int, followed by array contents</entry> + </row> + + <row> + <entry><literal>v</literal></entry> + <entry><constant>SD_BUS_TYPE_VARIANT</constant></entry> + <entry>variant</entry> + <entry>determined by the type argument</entry> + <entry>signature string, followed by variant contents</entry> + </row> + + <row> + <entry><literal>(</literal></entry> + <entry><constant>SD_BUS_TYPE_STRUCT_BEGIN</constant></entry> + <entry>array start</entry> + <entry morerows="1">determined by the nested types</entry> + <entry morerows="1">structure contents</entry> + </row> + <row> + <entry><literal>)</literal></entry> + <entry><constant>SD_BUS_TYPE_STRUCT_END</constant></entry> + <entry>array end</entry> + </row> + + <row> + <entry><literal>{</literal></entry> + <entry><constant>SD_BUS_TYPE_DICT_ENTRY_BEGIN</constant></entry> + <entry>dictionary entry start</entry> + <entry morerows="1">determined by the nested types</entry> + <entry morerows="1">dictionary contents</entry> + </row> + <row> + <entry><literal>}</literal></entry> + <entry><constant>SD_BUS_TYPE_DICT_ENTRY_END</constant></entry> + <entry>dictionary entry end</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>For types "s" and "g" (unicode string or signature), the pointer may be + <constant>NULL</constant>, which is equivalent to an empty string. See + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for the precise interpretation of those and other types.</para> + + </refsect1> + + <refsect1> + <title>Types String Grammar</title> + + <programlisting>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 "}" +</programlisting> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para>Append a single basic type (the string <literal>a string</literal>): + </para> + + <programlisting>sd_bus_message *m; +… +sd_bus_message_append(m, "s", "a string");</programlisting> + + <para>Append all types of integers:</para> + + <programlisting>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);</programlisting> + + <para>Append a structure composed of a string and a D-Bus path:</para> + + <programlisting>sd_bus_message_append(m, "(so)", "a string", "/a/path"); +</programlisting> + + <para>Append an array of UNIX file descriptors:</para> + + <programlisting>sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO); +</programlisting> + + <para>Append a variant, with the real type "g" (signature), + and value "sdbusisgood":</para> + + <programlisting>sd_bus_message_append(m, "v", "g", "sdbusisgood");</programlisting> + + <para>Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}: + </para> + + <programlisting>sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL); + </programlisting> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, this call returns 0 or a positive + integer. On failure, this call returns a negative + errno-style error code.</para> + </refsect1> + + <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_open_user()</function> and other functions + described here are available as a shared library, which can be + compiled and linked to with the + <constant>libelogind-bus</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_message_append_array" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_append_array</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_append_array</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_append_array</refname> + <refname>sd_bus_message_append_array_memfd</refname> + <refname>sd_bus_message_append_array_iovec</refname> + <refname>sd_bus_message_append_array_space</refname> + + <refpurpose>Append an array of fields to a D-Bus + message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_append_array</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>char void *<parameter>ptr</parameter></paramdef> + <paramdef>size_t <parameter>size</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_message_append_array_memfd</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>int <parameter>memfd</parameter></paramdef> + <paramdef>uint64_t <parameter>offset</parameter></paramdef> + <paramdef>uint64_t <parameter>size</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_message_append_array_iovec</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>const struct iovec *<parameter>iov</parameter></paramdef> + <paramdef>unsigned <parameter>n</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int sd_bus_message_append_array_space</funcdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>size_t <parameter>size</parameter></paramdef> + <paramdef>void **<parameter>ptr</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_message_append_array()</function> + function appends an array to a D-Bus message + <parameter>m</parameter>. A container will be opened, the array + contents appended, and the container closed. The parameter + <parameter>type</parameter> determines how the pointer + <parameter>p</parameter> is interpreted. + <parameter>type</parameter> must be one of the "trivial" types + <literal>y</literal>, <literal>n</literal>, <literal>q</literal>, + <literal>i</literal>, <literal>u</literal>, <literal>x</literal>, + <literal>t</literal>, <literal>d</literal> (but not + <literal>b</literal>), as defined by the <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic + Types</ulink> section of the D-Bus specification, and listed in + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Pointer <parameter>p</parameter> must point to an array of size + <parameter>size</parameter> bytes containing items of the + respective type. Size <parameter>size</parameter> must be a + multiple of the size of the type <parameter>type</parameter>. As a + special case, <parameter>p</parameter> may be + <constant>NULL</constant>, if <parameter>size</parameter> is 0. + The memory pointed to by <parameter>p</parameter> 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.</para> + + <para>The <function>sd_bus_message_append_array_memfd()</function> + function appends an array of a trivial type to message + <parameter>m</parameter>, similar to + <function>sd_bus_message_append_array()</function>. The contents + of the memory file descriptor <parameter>memfd</parameter> + 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 + <parameter>type</parameter>. 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 + <citerefentry + project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> + 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.</para> + + <para>The <function>sd_bus_message_append_array_iovec()</function> + function appends an array of a trivial type to the message + <parameter>m</parameter>, similar to + <function>sd_bus_message_append_array()</function>. Contents of + the I/O vector array <parameter>iov</parameter> are used as the + contents of the array. The total size of + <parameter>iov</parameter> payload (the sum of + <structfield>iov_len</structfield> fields) must be a multiple of + the size of the type <parameter>type</parameter>. The + <parameter>iov</parameter> argument must point to + <parameter>n</parameter> I/O vector structures. Each structure may + have the <structname>iov_base</structname> 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 + <structname>iov_len</structname> bytes will be inserted. The + memory pointed at by <parameter>iov</parameter> may be changed + after this call.</para> + + <para>The <function>sd_bus_message_append_array_space()</function> + function appends space for an array of a trivial type to message + <parameter>m</parameter>. It behaves the same as + <function>sd_bus_message_append_array()</function>, but instead of + copying items to the message, it returns a pointer to the + destination area to the caller in pointer + <parameter>p</parameter>. 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.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, they return a negative errno-style error code.</para> + </refsect1> + + <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_append_array()</function> and other + functions described here are available as a shared library, which + can be compiled and linked to with the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_message_append_basic"> + + <refentryinfo> + <title>sd_bus_message_append_basic</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_append_basic</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_append_basic</refname> + + <refpurpose>Attach a single field to a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_append_basic</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>const void *<parameter>p</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_message_append_basic()</function> appends a + single field to the message <parameter>m</parameter>. The + parameter <parameter>type</parameter> determines how the pointer + <parameter>p</parameter> is interpreted. + <parameter>type</parameter> must be one of the basic types as + defined by the <ulink + url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic + Types</ulink> section of the D-Bus specification, and listed in + the table below. + </para> + + <table id='format-specifiers'> + <title>Item type specifiers</title> + + <tgroup cols='5'> + <colspec colname='specifier' /> + <colspec colname='constant' /> + <colspec colname='description' /> + <colspec colname='size' /> + <colspec colname='ctype' /> + <thead> + <row> + <entry>Specifier</entry> + <entry>Constant</entry> + <entry>Description</entry> + <entry>Size</entry> + <entry>Expected C Type</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>y</literal></entry> + <entry><constant>SD_BUS_TYPE_BYTE</constant></entry> + <entry>unsigned integer</entry> + <entry>1 byte</entry> + <entry>uint8_t</entry> + </row> + + <row> + <entry><literal>b</literal></entry> + <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry> + <entry>boolean</entry> + <entry>4 bytes</entry> + <entry>int</entry> + </row> + + <row> + <entry><literal>n</literal></entry> + <entry><constant>SD_BUS_TYPE_INT16</constant></entry> + <entry>signed integer</entry> + <entry>2 bytes</entry> + <entry>int16_t</entry> + </row> + + <row> + <entry><literal>q</literal></entry> + <entry><constant>SD_BUS_TYPE_UINT16</constant></entry> + <entry>unsigned integer</entry> + <entry>2 bytes</entry> + <entry>uint16_t</entry> + </row> + + <row> + <entry><literal>i</literal></entry> + <entry><constant>SD_BUS_TYPE_INT32</constant></entry> + <entry>signed integer</entry> + <entry>4 bytes</entry> + <entry>int32_t</entry> + </row> + + <row> + <entry><literal>u</literal></entry> + <entry><constant>SD_BUS_TYPE_UINT32</constant></entry> + <entry>unsigned integer</entry> + <entry>4 bytes</entry> + <entry>uint32_t</entry> + </row> + + <row> + <entry><literal>x</literal></entry> + <entry><constant>SD_BUS_TYPE_INT64</constant></entry> + <entry>signed integer</entry> + <entry>8 bytes</entry> + <entry>int64_t</entry> + </row> + + <row> + <entry><literal>t</literal></entry> + <entry><constant>SD_BUS_TYPE_UINT64</constant></entry> + <entry>unsigned integer</entry> + <entry>8 bytes</entry> + <entry>uint64_t</entry> + </row> + + <row> + <entry><literal>d</literal></entry> + <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry> + <entry>floating-point</entry> + <entry>8 bytes</entry> + <entry>double</entry> + </row> + + <row> + <entry><literal>s</literal></entry> + <entry><constant>SD_BUS_TYPE_STRING</constant></entry> + <entry>Unicode string</entry> + <entry>variable</entry> + <entry>char[]</entry> + </row> + + <row> + <entry><literal>o</literal></entry> + <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry> + <entry>object path</entry> + <entry>variable</entry> + <entry>char[]</entry> + </row> + + <row> + <entry><literal>g</literal></entry> + <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry> + <entry>signature</entry> + <entry>variable</entry> + <entry>char[]</entry> + </row> + + <row> + <entry><literal>h</literal></entry> + <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry> + <entry>UNIX file descriptor</entry> + <entry>4 bytes</entry> + <entry>int</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>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 <parameter>type</parameter> + is <literal>h</literal> (UNIX file descriptor), the descriptor is + duplicated by this call and the passed descriptor stays in + possession of the caller.</para> + + <para>For types <literal>s</literal>, <literal>o</literal>, and + <literal>g</literal>, the parameter <parameter>p</parameter> is + interpreted as a pointer to a <constant>NUL</constant>-terminated + character sequence. As a special case, a <constant>NULL</constant> + 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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, this call returns 0 or a positive integer. On + failure, it returns a negative errno-style error code.</para> + </refsect1> + + <refsect1 id='errors'> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>Message has been sealed. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>Message is in invalid state. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>Message cannot be appended to. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_bus_append_basic()</function> function + described here is available as a shared library, which can be + compiled and linked to with the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_message_append_strv" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_message_append_strv</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_append_strv</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_append_strv</refname> + + <refpurpose>Attach an array of strings to a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int sd_bus_message_append_strv</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char **<parameter>l</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <function>sd_bus_message_append</function> function can be + used to append an array of strings to message + <parameter>m</parameter>. The parameter <parameter>l</parameter> + shall point to a <constant>NULL</constant>-terminated array of pointers + to <constant>NUL</constant>-terminated strings. Each string must + satisfy the same constraints as described for the + <literal>s</literal> type in + <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para>The memory pointed at by <parameter>p</parameter> 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 <parameter>l</parameter> parameter is to be + treated as <type>const char *const *</type>, and the contents + will not be modified.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, this call returns 0 or a positive integer. On + failure, a negative errno-style error code is returned.</para> + </refsect1> + + <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_bus_append_append_strv()</function> function + described here is available as a shared library, which can be + compiled and linked to with the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Julian Orth + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_message_read_basic"> + + <refentryinfo> + <title>sd_bus_message_read_basic</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <firstname>Julian</firstname> + <surname>Orth</surname> + <email>ju.orth@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_message_read_basic</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_message_read_basic</refname> + + <refpurpose>Read a basic type from a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_message_read_basic</function></funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>char <parameter>type</parameter></paramdef> + <paramdef>void *<parameter>p</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>sd_bus_message_read_basic()</function> 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 <parameter>type</parameter> are + described in the <ulink + url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus + Specification</ulink>. + </para> + + <para> + If <parameter>p</parameter> is not NULL, it should contain a pointer to an + appropriate object. For example, if <parameter>type</parameter> is + <constant>'y'</constant>, the object passed in <parameter>p</parameter> + should have type <code>uint8_t *</code>. If <parameter>type</parameter> + is <constant>'s'</constant>, the object passed in <parameter>p</parameter> + should have type <code>const char **</code>. Note that, if the basic type + is a pointer (e.g., <code>const char *</code> 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. + </para> + + <para> + If there is no object of the specified type at the current position in the + message, an error is returned. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + On success, <function>sd_bus_message_read_basic()</function> returns 0 or + a positive integer. On failure, it returns a negative errno-style error + code. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_negotiate_fds"> + + <refentryinfo> + <title>sd_bus_negotiate_fds</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_negotiate_fds</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_negotiate_fds</refname> + <refname>sd_bus_negotiate_timestamp</refname> + <refname>sd_bus_negotiate_creds</refname> + + <refpurpose>Control feature negotiation on bus connections</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_negotiate_fds</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_negotiate_timestamp</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_negotiate_creds</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + <paramdef>uint64_t <parameter>mask</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_negotiate_fds()</function> 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 + <citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. 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.</para> + + <para>Note that when bus activation is used, it is highly + recommended to set the <option>AcceptFileDescriptors=</option> + setting in the <filename>.busname</filename> unit file to the same + setting as negotiated by the program ultimately activated. By + default, file descriptor passing is enabled for both.</para> + + <para><function>sd_bus_negotiate_timestamp()</function> 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 + <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to query the timestamps of incoming messages. If negotiation is disabled or not supported, these + calls will fail with <constant>-ENODATA</constant>. Note that currently no transports support + timestamping of messages. By default, message timestamping is not negotiated for + connections.</para> + + <para><function>sd_bus_negotiate_creds()</function> 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 + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender credentials are suitable for + authorization decisions. By default, only <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In fact, these two credential fields + are always sent along and cannot be turned off.</para> + + <para>The <function>sd_bus_negotiate_fds()</function> function may + be called only before the connection has been started with + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both + <function>sd_bus_negotiate_timestamp()</function> and + <function>sd_bus_negotiate_creds()</function> 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 + <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>), + 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.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a + positive integer. On failure, they return a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>The bus connection has already been started.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_negotiate_fds()</function> and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_new"> + + <refentryinfo> + <title>sd_bus_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>A monkey with a typewriter</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_new</refname> + <refname>sd_bus_ref</refname> + <refname>sd_bus_unref</refname> + <refname>sd_bus_unrefp</refname> + + <refpurpose>Create a new bus object and create or destroy references to it</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_new</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_unrefp</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_new()</function> 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 + <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or a related call, and then start the connection with + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>In most cases, it is a better idea to invoke + <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or related calls instead of the more low-level + <function>sd_bus_new()</function> and + <function>sd_bus_start()</function>. 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.</para> + + <para><function>sd_bus_ref()</function> increases the reference + counter of <parameter>bus</parameter> by one.</para> + + <para><function>sd_bus_unref()</function> decreases the reference + counter of <parameter>bus</parameter> by one. Once the reference + count has dropped to zero, <parameter>bus</parameter> is destroyed + and cannot be used anymore, so further calls to + <function>sd_bus_ref()</function> or + <function>sd_bus_unref()</function> are illegal.</para> + + <para><function>sd_bus_unrefp()</function> is similar to + <function>sd_bus_unref()</function> but takes a pointer to a + pointer to an <type>sd_bus</type> object. This call is useful in + conjunction with GCC's and LLVM's <ulink + url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up + Variable Attribute</ulink>. 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:</para> + + <programlisting>{ + __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)); + … +}</programlisting> + + <para><function>sd_bus_ref()</function>, + <function>sd_bus_unref()</function> and + <function>sd_bus_unrefp()</function> execute no operation if the + passed in bus object is <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_new()</function> returns 0 or a + positive integer. On failure, it returns a negative errno-style + error code.</para> + + <para><function>sd_bus_ref()</function> always returns the argument. + </para> + + <para><function>sd_bus_unref()</function> always returns + <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_new()</function> and other functions + described here are available as a shared library, which can be + compiled and linked to with the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Julian Orth + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_process"> + + <refentryinfo> + <title>sd_bus_process</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <firstname>Julian</firstname> + <surname>Orth</surname> + <email>ju.orth@gmail.com</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_process</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_process</refname> + + <refpurpose>Drive the connection</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_process</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_message **<parameter>r</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <function>sd_bus_process()</function> 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. + </para> + + <para> + Once no further progress can be made, + <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> + should be called. Alternatively the user can wait for incoming data on + the file descriptor returned by + <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para> + <function>sd_bus_process</function> processes at most one incoming + message per call. If the parameter <parameter>r</parameter> is not NULL + and the call processed a message, <code>*r</code> is set to this message. + The caller owns a reference to this message and should call + <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + when the message is no longer needed. If <parameter>r</parameter> is not + NULL, progress was made, but no message was processed, <code>*r</code> is + set to NULL. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + 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. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2013 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_request_name"> + + <refentryinfo> + <title>sd_bus_request_name</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_request_name</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_request_name</refname> + <refname>sd_bus_release_name</refname> + <refpurpose>Request or release a well-known service name on a bus</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_request_name</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>uint64_t <parameter>flags</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_release_name</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_request_name()</function> 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:</para> + + <variablelist> + <varlistentry> + <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term> + + <listitem><para>After acquiring the name successfully, permit + other peers to take over the name when they try to acquire it + with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag + set. If <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is + not set on the original request, such a request by other peers + will be denied.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term> + + <listitem><para>Take over the name if it is already acquired + by another peer, and that other peer has permitted takeover by + setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while + acquiring it.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SD_BUS_NAME_QUEUE</varname></term> + + <listitem><para>Queue the acquisition of the name when the + name is already taken.</para></listitem> + </varlistentry> + </variablelist> + + <para><function>sd_bus_release_name()</function> releases an + acquired well-known name. It takes a bus connection and a valid + bus name as parameters.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code.</para> + + <para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified, + <function>sd_bus_request_name()</function> 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 <literal>NameOwnerChanged</literal> signals to be + notified when the name is successfully acquired. + <function>sd_bus_request_name()</function> returns > 0 when the + name has immediately been acquired successfully.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EALREADY</constant></term> + + <listitem><para>The caller already is the owner of the + specified name.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EEXIST</constant></term> + + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESRCH</constant></term> + + <listitem><para>It was attempted to release a name that is + currently not registered on the bus.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EADDRINUSE</constant></term> + + <listitem><para>It was attempted to release a name that is + owned by a different peer on the bus.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOTCONN</constant></term> + + <listitem><para>The bus connection has been + disconnected.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a + different process than the current one.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_bus_acquire_name()</function> and + <function>sd_bus_release_name()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_track_add_name"> + + <refentryinfo> + <title>sd_bus_track_add_name</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_track_add_name</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_track_add_name</refname> + <refname>sd_bus_track_add_sender</refname> + <refname>sd_bus_track_remove_name</refname> + <refname>sd_bus_track_remove_sender</refname> + <refname>sd_bus_track_count</refname> + <refname>sd_bus_track_count_sender</refname> + <refname>sd_bus_track_count_name</refname> + <refname>sd_bus_track_contains</refname> + <refname>sd_bus_track_first</refname> + <refname>sd_bus_track_next</refname> + + <refpurpose>Add, remove and retrieve bus peers tracked in a bus peer tracking object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_track_add_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_add_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_remove_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_remove_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>unsigned <function>sd_bus_track_count</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_count_name</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_count_sender</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>sd_bus_message* <parameter>message</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_contains</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_track_first</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>const char* <function>sd_bus_track_next</function></funcdef> + <paramdef>sd_bus_track* <parameter>t</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_track_add_name()</function> adds a peer to track to a bus peer tracking object. The first + argument should refer to a bus peer tracking object created with + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 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 <function>sd_bus_track_remove_name()</function> has to be called as many + times as <function>sd_bus_track_add_name()</function> was invoked before in order to stop tracking of the name. Use + <citerefentry><refentrytitle>sd_bus_track_set_recursive</refentrytitle><manvolnum>3</manvolnum></citerefentry> 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.</para> + + <para><function>sd_bus_track_remove_name()</function> undoes the effect of + <function>sd_bus_track_add_name()</function> 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.</para> + + <para><function>sd_bus_track_add_sender()</function> and <function>sd_bus_track_remove_sender()</function> are + similar to <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_remove_name()</function> 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.</para> + + <para><function>sd_bus_track_count()</function> 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 <function>sd_bus_track_add_name()</function> has been invoked multiple times for the same name it is only + counted as one, regardless if recursive mode is used or not.</para> + + <para><function>sd_bus_track_count_name()</function> 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 <function>sd_bus_track_add_name()</function> has been called multiple times for the same + name.</para> + + <para><function>sd_bus_track_count_sender()</function> is similar to + <function>sd_bus_track_count_name()</function>, but takes a bus message object and returns the per-name counter + matching the sender of the message.</para> + + <para><function>sd_bus_track_contains()</function> may be used to determine whether the specified name has been + added at least once to the specified bus peer tracking object.</para> + + <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> may be used to + enumerate all names currently being tracked by the passed bus peer tracking + object. <function>sd_bus_track_first()</function> returns the first entry in the object, and resets an internally + maintained read index. Each subsequent invocation of <function>sd_bus_track_next()</function> returns the next name + contained in the bus object. If the end is reached <constant>NULL</constant> is returned. If no names have been + added to the object yet <function>sd_bus_track_first()</function> will return <constant>NULL</constant> + 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 <function>sd_bus_track_next()</function> as <constant>NULL</constant> is returned.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_track_add_name()</function> and <function>sd_bus_track_add_sender()</function> + 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.</para> + + <para><function>sd_bus_track_remove_name()</function> and <function>sd_bus_track_remove_sender()</function> 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 + <constant>-EUNATCH</constant> is returned in this case. On failure, they return a negative errno-style error + code.</para> + + <para><function>sd_bus_track_count()</function> returns the number of names currently being tracked, or 0 on + failure.</para> + + <para><function>sd_bus_track_count_name()</function> and <function>sd_bus_track_count_sender()</function> 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.</para> + + <para><function>sd_bus_track_contains()</function> returns the passed name if it exists in the bus peer tracking + object. On failure, and if the name has not been added yet <constant>NULL</constant> is returned.</para> + + <para><function>sd_bus_track_first()</function> and <function>sd_bus_track_next()</function> return the first/next + name contained in the bus peer tracking object, and <constant>NULL</constant> if the end of the enumeration is + reached and on error.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EUNATCH</constant></term> + + <listitem><para><function>sd_bus_track_remove_name()</function> or + <function>sd_bus_track_remove_sender()</function> have been invoked for a name not previously added to the bus + peer object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_track_add_name()</function> and the other calls described here are available as a shared library, + which can be compiled and linked to with the <constant>libelogind</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2016 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_bus_track_new"> + + <refentryinfo> + <title>sd_bus_track_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_track_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_track_new</refname> + <refname>sd_bus_track_ref</refname> + <refname>sd_bus_track_unref</refname> + <refname>sd_bus_track_unrefp</refname> + <refname>sd_bus_track_set_recursive</refname> + <refname>sd_bus_track_get_recursive</refname> + <refname>sd_bus_track_get_bus</refname> + <refname>sd_bus_track_get_userdata</refname> + <refname>sd_bus_track_set_userdata</refname> + + <refpurpose>Track bus peers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_track_new</function></funcdef> + <paramdef>sd_bus* <parameter>bus</parameter></paramdef> + <paramdef>sd_bus_track** <parameter>ret</parameter></paramdef> + <paramdef>sd_bus_track_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void* <parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_track *<function>sd_bus_track_ref</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus_track *<function>sd_bus_track_unref</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_track_unrefp</function></funcdef> + <paramdef>sd_bus_track **<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_get_recursive</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_set_recursive</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus* <function>sd_bus_track_get_bus</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_track_get_userdata</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void* <function>sd_bus_track_set_userdata</function></funcdef> + <paramdef>sd_bus_track *<parameter>t</parameter></paramdef> + <paramdef>void *userdata</paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_track_new()</function> creates a new bus peer tracking object. The object is allocated for + the specified bus, and returned in the <parameter>*ret</parameter> parameter. After use, the object should be freed + again by dropping the acquired reference with <function>sd_bus_track_unref()</function> (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 + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> or + <function>sd_bus_track_add_sender()</function>. They may be dropped again via + <function>sd_bus_track_remove_name()</function> and + <function>sd_bus_track_remove_sender()</function>. Alternatively, references on peers are removed automatically + when they disconnect from the bus. If non-NULL the <parameter>handler</parameter> may specify a function that is + invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via + <function>sd_bus_track_remove_name()</function> or implicitly because the peer disconnected from the bus. The final + argument <parameter>userdata</parameter> 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.</para> + + <para><function>sd_bus_track_ref()</function> creates a new reference to a bus peer tracking object. This object + will not be destroyed until <function>sd_bus_track_unref()</function> 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 + <function>sd_bus_track_ref()</function> or <function>sd_bus_track_unref()</function> on the same object are + illegal.</para> + + <para><function>sd_bus_track_unref()</function> destroys a reference to a bus peer tracking object.</para> + + <para><function>sd_bus_track_unrefp()</function> is similar to <function>sd_bus_track_unref()</function> but takes + a pointer to a pointer to an <type>sd_bus_track</type> object. This call is useful in conjunction with GCC's and + LLVM's <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable + Attribute</ulink>. Note that this function is defined as inline function.</para> + + <para><function>sd_bus_track_ref()</function>, <function>sd_bus_track_unref()</function> and + <function>sd_bus_track_unrefp()</function> execute no operation if the passed in bus peer tracking object is + <constant>NULL</constant>.</para> + + <para>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 <function>sd_bus_track_add_name()</function> 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 + <function>sd_bus_track_remove_name()</function> removes the reference on the peer again, regardless how many times + <function>sd_bus_track_add_name()</function> was called before. If operating in recursive mode, the number of times + <function>sd_bus_track_add_name()</function> is invoked for the same peer name is counted and + <function>sd_bus_track_remove_name()</function> 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. <function>sd_bus_track_get_recursive()</function> may be used to determine whether the bus peer tracking + object is operating in recursive mode. <function>sd_bus_track_set_recursive()</function> may be used to enable or + disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and + <function>sd_bus_track_get_recursive()</function> for a newly allocated object hence returns a value equal to + zero. Use <function>sd_bus_track_set_recursive()</function> to enable recursive mode, right after allocation. It + takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which + <function>sd_bus_track_add_name()</function> 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.</para> + + <para><function>sd_bus_track_get_bus()</function> returns the bus object the bus peer tracking object belongs + to. It returns the bus object initially passed to <function>sd_bus_track_new()</function> when the object was + allocated.</para> + + <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer set on the bus peer + tracking object at the time of creation using <function>sd_bus_track_new()</function> or at a later time, using + <function>sd_bus_track_set_userdata()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_track_new()</function> and <function>sd_bus_track_set_recursive()</function> + return 0 or a positive integer. On failure, they return a negative errno-style error code.</para> + + <para><function>sd_bus_track_ref()</function> always returns the argument.</para> + + <para><function>sd_bus_track_unref()</function> always returns <constant>NULL</constant>.</para> + + <para><function>sd_bus_track_get_recursive()</function> 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.</para> + + <para><function>sd_bus_track_get_bus()</function> returns the bus object associated to the bus peer tracking + object.</para> + + <para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer associated with the + bus peer tracking object. <function>sd_bus_track_set_userdata()</function> returns the previous user data pointer + set.</para> + + </refsect1> + + <refsect1> + <title>Reference ownership</title> + + <para>The <function>sd_bus_track_new()</function> function creates a new object and the caller owns the sole + reference. When not needed anymore, this reference should be destroyed with + <function>sd_bus_track_unref()</function>. + </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>Bus peers have already been added to the bus peer tracking object and + <function>sd_bus_track_set_recursive()</function> was called to change tracking mode.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>Specified parameter is invalid + (<constant>NULL</constant> in case of output + parameters).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_track_new()</function> and the other calls described here are available as a shared library, + which can be compiled and linked to with the <constant>libelogind</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_add_child</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>More text</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_add_child</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_add_child</refname> + <refname>sd_event_source_get_child_pid</refname> + <refname>sd_event_child_handler_t</refname> + + <refpurpose>Add a child process state change event source to an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>const siginfo_t *<parameter>si</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_add_child</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>options</parameter></paramdef> + <paramdef>sd_event_child_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_child_pid</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>pid_t *<parameter>pid</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_add_child()</function> adds a new child + process state change event source to an event loop. The event loop + object is specified in the <parameter>event</parameter> parameter, + the event source object is returned in the + <parameter>source</parameter> parameter. The + <parameter>pid</parameter> parameter specifies the PID of the + process to watch. The <parameter>handler</parameter> must + reference a function to call when the process changes state. The + handler function will be passed the + <parameter>userdata</parameter> pointer, which may be chosen + freely by the caller. The handler also receives a pointer to a + <structname>siginfo_t</structname> structure containing + information about the child process event. The + <parameter>options</parameter> parameter determines which state + changes will be watched for. It must contain an OR-ed mask of + <constant>WEXITED</constant> (watch for the child process + terminating), <constant>WSTOPPED</constant> (watch for the child + process being stopped by a signal), and + <constant>WCONTINUED</constant> (watch for the child process being + resumed by a signal). See <citerefentry + project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for further information.</para> + + <para>Only a single handler may be installed for a specific + child process. The handler is enabled for a single event + (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed + with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. + </para> + + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + 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 + <constant>SD_EVENT_OFF</constant> with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>If the second parameter of + <function>sd_event_add_child()</function> 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.</para> + + <para>Note that the <parameter>handler</parameter> 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.</para> + + <para>If both a child process state change event source and a + <constant>SIGCHLD</constant> 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.</para> + + <para><function>sd_event_source_get_child_pid()</function> + retrieves the configured PID of a child process state change event + source created previously with + <function>sd_event_add_child()</function>. It takes the event + source object as the <parameter>source</parameter> parameter and a + pointer to a <type>pid_t</type> variable to return the process ID + in. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory to allocate an object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid argument has been passed. This includes + specifying an empty mask in <parameter>options</parameter> or a mask + which contains values different than a combination of + <constant>WEXITED</constant>, <constant>WSTOPPED</constant>, and + <constant>WCONTINUED</constant>. + </para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>A handler is already installed for this + child process.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-EDOM</constant></term> + + <listitem><para>The passed event source is not a child process event source.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_add_defer</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>More text</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_add_defer</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_add_defer</refname> + <refname>sd_event_add_post</refname> + <refname>sd_event_add_exit</refname> + <refname>sd_event_handler_t</refname> + + <refpurpose>Add static event sources to an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_add_defer</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_add_post</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_add_exit</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>sd_event_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>These three functions add new static event sources to an + event loop. The event loop object is specified in the + <parameter>event</parameter> parameter, the event source object is + returned in the <parameter>source</parameter> 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 <parameter>userdata</parameter> + pointer, which may be chosen freely by the caller.</para> + + <para><function>sd_event_add_defer()</function> 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 + (<constant>SD_EVENT_ONESHOT</constant>). Note that if the event + source is set to <constant>SD_EVENT_ON</constant> the event loop + will never go to sleep again, but continuously call the handler, + possibly interleaved with other event sources.</para> + + <para><function>sd_event_add_post()</function> 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 (<constant>SD_EVENT_ON</constant>). Note that this + event source type will still allow the event loop to go to sleep + again, even if set to <constant>SD_EVENT_ON</constant>, as long as + no other event source is ever triggered.</para> + + <para><function>sd_event_add_exit()</function> adds a new event + source that will be dispatched when the event loop is terminated + with <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>The + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + function may be used to enable the event source permanently + (<constant>SD_EVENT_ON</constant>) or to make it fire just once + (<constant>SD_EVENT_ONESHOT</constant>).</para> + + <para>If the handler function returns a negative error code, it + will be disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before.</para> + + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + 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 + <constant>SD_EVENT_OFF</constant> with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>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.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory to allocate an object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid argument has been passed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_add_signal</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>More text</contrib> + <firstname>Zbigniew</firstname> + <surname>Jędrzejewski-Szmek</surname> + <email>zbyszek@in.waw.pl</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_add_signal</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_add_signal</refname> + <refname>sd_event_source_get_signal</refname> + <refname>sd_event_signal_handler_t</refname> + + <refpurpose>Add a UNIX process signal event source to an event + loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_add_signal</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>int <parameter>signal</parameter></paramdef> + <paramdef>sd_event_signal_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_signal</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_add_signal()</function> adds a new UNIX + process signal event source to an event loop. The event loop + object is specified in the <parameter>event</parameter> parameter, + and the event source object is returned in the + <parameter>source</parameter> parameter. The + <parameter>signal</parameter> parameter specifies the numeric + signal to be handled (see <citerefentry + project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>). + The <parameter>handler</parameter> parameter must reference a + function to call when the signal is received or be + <constant>NULL</constant>. The handler function will be passed + the <parameter>userdata</parameter> pointer, which may be chosen + freely by the caller. The handler also receives a pointer to a + <structname>signalfd_siginfo</structname> structure containing + information about the received signal. See <citerefentry + project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for further information.</para> + + <para>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 + <citerefentry + project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>). If + the handler is not specified (<parameter>handler</parameter> is + <constant>NULL</constant>), a default handler which causes the + program to exit cleanly will be used.</para> + + <para>By default, the event source is enabled permanently + (<constant>SD_EVENT_ON</constant>), but this may be changed with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. + </para> + + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + 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 + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant>.</para> + + <para>If the second parameter of + <function>sd_event_add_signal()</function> is + <constant>NULL</constant> 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.</para> + + <para><function>sd_event_source_get_signal()</function> returns + the configured signal number of an event source created previously + with <function>sd_event_add_signal()</function>. It takes the + event source object as the <parameter>source</parameter> + parameter.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory to allocate an object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid argument has been passed.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>A handler is already installed for this + signal or the signal was not blocked previously.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EDOM</constant></term> + + <listitem><para>The passed event source is not a signal event source.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_add_time</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_add_time</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_add_time</refname> + <refname>sd_event_source_get_time</refname> + <refname>sd_event_source_set_time</refname> + <refname>sd_event_source_get_time_accuracy</refname> + <refname>sd_event_source_set_time_accuracy</refname> + <refname>sd_event_source_get_time_clock</refname> + <refname>sd_event_time_handler_t</refname> + + <refpurpose>Add a timer event source to an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_add_time</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>clockid_t <parameter>clock</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + <paramdef>uint64_t <parameter>accuracy</parameter></paramdef> + <paramdef>sd_event_time_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_time</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_time_clock</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>clockid_t *<parameter>clock</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_add_time()</function> adds a new timer event source to an event loop. The event loop + object is specified in the <parameter>event</parameter> parameter, the event source object is returned in the + <parameter>source</parameter> parameter. The <parameter>clock</parameter> parameter takes a clock identifier, one + of <constant>CLOCK_REALTIME</constant>, <constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_BOOTTIME</constant>, + <constant>CLOCK_REALTIME_ALARM</constant>, or <constant>CLOCK_BOOTTIME_ALARM</constant>. See + <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> for details + regarding the various types of clocks. The <parameter>usec</parameter> 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 <constant>0</constant>), this timer source "fires" immediately and is ready to be + dispatched. If the parameter is specified as <constant>UINT64_MAX</constant> the timer event will never elapse, + which may be used as an alternative to explicitly disabling a timer event source with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. The + <parameter>accuracy</parameter> parameter specifies an additional accuracy value in µs specifying how much the + timer event may be delayed. Use <constant>0</constant> 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 <parameter>handler</parameter> parameter shall reference a function to call when + the timer elapses. The handler function will be passed the <parameter>userdata</parameter> 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 + <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>), and additional + scheduling latencies. To query the actual time the handler was called use + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>By default, the timer will elapse once + (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed + with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + If the handler function returns a negative error code, it will be + disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. Note + that a timer event set to <constant>SD_EVENT_ON</constant> will + fire continuously unless its configured time is updated using + <function>sd_event_source_set_time()</function>. + </para> + + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + 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 + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with <constant>SD_EVENT_OFF</constant>.</para> + + <para>If the second parameter of + <function>sd_event_add_time()</function> is + <constant>NULL</constant> 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.</para> + + <para>If the <parameter>handler</parameter> to + <function>sd_event_add_time()</function> is + <constant>NULL</constant>, and the event source fires, this will + be considered a request to exit the event loop. In this case, the + <parameter>userdata</parameter> parameter, cast to an integer, is + used for the exit code passed to + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and + <constant>CLOCK_REALTIME_ALARM</constant> to define event sources + that may wake up the system from suspend.</para> + + <para>In order to set up relative timers (that is, relative to the + current time), retrieve the current time via + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + add the desired timespan to it, and use the result as + the <parameter>usec</parameter> parameter to + <function>sd_event_add_time()</function>.</para> + + <para>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 + <citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer + iteration, and reenable the timer using + <function>sd_event_source_set_enabled()</function>. To calculate + the next point in time to pass to + <function>sd_event_source_set_time()</function>, either use as + base the <parameter>usec</parameter> parameter passed to the timer + callback, or the timestamp returned by + <function>sd_event_now()</function>. In the former case timer + events will be regular, while in the latter case the scheduling + latency will keep accumulating on the timer.</para> + + <para><function>sd_event_source_get_time()</function> retrieves + the configured time value of an event source created + previously with <function>sd_event_add_time()</function>. 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.</para> + + <para><function>sd_event_source_set_time()</function> changes the + time of an event source created previously with + <function>sd_event_add_time()</function>. It takes the event + source object and a time relative to the selected clock's epoch, + in µs.</para> + + <para><function>sd_event_source_get_time_accuracy()</function> + retrieves the configured accuracy value of an event source + created previously with <function>sd_event_add_time()</function>. It + takes the event source object and a pointer to a variable to store + the accuracy in. The accuracy is specified in µs.</para> + + <para><function>sd_event_source_set_time_accuracy()</function> + changes the configured accuracy of a timer event source created + previously with <function>sd_event_add_time()</function>. It takes + the event source object and accuracy, in µs.</para> + + <para><function>sd_event_source_get_time_clock()</function> + retrieves the configured clock of an event source created + previously with <function>sd_event_add_time()</function>. It takes + the event source object and a pointer to a variable to store the + clock identifier in.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive + integer. On failure, they return a negative errno-style error + code. </para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned values may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory to allocate an object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid argument has been passed.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-EOPNOTSUPP</constant></term> + + <listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-EDOM</constant></term> + + <listitem><para>The passed event source is not a timer event source.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2014 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_new" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_new</refname> + <refname>sd_event_default</refname> + <refname>sd_event_ref</refname> + <refname>sd_event_unref</refname> + <refname>sd_event_unrefp</refname> + <refname>sd_event_get_tid</refname> + <refname>sd_event</refname> + + <refpurpose>Acquire and release an event loop object</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_new</function></funcdef> + <paramdef>sd_event **<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_default</function></funcdef> + <paramdef>sd_event **<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_event *<function>sd_event_ref</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_event *<function>sd_event_unref</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_event_unrefp</function></funcdef> + <paramdef>sd_event **<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_get_tid</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>pid_t *<parameter>tid</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_new()</function> allocates a new event + loop object. The event loop object is returned in the + <parameter>event</parameter> parameter. After use, drop + the returned reference with + <function>sd_event_unref()</function>. When the last reference is + dropped, the object is freed.</para> + + <para><function>sd_event_default()</function> 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 <function>sd_event_unref()</function>. 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 + <function>sd_event_new()</function> 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.</para> + + <para>After allocating an event loop object, add event sources to + it with + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + and then execute the event loop using + <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para><function>sd_event_ref()</function> increases the reference + count of the specified event loop object by one.</para> + + <para><function>sd_event_unref()</function> 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 + <function>sd_event_default()</function>, then releasing it, and + then acquiring a new one with + <function>sd_event_default()</function> 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.</para> + + <para><function>sd_event_unrefp()</function> is similar to + <function>sd_event_unref()</function> but takes a pointer to a + pointer to an <type>sd_event</type> object. This call is useful in + conjunction with GCC's and LLVM's <ulink + url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up + Variable Attribute</ulink>. 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:</para> + + <programlisting>{ + __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)); + … +}</programlisting> + + <para><function>sd_event_ref()</function>, + <function>sd_event_unref()</function> and + <function>sd_event_unrefp()</function> execute no operation if the + passed in event loop object is <constant>NULL</constant>.</para> + + <para><function>sd_event_get_tid()</function> 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 <function>sd_event_default()</function>, and + returns the identifier for the thread the event loop is the + default event loop of. See <citerefentry + project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for more information on thread identifiers.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_event_new()</function>, + <function>sd_event_default()</function> and + <function>sd_event_get_tid()</function> return 0 or a positive + integer. On failure, they return a negative errno-style error + code. <function>sd_event_ref()</function> always returns a pointer + to the event loop object passed + in. <function>sd_event_unref()</function> always returns + <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory to allocate the object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EMFILE</constant></term> + + <listitem><para>The maximum number of event loops has been allocated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para><function>sd_event_get_tid()</function> was + invoked on an event loop object that was not allocated with + <function>sd_event_default()</function>.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_run</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_run</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_run</refname> + <refname>sd_event_loop</refname> + + <refpurpose>Run an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_run</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_loop</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_run()</function> may be used to run a single + iteration of the event loop specified in the + <parameter>event</parameter> parameter. The function waits until an event to + process is available, and dispatches the registered handler for + it. The <parameter>usec</parameter> parameter specifies the + maximum time (in microseconds) to wait for an event. Use + <constant>(uint64_t) -1</constant> to specify an infinite + timeout.</para> + + <para><function>sd_event_loop()</function> invokes + <function>sd_event_run()</function> in a loop, thus implementing + the actual event loop. The call returns as soon as exiting was + requested using + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>The event loop object <parameter>event</parameter> is + created with + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Events sources to wait for and their handlers may be registered + with + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + </para> + + <para>For low-level control of event loop execution, use + <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry> + which are wrapped by <function>sd_event_run()</function>. Along + with + <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + these functions allow integration of an + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> + event loop into foreign event loop implementations.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, these functions return a negative errno-style + error code. <function>sd_event_run()</function> 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. <function>sd_event_loop()</function> returns the exit + code specified when invoking + <function>sd_event_exit()</function>.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>event</parameter> parameter is + invalid or <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>The event loop object is not in the right + state (see + <citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for an explanation of possible states).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + </variablelist> + + <para>Other errors are possible, too.</para> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>. + </para> + </refsect1> + +</refentry> 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"> <!-- - This file is part of elogind. + This file is part of systemd. Copyright 2015 Lennart Poettering - elogind is free software; you can redistribute it and/or modify it + systemd is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. - elogind is distributed in the hope that it will be useful, but + systemd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License - along with elogind; If not, see <http://www.gnu.org/licenses/>. + along with systemd; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="sd_event_source_unref" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_source_unref</title> - <productname>elogind</productname> + <productname>systemd</productname> <authorgroup> <author> @@ -52,7 +52,7 @@ <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <elogind/sd-event.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> <funcprototype> <funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2015 Zbigniew Jędrzejewski-Szmek + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_wait</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Tom</firstname> + <surname>Gundersen</surname> + <email>teg@jklm.no</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_wait</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_wait</refname> + <refname>sd_event_prepare</refname> + <refname>sd_event_dispatch</refname> + <refname>sd_event_get_state</refname> + <refname>sd_event_get_iteration</refname> + <refname>SD_EVENT_INITIAL</refname> + <refname>SD_EVENT_PREPARING</refname> + <refname>SD_EVENT_ARMED</refname> + <refname>SD_EVENT_PENDING</refname> + <refname>SD_EVENT_RUNNING</refname> + <refname>SD_EVENT_EXITING</refname> + <refname>SD_EVENT_FINISHED</refname> + + <refpurpose>Low-level event loop operations</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>enum</token> { + <constant>SD_EVENT_INITIAL</constant>, + <constant>SD_EVENT_PREPARING</constant>, + <constant>SD_EVENT_ARMED</constant>, + <constant>SD_EVENT_PENDING</constant>, + <constant>SD_EVENT_RUNNING</constant>, + <constant>SD_EVENT_EXITING</constant>, + <constant>SD_EVENT_FINISHED</constant>, +};</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_event_prepare</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_wait</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>uint64_t <parameter>usec</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_dispatch</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_get_state</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_get_iteration</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>uint64_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The low-level <function>sd_event_prepare()</function>, + <function>sd_event_wait()</function> and + <function>sd_event_dispatch()</function> functions may be used to + execute specific phases of an event loop. See + <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for higher-level functions that execute individual but complete + iterations of an event loop or run it continuously.</para> + + <para><function>sd_event_prepare()</function> 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 + <function>sd_event_dispatch()</function>.</para> + + <para><function>sd_event_dispatch()</function> dispatches the + highest priority event source that has a pending event. On + success, <function>sd_event_dispatch()</function> returns either + zero, which indicates that no further event sources may be + dispatched and exiting of the event loop was requested via + <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>; + 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 + <function>sd_event_prepare()</function> again.</para> + + <para>In case <function>sd_event_prepare()</function> returned + zero, <function>sd_event_wait()</function> 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 + <function>sd_event_dispatch()</function>. Otherwise, the event + loop returned to its initial state and the next event loop + iteration should be initiated by invoking + <function>sd_event_prepare()</function> again.</para> + + <para><function>sd_event_get_state()</function> may be used to + determine the state the event loop is currently in. It returns one + of the states described below.</para> + + <para><function>sd_event_get_iteration()</function> 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 + <function>sd_event_prepare()</function> invocation.</para> + + <para>All five functions take, as the first argument, the event loop object <parameter>event</parameter> that has + been created with <function>sd_event_new()</function>. The timeout for <function>sd_event_wait()</function> is + specified in <parameter>usec</parameter> in microseconds. <constant>(uint64_t) -1</constant> may be used to + specify an infinite timeout.</para> +</refsect1> + + <refsect1> + <title>State Machine</title> + + <para>The event loop knows the following states, that may be + queried with <function>sd_event_get_state()</function>.</para> + + <variablelist> + <varlistentry> + <term><constant>SD_EVENT_INITIAL</constant></term> + + <listitem><para>The initial state the event loop is in, + before each event loop iteration. Use + <function>sd_event_prepare()</function> to transition the + event loop into the <constant>SD_EVENT_ARMED</constant> or + <constant>SD_EVENT_PENDING</constant> states.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_PREPARING</constant></term> + + <listitem><para>An event source is currently being prepared, + i.e. the preparation handler is currently being executed, as + set with + <citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This + state is only seen in the event source preparation handler + that is invoked from the + <function>sd_event_prepare()</function> call and is + immediately followed by <constant>SD_EVENT_ARMED</constant> or + <constant>SD_EVENT_PENDING</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_ARMED</constant></term> + + <listitem><para><function>sd_event_prepare()</function> has + been called and no event sources were ready to be + dispatched. Use <function>sd_event_wait()</function> to wait + for new events, and transition into + <constant>SD_EVENT_PENDING</constant> or back into + <constant>SD_EVENT_INITIAL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_PENDING</constant></term> + + <listitem><para><function>sd_event_prepare()</function> or + <function>sd_event_wait()</function> have been called and + there were event sources with events pending. Use + <function>sd_event_dispatch()</function> to dispatch the + highest priority event source and transition back to + <constant>SD_EVENT_INITIAL</constant>, or + <constant>SD_EVENT_FINISHED</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_RUNNING</constant></term> + + <listitem><para>A regular event source is currently being + dispatched. This state is only seen in the event source + handler that is invoked from the + <function>sd_event_dispatch()</function> call, and is + immediately followed by <constant>SD_EVENT_INITIAL</constant> + or <constant>SD_EVENT_FINISHED</constant> as soon the event + source handler returns. Note that during dispatching of exit + event sources the <constant>SD_EVENT_EXITING</constant> state + is seen instead.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_EXITING</constant></term> + + <listitem><para>Similar to + <constant>SD_EVENT_RUNNING</constant> but is the state in + effect while dispatching exit event sources. It is followed by + <constant>SD_EVENT_INITIAL</constant> or + <constant>SD_EVENT_FINISHED</constant> as soon as the event + handler returns.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SD_EVENT_FINISHED</constant></term> + + <listitem><para>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.</para></listitem> + </varlistentry> + + </variablelist> + + <para>A simplified flow chart of the states and the calls to + transition between them is shown below. Note that + <constant>SD_EVENT_PREPARING</constant>, + <constant>SD_EVENT_RUNNING</constant> and + <constant>SD_EVENT_EXITING</constant> are not shown here.</para> + + <programlisting> + 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 + </programlisting> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. + On failure, they return a negative errno-style error code. In case + of <function>sd_event_prepare()</function> and + <function>sd_event_wait()</function>, 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 + <function>sd_event_dispatch()</function>, a positive, non-zero + return code indicates that the event loop returned to its initial + state and zero indicates the event loop has + exited. <function>sd_event_get_state()</function> returns a + positive or zero state on success.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>event</parameter> parameter is + invalid or <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EBUSY</constant></term> + + <listitem><para>The event loop object is not in the right + state.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + </variablelist> + + <para>Other errors are possible, too.</para> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ <para>The <function>sd_id128_get_machine()</function>, <function>sd_id128_get_machine_app_specific()</function> <function>sd_id128_get_boot()</function> and <function>sd_id128_get_invocation()</function> interfaces are available as a shared library, which can be compiled and linked to with the - <literal>libsystemd</literal> <citerefentry + <literal>libelogind</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> </refsect1> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_is_fifo" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_is_fifo</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_is_fifo</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_is_fifo</refname> + <refname>sd_is_socket</refname> + <refname>sd_is_socket_inet</refname> + <refname>sd_is_socket_unix</refname> + <refname>sd_is_socket_sockaddr</refname> + <refname>sd_is_mq</refname> + <refname>sd_is_special</refname> + <refpurpose>Check the type of a file descriptor</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_is_fifo</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>family</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket_inet</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>family</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + <paramdef>uint16_t <parameter>port</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket_sockaddr</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>const struct sockaddr *<parameter>addr</parameter></paramdef> + <paramdef>unsigned <parameter>addr_len</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_socket_unix</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>type</parameter></paramdef> + <paramdef>int <parameter>listening</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>size_t <parameter>length</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_mq</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_is_special</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_is_fifo()</function> may be called to check + whether the specified file descriptor refers to a FIFO or pipe. If + the <parameter>path</parameter> parameter is not + <constant>NULL</constant>, it is checked whether the FIFO is bound + to the specified file system path.</para> + + <para><function>sd_is_socket()</function> may be called to check + whether the specified file descriptor refers to a socket. If the + <parameter>family</parameter> parameter is not + <constant>AF_UNSPEC</constant>, it is checked whether the socket + is of the specified family (<constant>AF_UNIX</constant>, + <constant>AF_INET</constant>, …). If the <parameter>type</parameter> + parameter is not 0, it is checked whether the socket is of the + specified type (<constant>SOCK_STREAM</constant>, + <constant>SOCK_DGRAM</constant>, …). If the + <parameter>listening</parameter> parameter is positive, it is + checked whether the socket is in accepting mode, i.e. + <function>listen()</function> has been called for it. If + <parameter>listening</parameter> is 0, it is checked whether the + socket is not in this mode. If the parameter is negative, no such + check is made. The <parameter>listening</parameter> parameter + should only be used for stream sockets and should be set to a + negative value otherwise.</para> + + <para><function>sd_is_socket_inet()</function> is similar to + <function>sd_is_socket()</function>, but optionally checks the + IPv4 or IPv6 port number the socket is bound to, unless + <parameter>port</parameter> is zero. For this call + <parameter>family</parameter> must be passed as either + <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or + <constant>AF_INET6</constant>.</para> + + <para><function>sd_is_socket_sockaddr()</function> is similar to + <function>sd_is_socket_inet()</function>, but checks if the socket is bound to the + address specified by <parameter>addr</parameter>. The + <structfield>family</structfield> specified by <parameter>addr</parameter> must be + either <constant>AF_INET</constant> or <constant>AF_INET6</constant> and + <parameter>addr_len</parameter> must be large enough for that family. If + <parameter>addr</parameter> specifies a non-zero port, it is also checked if the + socket is bound to this port. In addition, for IPv6, if <parameter>addr</parameter> + specifies non-zero <structfield>sin6_flowinfo</structfield> or + <structfield>sin6_scope_id</structfield>, it is checked if the socket has the same + values.</para> + + <para><function>sd_is_socket_unix()</function> is similar to + <function>sd_is_socket()</function> but optionally checks the + <constant>AF_UNIX</constant> path the socket is bound to, unless + the <parameter>path</parameter> parameter is + <constant>NULL</constant>. For normal file system + <constant>AF_UNIX</constant> sockets, set the + <parameter>length</parameter> parameter to 0. For Linux abstract + namespace sockets, set the <parameter>length</parameter> to the + size of the address, including the initial 0 byte, and set the + <parameter>path</parameter> to the initial 0 byte of the socket + address.</para> + + <para><function>sd_is_mq()</function> may be called to check + whether the specified file descriptor refers to a POSIX message + queue. If the <parameter>path</parameter> parameter is not + <constant>NULL</constant>, it is checked whether the message queue + is bound to the specified name.</para> + + <para><function>sd_is_special()</function> may be called to check + whether the specified file descriptor refers to a special file. If + the <parameter>path</parameter> parameter is not + <constant>NULL</constant>, 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 + <filename>/proc</filename> or <filename>/sys</filename>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>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.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, these function use a combination of + <filename>fstat()</filename> and + <filename>getsockname()</filename> to check the file descriptor + type and where it is bound to.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>fifo</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_listen_fds" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_listen_fds</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_listen_fds</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_listen_fds</refname> + <refname>sd_listen_fds_with_names</refname> + <refname>SD_LISTEN_FDS_START</refname> + <refpurpose>Check for file descriptors passed by the system manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + + <funcsynopsisinfo>#define SD_LISTEN_FDS_START 3</funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_listen_fds</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_listen_fds_with_names</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>char*** <parameter>names</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_listen_fds()</function> 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. <constant>SD_LISTEN_FDS_START</constant>), the remaining + descriptors follow at 4, 5, 6, …, if any.</para> + + <para>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 + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Nonetheless, it is recommended to verify the correct + socket types before using them. To simplify this checking, the + functions + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry> + 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.</para> + + <para>This function call will set the FD_CLOEXEC flag for all + passed file descriptors to avoid further inheritance to children + of the calling process.</para> + + <para>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 + <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>'s + <literal>FDSTORE=1</literal> messages, these file descriptors are + passed last, in arbitrary order, and with duplicates + removed.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_listen_fds()</function> will unset the + <varname>$LISTEN_FDS</varname>, <varname>$LISTEN_PID</varname> and + <varname>$LISTEN_FDNAMES</varname> environment variables before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + <function>sd_listen_fds()</function> will then return zero, but the + variables are no longer inherited by child processes.</para> + + <para><function>sd_listen_fds_with_names()</function> is like + <function>sd_listen_fds()</function>, but optionally also returns + an array of strings with identification names for the passed file + descriptors, if that is available and the + <parameter>names</parameter> parameter is non-NULL. This + information is read from the <varname>$LISTEN_FDNAMES</varname> + variable, which may contain a colon-separated list of names. For + socket-activated services, these names may be configured with the + <varname>FileDescriptorName=</varname> setting in socket unit + files, see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. For file descriptors pushed into the file descriptor + store (see above), the name is set via the + <varname>FDNAME=</varname> field transmitted via + <function>sd_pid_notify_with_fds()</function>. The primary usecase + for these names are services which accept a variety of file + descriptors which are not recognizable with functions like + <function>sd_is_socket()</function> alone, and thus require + identification via a name. It is recommended to rely on named file + descriptors only if identification via + <function>sd_is_socket()</function> 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 <function>free()</function> + call after use. If the <parameter>names</parameter> parameter is + NULL, the call is entirely equivalent to + <function>sd_listen_fds()</function>.</para> + + <para>Under specific conditions, the following automatic file + descriptor names are returned: + + <table> + <title> + <command>Special names</command> + </title> + + <tgroup cols='2'> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>unknown</literal></entry> + <entry>The process received no name for the specific file descriptor from the service manager.</entry> + </row> + + <row> + <entry><literal>stored</literal></entry> + <entry>The file descriptor originates in the service manager's per-service file descriptor store, and the <varname>FDNAME=</varname> field was absent when the file descriptor was submitted to the service manager.</entry> + </row> + + <row> + <entry><literal>connection</literal></entry> + <entry>The service was activated in per-connection style using <varname>Accept=yes</varname> in the socket unit file, and the file descriptor is the connection socket.</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, these calls returns a negative errno-style error + code. If + <varname>$LISTEN_FDS</varname>/<varname>$LISTEN_PID</varname> 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.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, <function>sd_listen_fds()</function> checks + whether the <varname>$LISTEN_PID</varname> environment variable + equals the daemon PID. If not, it returns immediately. Otherwise, + it parses the number passed in the <varname>$LISTEN_FDS</varname> + 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. <function>sd_listen_fds_with_names()</function> does the + same but also parses <varname>$LISTEN_FDNAMES</varname> if + set.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> + + <listitem><para>Set by the service manager for supervised + processes that use socket-based activation. This environment + variable specifies the data + <function>sd_listen_fds()</function> and + <function>sd_listen_fds_with_names()</function> parses. See + above for details.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_fifo</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_inet</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_is_socket_unix</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_notify_with_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_login_monitor_new" conditional='HAVE_PAM'> + + <refentryinfo> + <title>sd_login_monitor_new</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_login_monitor_new</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_login_monitor_new</refname> + <refname>sd_login_monitor_unref</refname> + <refname>sd_login_monitor_unrefp</refname> + <refname>sd_login_monitor_flush</refname> + <refname>sd_login_monitor_get_fd</refname> + <refname>sd_login_monitor_get_events</refname> + <refname>sd_login_monitor_get_timeout</refname> + <refname>sd_login_monitor</refname> + <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_new</function></funcdef> + <paramdef>const char *<parameter>category</parameter></paramdef> + <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_login_monitor_unrefp</function></funcdef> + <paramdef>sd_login_monitor **<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_flush</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_events</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef> + <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> + <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_login_monitor_new()</function> 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 <literal>seat</literal> (to get only notifications about + seats being added, removed or changed), <literal>session</literal> + (to get only notifications about sessions being created or removed + or changed), <literal>uid</literal> (to get only notifications + when a user changes state in respect to logins) or + <literal>machine</literal> (to get only notifications when a + virtual machine or container is started or stopped). If + notifications shall be generated in all these conditions, + <constant>NULL</constant> 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 + <function>sd_login_monitor_unref()</function> call after + use.</para> + + <para><function>sd_login_monitor_unref()</function> may be used to + destroy a monitor object. Note that this will invalidate any file + descriptor returned by + <function>sd_login_monitor_get_fd()</function>.</para> + + <para><function>sd_login_monitor_unrefp()</function> is similar to + <function>sd_login_monitor_unref()</function> but takes a pointer + to a pointer to an <type>sd_login_monitor</type> object. This call + is useful in conjunction with GCC's and LLVM's <ulink + url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up + Variable Attribute</ulink>. 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:</para> + + <programlisting>{ + __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)); + … +}</programlisting> + + <para><function>sd_login_monitor_flush()</function> 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.</para> + + <para><function>sd_login_monitor_unref()</function> and + <function>sd_login_monitor_unrefp()</function> execute no + operation if the passed in monitor object is + <constant>NULL</constant>.</para> + + <para><function>sd_login_monitor_get_fd()</function> may be used + to retrieve the file descriptor of the monitor object that may be + integrated in an application defined event loop, based around + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> + or a similar interface. The application should include the + returned file descriptor as wake-up source for the events mask + returned by <function>sd_login_monitor_get_events()</function>. It + should pass a timeout value as returned by + <function>sd_login_monitor_get_timeout()</function>. Whenever a + wake-up is triggered the file descriptor needs to be reset via + <function>sd_login_monitor_flush()</function>. An application + needs to reread the login state with a function like + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or similar to determine what changed.</para> + + <para><function>sd_login_monitor_get_events()</function> will + return the <function>poll()</function> mask to wait for. This + function will return a combination of <constant>POLLIN</constant>, + <constant>POLLOUT</constant> and similar to fill into the + <literal>.events</literal> field of <varname>struct + pollfd</varname>.</para> + + <para><function>sd_login_monitor_get_timeout()</function> will + return a timeout value for usage in <function>poll()</function>. + This returns a value in microseconds since the epoch of + <constant>CLOCK_MONOTONIC</constant> for timing out + <function>poll()</function> in <varname>timeout_usec</varname>. + See + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + for details about <constant>CLOCK_MONOTONIC</constant>. If there + is no timeout to wait for this will fill in <constant>(uint64_t) + -1</constant> instead. Note that <function>poll()</function> 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:</para> + + <programlisting>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; +}</programlisting> + + <para>The code above does not do any error checking for brevity's + sake. The calculated <varname>msec</varname> integer can be passed + directly as <function>poll()</function>'s timeout + parameter.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, + <function>sd_login_monitor_new()</function>, + <function>sd_login_monitor_flush()</function> and + <function>sd_login_monitor_get_timeout()</function> + return 0 or a positive integer. On success, + <function>sd_login_monitor_get_fd()</function> returns + a Unix file descriptor. On success, + <function>sd_login_monitor_get_events()</function> + returns a combination of <constant>POLLIN</constant>, + <constant>POLLOUT</constant> and suchlike. On failure, + these calls return a negative errno-style error + code.</para> + + <para><function>sd_login_monitor_unref()</function> + always returns <constant>NULL</constant>.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that is not accepted). The specified category to + watch is not known.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_login_monitor_new()</function>, + <function>sd_login_monitor_unref()</function>, + <function>sd_login_monitor_flush()</function>, + <function>sd_login_monitor_get_fd()</function>, + <function>sd_login_monitor_get_events()</function> and + <function>sd_login_monitor_get_timeout()</function> + interfaces are available as a shared library, which can be + compiled and linked to with the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_pid_get_session" conditional='HAVE_PAM'> + + <refentryinfo> + <title>sd_pid_get_session</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_pid_get_session</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_pid_get_session</refname> + <refname>sd_pid_get_unit</refname> + <refname>sd_pid_get_user_unit</refname> + <refname>sd_pid_get_owner_uid</refname> + <refname>sd_pid_get_machine_name</refname> + <refname>sd_pid_get_slice</refname> + <refname>sd_pid_get_user_slice</refname> + <refname>sd_pid_get_cgroup</refname> + <refname>sd_peer_get_session</refname> + <refname>sd_peer_get_unit</refname> + <refname>sd_peer_get_user_unit</refname> + <refname>sd_peer_get_owner_uid</refname> + <refname>sd_peer_get_machine_name</refname> + <refname>sd_peer_get_slice</refname> + <refname>sd_peer_get_user_slice</refname> + <refname>sd_peer_get_cgroup</refname> + <refpurpose>Determine session, unit, owner of a session, + container/VM or slice of a specific PID or socket + peer</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_pid_get_session</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>session</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_unit</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_user_unit</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_machine_name</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_slice</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_user_slice</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_cgroup</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>cgroup</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_session</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>session</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_unit</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_user_unit</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_machine_name</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_slice</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_user_slice</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>slice</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_cgroup</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>cgroup</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_pid_get_session()</function> 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 + <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_pid_get_unit()</function> 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 <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_pid_get_user_unit()</function> 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 <function>sd_pid_get_unit()</function>, but applies to + user units instead of system units.</para> + + <para><function>sd_pid_get_owner_uid()</function> 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 + <function>sd_pid_get_session()</function> 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.</para> + + <para><function>sd_pid_get_machine_name()</function> 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 + <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use. For processes not part of a VM or containers, this + function fails with -ENODATA.</para> + + <para><function>sd_pid_get_slice()</function> may be used to + determine the slice unit the process is a member of. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details about slices. The returned string needs to be freed + with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para>Similarly, <function>sd_pid_get_user_slice()</function> + returns the user slice (as managed by the user's systemd instance) + of a process.</para> + + <para><function>sd_pid_get_cgroup()</function> 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 + <filename>/sys/fs/cgroup/</filename> (if the unified control group + setup is used), or + <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename> + (if the legacy multi-hierarchy control group setup is used).</para> + + <para>If the <varname>pid</varname> parameter of any of these + functions is passed as 0, the operation is executed for the + calling process.</para> + + <para>The <function>sd_peer_get_session()</function>, + <function>sd_peer_get_unit()</function>, + <function>sd_peer_get_user_unit()</function>, + <function>sd_peer_get_owner_uid()</function>, + <function>sd_peer_get_machine_name()</function>, + <function>sd_peer_get_slice()</function>, + <function>sd_peer_get_user_slice()</function> and + <function>sd_peer_get_cgroup()</function> 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 <filename>/proc</filename>, + and hence are not suitable for authorization purposes, as they are + subject to races.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these calls return 0 or a positive integer. On + failure, these calls return a negative errno-style error + code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ESRCH</constant></term> + + <listitem><para>The specified PID does not refer to a running + process.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-BADF</constant></term> + + <listitem><para>The specified socket file descriptor was + invalid.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The given field is not specified for the described + process or peer.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An input parameter was invalid (out of range, + or NULL, where that is not accepted).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_pid_get_session()</function>, + <function>sd_pid_get_unit()</function>, + <function>sd_pid_get_user_unit()</function>, + <function>sd_pid_get_owner_uid()</function>, + <function>sd_pid_get_machine_name()</function>, + <function>sd_pid_get_slice()</function>, + <function>sd_pid_get_user_slice()</function>, + <function>sd_peer_get_session()</function>, + <function>sd_peer_get_unit()</function>, + <function>sd_peer_get_user_unit()</function>, + <function>sd_peer_get_owner_uid()</function>, + <function>sd_peer_get_machine_name()</function>, + <function>sd_peer_get_slice()</function> and + <function>sd_peer_get_user_slice()</function> interfaces are + available as a shared library, which can be compiled and linked to + with the <constant>libelogind</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + file.</para> + + <para>Note that the login session identifier as + returned by <function>sd_pid_get_session()</function> + is completely unrelated to the process session + identifier as returned by + <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> 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 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of systemd. + + Copyright 2010 Lennart Poettering + + systemd is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or + (at your option) any later version. + + systemd is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with systemd; If not, see <http://www.gnu.org/licenses/>. +--> + +<refentry id="sd_uid_get_state" conditional='HAVE_PAM'> + + <refentryinfo> + <title>sd_uid_get_state</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_uid_get_state</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_uid_get_state</refname> + <refname>sd_uid_is_on_seat</refname> + <refname>sd_uid_get_sessions</refname> + <refname>sd_uid_get_seats</refname> + <refname>sd_uid_get_display</refname> + <refpurpose>Determine login state of a specific Unix user ID</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_uid_get_state</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>char **<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_is_on_seat</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>const char *<parameter>seat</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_sessions</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>char ***<parameter>sessions</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_seats</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>int <parameter>require_active</parameter></paramdef> + <paramdef>char ***<parameter>seats</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_uid_get_display</function></funcdef> + <paramdef>uid_t <parameter>uid</parameter></paramdef> + <paramdef>char **<parameter>session</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_uid_get_state()</function> may be used to + determine the login state of a specific Unix user identifier. The + following states are currently known: <literal>offline</literal> + (user not logged in at all), <literal>lingering</literal> (user + not logged in, but some user services running), + <literal>online</literal> (user logged in, but not active, i.e. + has no session in the foreground), <literal>active</literal> (user + logged in, and has at least one active session, i.e. one session + in the foreground), <literal>closing</literal> (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 + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_uid_is_on_seat()</function> 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 + <parameter>require_active</parameter> 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.</para> + + <para><function>sd_uid_get_sessions()</function> may be used to + determine the current sessions of the specified user. Accepts a + Unix user identifier as parameter. The + <parameter>require_active</parameter> 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 + <constant>NULL</constant> terminated string array of session + identifiers in <parameter>sessions</parameter> which needs to be + freed by the caller with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use, including all the strings referenced. If the + string array parameter is passed as <constant>NULL</constant>, 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 <constant>NULL</constant> may be returned and should be + considered equivalent to an empty array.</para> + + <para>Similarly, <function>sd_uid_get_seats()</function> 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 + <function>sd_uid_get_sessions()</function>.</para> + + <para><function>sd_uid_get_display()</function> 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.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_uid_get_state()</function> returns + 0 or a positive integer. If the test succeeds, + <function>sd_uid_is_on_seat()</function> returns a positive + integer; if it fails, 0. + <function>sd_uid_get_sessions()</function> and + <function>sd_uid_get_seats()</function> return the number of + entries in the returned arrays. + <function>sd_uid_get_display()</function> returns a non-negative + code on success. On failure, these calls return a negative + errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + + <varlistentry> + <term><constant>-ENODATA</constant></term> + + <listitem><para>The given field is not specified for the described + user.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENXIO</constant></term> + + <listitem><para>The specified seat is unknown.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>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.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Memory allocation failed.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>Functions described here are available as a shared library, + and can be compiled and linked to using the + <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + entry.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |