On 3/23/23 20:17, Eric Blake wrote:
> On Thu, Mar 23, 2023 at 01:10:15PM +0100, Laszlo Ersek wrote:
>> From: "Richard W.M. Jones" <rjo...@redhat.com>
>>
>> To allow us to name the socket passed down to the NBD server when
>> calling nbd_connect_systemd_socket_activation(3), we need to add the
>> field to the handle and add access functions.
>>
>> [Laszlo's note: originally posted by Rich at
>> <https://listman.redhat.com/archives/libguestfs/2023-January/030557.html>.
>> I've renamed "sa_name" to "sact_name", due to <signal.h> reserving symbols
>> with the "sa_" prefix. This corresponds to earlier patches in this series,
>> such as 'socket activation: rename sa_(tmpdir|sockpath) to
>> sact_(tmpdir|sockpath)' and 'ocaml: rename "sa_u" to "saddr_u"'.]
>>
>> Message-Id: <20230130225521.1771496-4-rjo...@redhat.com>
>> Signed-off-by: Laszlo Ersek <ler...@redhat.com>
>> Reviewed-by: Richard W.M. Jones <rjo...@redhat.com>
>> ---
>>
>
>> +++ b/generator/API.ml
>> @@ -2036,15 +2036,62 @@ "connect_systemd_socket_activation", {
>>
>> When the NBD handle is closed the server subprocess
>> is killed.
>> +
>> +=head3 Socket name
>> +
>> +The socket activation protocol lets you optionally give
>> +the socket a name. If used, the name is passed to the
>> +NBD server using the C<LISTEN_FDNAMES> environment
>> +variable. To provide a socket name, call
>> +L<nbd_set_socket_activation_name(3)> before calling
>> +the connect function.
>> " ^ blocking_connect_call_description;
>> see_also = [Link "aio_connect_systemd_socket_activation";
>> Link "connect_command"; Link "kill_subprocess";
>> Link "set_opt_mode";
>> + Link "set_socket_activation_name";
>> + Link "get_socket_activation_name";
>> ExternalLink ("qemu-nbd", 1);
>> URLLink
>> "http://0pointer.de/blog/projects/socket-activation.html";];
>> example = Some "examples/open-qcow2.c";
>> };
>>
>> + "set_socket_activation_name", {
>> + default_call with
>> + args = [ String "socket_name" ]; ret = RErr;
>> + shortdesc = "set the socket activation name";
>
> I recommend adding permitted_states = [ Created ]; on this one - it
> makes no sense to change the socket name after connection.
Will do, thanks!
Laszlo
>
>> + longdesc = "\
>> +When running an NBD server using
>> +L<nbd_connect_systemd_socket_activation(3)> you can optionally
>> +name the socket. Call this function before connecting to the
>> +server.
>> +
>> +Some servers such as L<qemu-storage-daemon(1)>
>> +can use this information to associate the socket with a name
>> +used on the command line, but most servers will ignore it.
>> +The name is passed through the C<LISTEN_FDNAMES> environment
>> +variable.
>
> qemu-storage-daemon doesn't do it yet, but there's a strong likelihood
> of it moving that direction, so I don't mind leaving this statement
> as-is describing what we hope is the future state of things.
>
>> +
>> +The parameter C<socket_name> can be a short alphanumeric string.
>> +If it is set to the empty string (also the default when the handle
>> +is created) then no name is passed to the server.";
>> + see_also = [Link "connect_systemd_socket_activation";
>> + Link "get_socket_activation_name"];
>> + };
>> +
>> + "get_socket_activation_name", {
>> + default_call with
>> + args = []; ret = RString;
>> + shortdesc = "get the socket activation name";
>
> Unlike set_ which only makes sense in Created, get_ makes sense over
> the entire life of the handle, so no permitted_state entry needed
> here.
>
> My suggested one-line addition is easy enough to add that I'm fine if
> you do that without needing a v5.
>
> Reviewed-by: Eric Blake <ebl...@redhat.com>
>
_______________________________________________
Libguestfs mailing list
Libguestfs@redhat.com
https://listman.redhat.com/mailman/listinfo/libguestfs
