man/sd_bus_message_append_basic.3

   1 '\" t
   2 .TH "SD_BUS_MESSAGE_APPEND_BASIC" "3" "" "systemd 215" "sd_bus_message_append_basic"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 sd_bus_message_append_basic \- Attach a single part to a message
  24 .SH "SYNOPSIS"
  25 .sp
  26 .ft B
  27 .nf
  28 #include <systemd/sd\-bus\&.h>
  29 .fi
  30 .ft
  31 .HP \w'int\ sd_bus_message_append_basic('u
  32 .BI "int sd_bus_message_append_basic(sd_bus_message\ *" "m" ", char\ " "type" ", char\ void\ *" "p" ");"
  33 .SH "DESCRIPTION"
  34 .PP
  35 \fBsd_bus_message_append_basic\fR
  36 appends a single item to the message
  37 \fIm\fR\&. Parameter
  38 \fItype\fR
  39 determines how pointer
  40 \fIp\fR
  41 is interpreted\&.
  42 \fItype\fR
  43 must be one of the basic types as defined by the
  44 \m[blue]\fBBasic Types\fR\m[]\&\s-2\u[1]\d\s+2
  45 section of the D\-Bus specification, and listed in the table below\&.
  46 .sp
  47 .it 1 an-trap
  48 .nr an-no-space-flag 1
  49 .nr an-break-flag 1
  50 .br
  51 .B Table\ \&1.\ \&Item format specifiers
  52 .TS
  53 allbox tab(:);
  54 lB lB lB lB.
  55 T{
  56 Specifier
  57 T}:T{
  58 Constant
  59 T}:T{
  60 Description
  61 T}:T{
  62 Size
  63 T}
  64 .T&
  65 l l l l
  66 l l l l
  67 l l l l
  68 l l l l
  69 l l l l
  70 l l l l
  71 l l l l
  72 l l l l
  73 l l l l
  74 l l l l
  75 l l l l
  76 l l l l
  77 l l l l.
  78 T{
  79 "y"
  80 T}:T{
  81 \fBSD_BUS_TYPE_BYTE\fR
  82 T}:T{
  83 unsigned interger
  84 T}:T{
  85 1 byte
  86 T}
  87 T{
  88 "b"
  89 T}:T{
  90 \fBSD_BUS_TYPE_BOOLEAN\fR
  91 T}:T{
  92 boolean
  93 T}:T{
  94 4 bytes
  95 T}
  96 T{
  97 "n"
  98 T}:T{
  99 \fBSD_BUS_TYPE_INT16\fR
 100 T}:T{
 101 signed integer
 102 T}:T{
 103 2 bytes
 104 T}
 105 T{
 106 "q"
 107 T}:T{
 108 \fBSD_BUS_TYPE_UINT16\fR
 109 T}:T{
 110 unsigned integer
 111 T}:T{
 112 2 bytes
 113 T}
 114 T{
 115 "i"
 116 T}:T{
 117 \fBSD_BUS_TYPE_INT32\fR
 118 T}:T{
 119 signed integer
 120 T}:T{
 121 4 bytes
 122 T}
 123 T{
 124 "u"
 125 T}:T{
 126 \fBSD_BUS_TYPE_UINT32\fR
 127 T}:T{
 128 unsigned integer
 129 T}:T{
 130 4 bytes
 131 T}
 132 T{
 133 "x"
 134 T}:T{
 135 \fBSD_BUS_TYPE_INT64\fR
 136 T}:T{
 137 signed integer
 138 T}:T{
 139 8 bytes
 140 T}
 141 T{
 142 "t"
 143 T}:T{
 144 \fBSD_BUS_TYPE_UINT64\fR
 145 T}:T{
 146 unsigned integer
 147 T}:T{
 148 8 bytes
 149 T}
 150 T{
 151 "d"
 152 T}:T{
 153 \fBSD_BUS_TYPE_DOUBLE\fR
 154 T}:T{
 155 floating\-point
 156 T}:T{
 157 8 bytes
 158 T}
 159 T{
 160 "s"
 161 T}:T{
 162 \fBSD_BUS_TYPE_STRING\fR
 163 T}:T{
 164 Unicode string
 165 T}:T{
 166 variable
 167 T}
 168 T{
 169 "o"
 170 T}:T{
 171 \fBSD_BUS_TYPE_OBJECT_PATH\fR
 172 T}:T{
 173 object path
 174 T}:T{
 175 variable
 176 T}
 177 T{
 178 "g"
 179 T}:T{
 180 \fBSD_BUS_TYPE_SIGNATURE\fR
 181 T}:T{
 182 signature
 183 T}:T{
 184 variable
 185 T}
 186 T{
 187 "h"
 188 T}:T{
 189 \fBSD_BUS_TYPE_UNIX_FD\fR
 190 T}:T{
 191 UNIX file descriptor
 192 T}:T{
 193 4 bytes
 194 T}
 195 .TE
 196 .sp 1
 197 .PP
 198 The value of the parameter is copied into the memory area containing the message and may be changed after this call\&. If
 199 \fItype\fR
 200 is
 201 "h"
 202 (UNIX file descriptor), it is always "consumed" by this call, and either successfully appended to the message or closed\&.
 203 .PP
 204 For types
 205 "s",
 206 "o", and
 207 "g", the parameter
 208 \fIp\fR
 209 is interpreted as a pointer to a
 210 \fBNUL\fR\-terminated character sequence\&. As a special case, a
 211 \fBNULL\fR
 212 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 recepient of the message\&.
 213 .SH "RETURN VALUE"
 214 .PP
 215 On success, this call returns 0 or a positive integer\&. On failure, it returns a negative errno\-style error code\&.
 216 .SH "ERRORS"
 217 .PP
 218 Returned errors may indicate the following problems:
 219 .PP
 220 \fI\-EINVAL\fR
 221 .RS 4
 222 Specified parameter is invalid\&.
 223 .RE
 224 .PP
 225 \fI\-EPERM\fR
 226 .RS 4
 227 Message has been sealed\&.
 228 .RE
 229 .PP
 230 \fI\-ESTALE\fR
 231 .RS 4
 232 Message is in invalid state\&.
 233 .RE
 234 .PP
 235 \fI\-ENXIO\fR
 236 .RS 4
 237 Message cannot be appended to\&.
 238 .RE
 239 .PP
 240 \fI\-ENOMEM\fR
 241 .RS 4
 242 Memory allocation failed\&.
 243 .RE
 244 .SH "NOTES"
 245 .PP
 246 The
 247 \fBsd_bus_append_basic()\fR
 248 function described here is available as a shared library, which can be compiled and linked to with the
 249 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
 250 file\&.
 251 .SH "SEE ALSO"
 252 .PP
 253 \fBsystemd\fR(1),
 254 \fBsd-bus\fR(3),
 255 \fBsd_bus_message_append\fR(3),
 256 \m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2
 257 .SH "NOTES"
 258 .IP " 1." 4
 259 Basic Types
 260 .RS 4
 261 \%http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types
 262 .RE
 263 .IP " 2." 4
 264 The D-Bus specification
 265 .RS 4
 266 \%http://dbus.freedesktop.org/doc/dbus-specification.html
 267 .RE