mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-23 10:13:34 +08:00
Code Issues Packages Projects Releases Wiki Activity
d209e197f8
systemd/man/sd_machine_get_class.xml

123 lines
4.7 KiB
XML
Raw Normal View History

man: document sd_machine_get_class() and sd_machine_get_ifindices()
2014-10-18 22:06:21 +08:00
<?xml version='1.0'?> <!--*-nxml-*-->
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 21:40:58 +08:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 22:48:33 +08:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 12:23:58 +08:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: document sd_machine_get_class() and sd_machine_get_ifindices()
2014-10-18 22:06:21 +08:00
man: xinclude the generic text to talk about libsystemd pkgconfig The only difference is that functions are not individually listed by name, but that seems completely pointless, since all functions that are documented are always exported, so the generic text tells the user all she or he needs to know.
2018-06-06 17:59:04 +08:00
<refentry id="sd_machine_get_class" xmlns:xi="http://www.w3.org/2001/XInclude">
man: document sd_machine_get_class() and sd_machine_get_ifindices()
2014-10-18 22:06:21 +08:00
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<refentryinfo>
<title>sd_machine_get_class</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_machine_get_class</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_machine_get_class</refname>
<refname>sd_machine_get_ifindices</refname>
<refpurpose>Determine the class and network interface indices of a
tree-wide: fixes for assorted grammar and spelling issues Fixes #16363. Also includes some changes where I generalized the pattern.
2020-07-06 16:49:59 +08:00
locally running virtual machine or container</refpurpose>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_machine_get_class</function></funcdef>
<paramdef>const char* <parameter>machine</parameter></paramdef>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
<paramdef>char **<parameter>class</parameter></paramdef>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_machine_get_ifindices</function></funcdef>
<paramdef>const char* <parameter>machine</parameter></paramdef>
Rewrite sd_machine_get_ifindices() to avoid FOREACH_WORD() If we fail to parse the index, the failure is propogated as -EUNCLEAN. (-EINVAL would be confused with invalid args to the function itself.)
2020-07-30 18:56:51 +08:00
<paramdef>int **<parameter>ret_ifindices</parameter></paramdef>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_machine_get_class()</function> may be used to
determine the class of a locally running virtual machine or
container that is registered with
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
The string returned is either <literal>vm</literal> or
<literal>container</literal>. 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>
Let sd_machine_get_ifindices() omit the output param too Nowadays we do that almost everywhere, let's also do it here.
2020-07-30 19:08:52 +08:00
<para><function>sd_machine_get_ifindices()</function> may be used to determine the numeric indices of the
network interfaces on the host that are pointing towards the specified locally running virtual machine or
container. The vm or container must be registered with
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
Let sd_machine_get_ifindices() omit the output param too Nowadays we do that almost everywhere, let's also do it here.
2020-07-30 19:08:52 +08:00
The output parameter <parameter>ret_ifindices</parameter> may be passed as <constant>NULL</constant> when
the output value is not needed. The returned array needs to be freed with the libc <citerefentry
project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after
use.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsect1>
<refsect1>
<title>Return Value</title>
Let sd_machine_get_ifindices() omit the output param too Nowadays we do that almost everywhere, let's also do it here.
2020-07-30 19:08:52 +08:00
<para>On success, these functions return a non-negative integer.
<function>sd_machine_get_ifindices()</function> returns the number of the relevant network interfaces.
On failure, these calls return a negative errno-style error code.</para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<refsect2>
<title>Errors</title>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<para>Returned errors may indicate the following problems:</para>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<variablelist>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-ENXIO</constant></term>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>The specified machine does not exist or is currently not running.</para>
</listitem>
</varlistentry>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-EINVAL</constant></term>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>An input parameter was invalid (out of range, or <constant>NULL</constant>, where
that is not accepted).</para></listitem>
</varlistentry>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-ENOMEM</constant></term>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
sd-login: rework error handling Makre sure we always return sensible errors for the various, following the same rules, and document them in a comment in sd-login.c. Also, update all relevant man pages accordingly.
2015-09-04 15:05:52 +08:00
</refsect1>
man: xinclude the generic text to talk about libsystemd pkgconfig The only difference is that functions are not individually listed by name, but that seems completely pointless, since all functions that are documented are always exported, so the generic text tells the user all she or he needs to know.
2018-06-06 17:59:04 +08:00
<xi:include href="libsystemd-pkgconfig.xml" />
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
man: add version information for functions
2023-09-04 20:46:35 +08:00
<refsect1>
<title>History</title>
man: condense version information for functions Use a more compact form like 'a, b, and c were added in version x'
2023-09-19 00:44:26 +08:00
<para><function>sd_machine_get_class()</function> and
<function>sd_machine_get_ifindices()</function> were added in version 217.</para>
man: add version information for functions
2023-09-04 20:46:35 +08:00
</refsect1>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-23 02:09:32 +08:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_pid_get_machine_name</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
</simplelist></para>
Reindent man pages to 2ch
2015-02-04 10:14:13 +08:00
</refsect1>
man: document sd_machine_get_class() and sd_machine_get_ifindices()
2014-10-18 22:06:21 +08:00
</refentry>
Reference in New Issue Copy Permalink