[libvirt] [PATCH 2/3] Docs for usage of new command APIs

[Daniel P. Berrange]

On Tue, May 25, 2010 at 03:14:18PM -0600, Eric Blake wrote:
> On 05/25/2010 07:24 AM, Daniel P. Berrange wrote:
> > ---
> >  docs/Makefile.am       |   12 ++++++++++--
> >  docs/internals.html.in |    9 +++++++++
> >  docs/sitemap.html.in   |    4 ++++
> >  3 files changed, 23 insertions(+), 2 deletions(-)
> > 
> > +++ b/docs/Makefile.am
> > @@ -53,7 +53,7 @@ gif = \
> >    architecture.gif \
> >    node.gif
> >  
> > -dot_html_in = $(wildcard *.html.in)
> > +dot_html_in = $(wildcard *.html.in) $(wildcard internals/*.html.in)
> >  dot_html = $(dot_html_in:%.html.in=%.html)
> 
> Note to myself: If I ever get time to revisit my VPATH patches, I've got
> a merge conflict in this area.
> 
> Jim already pointed out the new file omission, but given your first
> message had the text-ified version, here's some spelling fixes:
> 
> >                Spawning processes / commands from libvirt drivers
> > 
> >    This page describes the usage of libvirt APIs for spawning processes /
> >    commands from libvirt drivers. All code is required to use these APIs
> > 
> > Problems with standard POSIX APIs
> > 
> >    The POSIX specification includes a number of APIs for spawning processes /
> >    commands, but they suffer from a number of flaws
> > 
> >      * fork+exec: The lowest & most flexible level, but very hard to use
> >        correctly / safely. It is easy to leak file descriptors, have
> >        unexpected signal handler behaviour and not handle edge cases
> 
> Also, not portable to mingw.
> 
> >      * system: Convenient if you don't care about capturing command output,
> >        but has the serious downside that the command string is interpreted by
> >        the shell. This makes it very dangerous to use, because improperly
> >        validated user input can lead to exploits via shell meta characters.
> 
> * popen: Similar problems to system; also has issues affecting signal
> handling related to other child processes.
> 
> >      * posix_spawn: A half-way house between simplicity of system() and the
> >        flexibility of fork+exec. It does not allow for a couple of important
> >        features though, such as running a hook between the fork+exec stage,
> >        or closing all open file descriptors.
> > 
> >    Due to the problems mentioned with each of these, libvirt driver code must
> >    not use any of the above APIs. Historically libvirt provided a higher
> >    level API known as virExec. This was wrapper around fork+exec, in a
> >    similar style to posix_spawn, but with a few more features.
> 
> I didn't see anything in patch 1/3 that deprecated virExec in the public
> headers.  Is it worth adding conditional deprecation (guarded by a macro
> defined only in command.c), to make sure it is not called anywhere
> except in the command.c implementation?

The full series will eventually make virExec static, so nothing can
call it.


Daniel
-- 
|: Red Hat, Engineering, London    -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :|
|: http://autobuild.org        -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|