Imported Upstream version 220

[systemd.git] / man / sd_bus_error.3

'\" t
.TH "SD_BUS_ERROR" "3" "" "systemd 220" "sd_bus_error"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_bus_error, sd_bus_error_free, sd_bus_error_set, sd_bus_error_set_const, sd_bus_error_set_errno, sd_bus_error_set_errnof, sd_bus_error_get_errno, sd_bus_error_copy, sd_bus_error_is_set, sd_bus_error_has_name \- sd\-bus error handling
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-bus\&.h>
.fi
.ft
.sp
.ft B
.nf
typedef struct {
        const char *name;
        const char *message;
        \&.\&.\&.
} sd_bus_error;
.fi
.ft
.PP
\fBSD_BUS_ERROR_MAKE_CONST(\fR\fB\fIname\fR\fR\fB, \fR\fB\fImessage\fR\fR\fB)\fR
.PP
\fBSD_BUS_ERROR_NULL\fR
.HP \w'int\ sd_bus_error_free('u
.BI "int sd_bus_error_free(sd_bus_error\ *" "e" ");"
.HP \w'int\ sd_bus_error_set('u
.BI "int sd_bus_error_set(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "message" ");"
.HP \w'int\ sd_bus_error_setf('u
.BI "int sd_bus_error_setf(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "format" ", \&.\&.\&.);"
.HP \w'int\ sd_bus_error_set_const('u
.BI "int sd_bus_error_set_const(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "message" ");"
.HP \w'int\ sd_bus_error_set_errno('u
.BI "int sd_bus_error_set_errno(sd_bus_error\ *" "e" ", int\ " "error" ");"
.HP \w'int\ sd_bus_error_set_errnof('u
.BI "int sd_bus_error_set_errnof(sd_bus_error\ *" "e" ", int\ " "error" ", const\ char\ *" "format" ", \&.\&.\&.);"
.HP \w'int\ sd_bus_error_get_errno('u
.BI "int sd_bus_error_get_errno(const\ sd_bus_error\ *" "e" ");"
.HP \w'int\ sd_bus_error_copy('u
.BI "int sd_bus_error_copy(sd_bus_error\ *" "dst" ", const\ sd_bus_error\ *" "e" ");"
.HP \w'int\ sd_bus_error_is_set('u
.BI "int sd_bus_error_is_set(const\ sd_bus_error\ *" "e" ");"
.HP \w'int\ sd_bus_error_has_name('u
.BI "int sd_bus_error_has_name(const\ sd_bus_error\ *" "e" ", const\ char\ *" "name" ");"
.PP
\fBSD_BUS_ERROR_FAILED\fR
.PP
\fBSD_BUS_ERROR_NO_MEMORY\fR
.PP
\fBSD_BUS_ERROR_SERVICE_UNKNOWN\fR
.PP
\fBSD_BUS_ERROR_NAME_HAS_NO_OWNER\fR
.PP
\fBSD_BUS_ERROR_NO_REPLY\fR
.PP
\fBSD_BUS_ERROR_IO_ERROR\fR
.PP
\fBSD_BUS_ERROR_BAD_ADDRESS\fR
.PP
\fBSD_BUS_ERROR_NOT_SUPPORTED\fR
.PP
\fBSD_BUS_ERROR_LIMITS_EXCEEDED\fR
.PP
\fBSD_BUS_ERROR_ACCESS_DENIED\fR
.PP
\fBSD_BUS_ERROR_AUTH_FAILED\fR
.PP
\fBSD_BUS_ERROR_NO_SERVER\fR
.PP
\fBSD_BUS_ERROR_TIMEOUT\fR
.PP
\fBSD_BUS_ERROR_NO_NETWORK\fR
.PP
\fBSD_BUS_ERROR_ADDRESS_IN_USE\fR
.PP
\fBSD_BUS_ERROR_DISCONNECTED\fR
.PP
\fBSD_BUS_ERROR_INVALID_ARGS\fR
.PP
\fBSD_BUS_ERROR_FILE_NOT_FOUND\fR
.PP
\fBSD_BUS_ERROR_FILE_EXISTS\fR
.PP
\fBSD_BUS_ERROR_UNKNOWN_METHOD\fR
.PP
\fBSD_BUS_ERROR_UNKNOWN_OBJECT\fR
.PP
\fBSD_BUS_ERROR_UNKNOWN_INTERFACE\fR
.PP
\fBSD_BUS_ERROR_UNKNOWN_PROPERTY\fR
.PP
\fBSD_BUS_ERROR_PROPERTY_READ_ONLY\fR
.PP
\fBSD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN\fR
.PP
\fBSD_BUS_ERROR_INVALID_SIGNATURE\fR
.PP
\fBSD_BUS_ERROR_INCONSISTENT_MESSAGE\fR
.PP
\fBSD_BUS_ERROR_MATCH_RULE_NOT_FOUND\fR
.PP
\fBSD_BUS_ERROR_MATCH_RULE_INVALID\fR
.SH "DESCRIPTION"
.PP
The
sd_bus_error
structure carries information for a
sd\-bus
error\&. The functions described below can be used to set and query fields in this structure\&. The
\fIname\fR
field contains a short identifier of an error\&. It should follow the rules for error names described in the D\-Bus specification, subsection
\m[blue]\fBValid Names\fR\m[]\&\s-2\u[1]\d\s+2\&. The
\fImessage\fR
is a human readable string describing the details\&. When no longer necessary, resources held by this structure should be destroyed with
\fBsd_bus_error_free\fR\&.
.PP
\fBsd_bus_error_set\fR
will return an errno\-like negative value returned based on parameter
\fIname\fR
(see
\fBerrno\fR(3))\&. Various well\-known D\-Bus errors are converted to specific values, and the remaining ones to
\fB\-ENXIO\fR\&. Well\-known D\-Bus error names are available as constants
\fBSD_BUS_ERROR_FAILED\fR, etc\&., listed above\&. If
\fIname\fR
is
\fBNULL\fR, it is assumed that no error occurred, and 0 is returned\&. This means that this function may be conveniently used in a
\fBreturn\fR
statement\&.
.PP
If
\fIe\fR
is not
\fBNULL\fR,
\fIname\fR
and
\fImessage\fR
in the
sd_bus_error
structure
\fIe\fR
points at will be filled in\&. As described above,
\fIname\fR
may be
\fBNULL\fR, which is treated as no error\&. Parameter
\fImessage\fR
may also be
\fBNULL\fR, in which case no message is specified\&.
\fBsd_bus_error_set\fR
will make internal copies of specified strings\&.
.PP
\fBsd_bus_error_setf\fR
is similar to
\fBsd_bus_error_set\fR, but takes a
\fBprintf\fR(3)
format string and corresponding arguments to generate
message\&.
.PP
\fBsd_bus_error_set_const\fR
is similar to
\fBsd_bus_error_set\fR, but string parameters are not copied internally, and must remain valid for the lifetime of
\fIe\fR\&.
.PP
\fBsd_bus_error_set_errno\fR
will set
\fIname\fR
based on an errno\-like value\&.
\fBstrerror\fR(3)
will be used to set
\fImessage\fR\&. Well\-known D\-Bus error names will be used for
\fIname\fR
if available, otherwise a name in the
"System\&.Error"
namespace will be generated\&.
.PP
\fBsd_bus_error_set_errnof\fR
is similar to
\fBsd_bus_error_set_errno\fR, but in addition to
\fIname\fR, takes a
\fBprintf\fR(3)
format and corresponding arguments\&.
\fIname\fR
will be generated from
\fIformat\fR
and the arguments\&.
.PP
\fBsd_bus_error_get_errno\fR
will convert
e\->name
to an errno\-like value using the same rules as
\fBsd_bus_error_set\fR\&. If
\fIe\fR
is
\fBNULL\fR, 0 will be returned\&.
.PP
\fBsd_bus_error_copy\fR
will initialize
\fIdst\fR
using the values in
\fIe\fR\&. If the strings in
\fIe\fR
were set using
\fBsd_bus_set_error_const\fR, they will be shared\&. Otherwise, they will be copied\&.
.PP
\fBsd_bus_error_is_set\fR
will return
\fBtrue\fR
if
\fIe\fR
is non\-\fBNULL\fR
and an error has been set,
\fBfalse\fR
otherwise\&.
.PP
\fBsd_bus_error_has_name\fR
will return true if
\fIe\fR
is non\-\fBNULL\fR
and an error with the same
\fIname\fR
has been set,
\fBfalse\fR
otherwise\&.
.PP
\fBsd_bus_error_free\fR
will destroy resources held by
\fIe\fR\&. The parameter itself will not be deallocated, and must be
\fBfree\fR(3)d by the caller if necessary\&.
.SH "RETURN VALUE"
.PP
Functions
\fBsd_bus_error_set\fR,
\fBsd_bus_error_setf\fR,
\fBsd_bus_error_set_const\fR, when successful, return the negative errno value corresponding to the
\fIname\fR
parameter\&. Functions
\fBsd_bus_error_set_errno\fR
and
\fBsd_bus_error_set_errnof\fR, when successful, return the value of the
\fIerrno\fR
parameter\&. If an error occurs, one of the negative error values listed below will be returned\&.
.PP
\fBsd_bus_error_get_errno\fR
returns
\fBfalse\fR
when
\fIe\fR
is
\fBNULL\fR, and a positive errno value mapped from
\fIe\->name\fR
otherwise\&.
.PP
\fBsd_bus_error_copy\fR
returns 0 or a positive integer on success, and one of the negative error values listed below otherwise\&.
.PP
\fBsd_bus_error_is_set\fR
returns
\fBtrue\fR
when
\fIe\fR
and
\fIe\->name\fR
are non\-\fBNULL\fR,
\fBfalse\fR
otherwise\&.
.PP
\fBsd_bus_error_has_name\fR
returns
\fBtrue\fR
when
\fIe\fR
is non\-\fBNULL\fR
and
\fIe\->name\fR
is equal to
\fIname\fR,
\fBfalse\fR
otherwise\&.
.SH "REFERENCE OWNERSHIP"
.PP
sd_bus_error
is not reference counted\&. Users should destroy resources held by it by calling
\fBsd_bus_error_free\fR\&.
.SH "ERRORS"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-EINVAL\fR
.RS 4
Error was already set in
sd_bus_error
structure when one the error\-setting functions was called\&.
.RE
.PP
\fB\-ENOMEM\fR
.RS 4
Memory allocation failed\&.
.RE
.SH "NOTES"
.PP
\fBsd_bus_set_error()\fR
and other functions described here are available as a shared library, which can be compiled and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd-bus\fR(3),
\fBerrno\fR(3),
\fBstrerror\fR(3)
.SH "NOTES"
.IP " 1." 4
Valid Names
.RS 4
\%http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names
.RE