Debian Codegraph @

upstream/debian-unstable/man3/sd_varlink_server_new.3

raw
1 '\" t
2 .TH "SD_VARLINK_SERVER_NEW" "3" "" "systemd 261~rc3" "sd_varlink_server_new"
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_varlink_server_new \- Allocate Varlink server object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-varlink\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_varlink_server_new('u
32 .BI "int sd_varlink_server_new(sd_varlink_server**\ " "ret" ", sd_varlink_server_flags_t\ " "flags" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_varlink_server_new()\fR
36 allocates a new Varlink server object\&. Initially the server does not listen on any socket or file descriptor\&. The newly allocated server object is returned in the
37 \fIret\fR
38 parameter\&. Use
39 \fBsd_varlink_server_unref()\fR
40 to release the server object again after use\&.
41 .PP
42 The following flags may be passed in the
43 \fIflags\fR
44 parameter:
45 .sp
46 .RS 4
47 .ie n \{\
48 \h'-04'\(bu\h'+03'\c
49 .\}
50 .el \{\
51 .sp -1
52 .IP \(bu 2.3
53 .\}
54 \fBSD_VARLINK_SERVER_ROOT_ONLY\fR: only allow connections from UID 0 (i\&.e\&. the root user)\&. This has two effects: any incoming connections is authenticated via
55 \fBSO_PEERCRED\fR
56 ensuring the UID reported by the kernel is zero\&. If this check fails the connection is immediately terminated\&. Moreover, when binding a socket inode in the file system, the access mode is set to 0600 (rather than 0666)\&. If this option is used connections on non\-\fBAF_UNIX\fR
57 sockets or via pipes are never permitted\&.
58 .RE
59 .sp
60 .RS 4
61 .ie n \{\
62 \h'-04'\(bu\h'+03'\c
63 .\}
64 .el \{\
65 .sp -1
66 .IP \(bu 2.3
67 .\}
68 \fBSD_VARLINK_SERVER_MYSELF_ONLY\fR: this is very similar to
69 \fBSD_VARLINK_SERVER_ROOT_ONLY\fR
70 but enforces that the connecting client\*(Aqs UID must match the server\*(Aqs UID (i\&.e\&. the UID this function is invoked as)\&. For servers that run as UID 0 the flags are equivalent\&. If both flags are specified in combination, connections are allowed by both UID 0 and the server\*(Aqs own UID\&.
71 .RE
72 .sp
73 .RS 4
74 .ie n \{\
75 \h'-04'\(bu\h'+03'\c
76 .\}
77 .el \{\
78 .sp -1
79 .IP \(bu 2.3
80 .\}
81 \fBSD_VARLINK_SERVER_ACCOUNT_UID\fR: if set connection accounting per client UID is enabled, and a limit on concurrent connections from the same UID is enforced\&. The limit can be set via
82 \fBsd_varlink_server_set_connections_per_uid_max()\fR, and defaults to 3/4th of the total concurrent connection limit, as settable via
83 \fBsd_varlink_server_set_connections_max()\fR\&.
84 .RE
85 .sp
86 .RS 4
87 .ie n \{\
88 \h'-04'\(bu\h'+03'\c
89 .\}
90 .el \{\
91 .sp -1
92 .IP \(bu 2.3
93 .\}
94 \fBSD_VARLINK_SERVER_INHERIT_USERDATA\fR: if set the user data field for incoming connection (i\&.e\&.
95 \fBsd_varlink\fR) objects (as settable via
96 \fBsd_varlink_set_userdata()\fR) is automatically set to the userdata field of the server (i\&.e\&.
97 \fBsd_varlink_server\fR) object (as settable via
98 \fBsd_varlink_server_set_userdata()\fR)\&. If this flag is not specified the connection\*(Aqs user data field will default to
99 \fBNULL\fR\&.
100 .RE
101 .sp
102 .RS 4
103 .ie n \{\
104 \h'-04'\(bu\h'+03'\c
105 .\}
106 .el \{\
107 .sp -1
108 .IP \(bu 2.3
109 .\}
110 \fBSD_VARLINK_SERVER_INPUT_SENSITIVE\fR: mark all incoming method call parameters as security sensitive (equivalent to calling
111 \fBsd_json_variant_sensitive()\fR)\&. This is useful for services that deal with secrets and similar, as it ensures that the parameters are kept out of debug logging, and memory used by the parameters is erased after use\&.
112 .RE
113 .sp
114 .RS 4
115 .ie n \{\
116 \h'-04'\(bu\h'+03'\c
117 .\}
118 .el \{\
119 .sp -1
120 .IP \(bu 2.3
121 .\}
122 \fBSD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT\fR: if set, allow receiving UNIX file descriptors via the connections, equivalent to calling
123 \fBsd_varlink_set_allow_fd_passing_input()\fR
124 immediately for each incoming connection\&. Note that this only has an effect if
125 \fBAF_UNIX\fR
126 sockets are used for communication\&.
127 .RE
128 .sp
129 .RS 4
130 .ie n \{\
131 \h'-04'\(bu\h'+03'\c
132 .\}
133 .el \{\
134 .sp -1
135 .IP \(bu 2.3
136 .\}
137 \fBSD_VARLINK_SERVER_ALLOW_FD_PASSING_OUTPUT\fR: similar, but controls sending of UNIX file descriptors\&.
138 .RE
139 .sp
140 .RS 4
141 .ie n \{\
142 \h'-04'\(bu\h'+03'\c
143 .\}
144 .el \{\
145 .sp -1
146 .IP \(bu 2.3
147 .\}
148 \fBSD_VARLINK_SERVER_FD_PASSING_INPUT_STRICT\fR: this flag can be used in conjunction with
149 \fBSD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT\fR\&. If so, file descriptor passing is turned off on the listening sockets already, ensuring that the connection sockets derived from it at no time have file descriptor passing enabled\&. If
150 \fBSD_VARLINK_SERVER_ALLOW_FD_PASSING_INPUT\fR
151 is used without
152 \fBSD_VARLINK_SERVER_FD_PASSING_INPUT_STRICT\fR
153 then a choice when to prohibit or allow file descriptor passing can still be made after the connection came in, however permitting a time window where file descriptors might already be enqueued, that then need to be dropped again\&.
154 .RE
155 .sp
156 .RS 4
157 .ie n \{\
158 \h'-04'\(bu\h'+03'\c
159 .\}
160 .el \{\
161 .sp -1
162 .IP \(bu 2.3
163 .\}
164 \fBSD_VARLINK_SERVER_HANDLE_SIGINT\fR: if set, and
165 \fBsd_varlink_server_loop_auto()\fR
166 is used, incoming
167 \fBSIGINT\fR
168 process signals will be caught gracefully and cause the event loop to exit cleanly\&.
169 .RE
170 .sp
171 .RS 4
172 .ie n \{\
173 \h'-04'\(bu\h'+03'\c
174 .\}
175 .el \{\
176 .sp -1
177 .IP \(bu 2.3
178 .\}
179 \fBSD_VARLINK_SERVER_HANDLE_SIGTERM\fR: similar, but does the same for
180 \fBSIGTERM\fR\&.
181 .RE
182 .SH "RETURN VALUE"
183 .PP
184 On success,
185 \fBsd_varlink_server_new()\fR
186 returns a non\-negative integer\&. On failure, it returns a negative errno\-style error code\&.
187 .SS "Errors"
188 .PP
189 Returned errors may indicate the following problems:
190 .PP
191 \fB\-EINVAL\fR
192 .RS 4
193 An argument is invalid\&.
194 .RE
195 .SH "NOTES"
196 .PP
197 Functions described here are available as a shared library, which can be compiled against and linked to with the
198 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
199 file\&.
200 .PP
201 The code described here uses
202 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
203 \fBsetenv\fR(3)
204 from a parallel thread\&. It is recommended to only do calls to
205 \fBsetenv()\fR
206 from an early phase of the program when no other threads have been started\&.
207 .SH "HISTORY"
208 .PP
209 \fBsd_varlink_server_new()\fR
210 was added in version 257\&.
211 .SH "SEE ALSO"
212 .PP
213 \fBsystemd\fR(1), \fBsd-varlink\fR(3)