NAME

       vga_init - initialize svgalib library

SYNOPSIS

       #include <vga.h>

       int vga_init(void);

DESCRIPTION

       It  detects the chipset and gives up supervisor rights. This is the recommended first line
       of any program that uses svgalib.  vga_setchipset(3) can be  called  before  it  to  avoid
       detection.

       Svgalib  catches a bunch of signals that usually kill your program to restore textmode. If
       you catch signal's before calling vga_init() svgalib will restore textmode and prepare for
       shutdown  and  then  call  your  handler routine. If you don't want this, catch the signal
       after calling vga_init and do not daisychain to svgalib's original handler.

       WARNING!  svgalib needs two signals for  it's  own  purposes  (that  is  managing  console
       switches).  To  avoid  problems  it uses the otherwise unused signals SIGUSR1 and SIGUSR2.
       However, this means that you cannot use them in your program by any means. They are  setup
       by vga_init() as everything else is.

       Since  version  1.2.11  vga_init() includes code to hunt for a free virtual console on its
       own in case you are not starting the program from one (but instead over a network or modem
       login,  from  within  'screen'  or  an  'xterm').  Provided  there is a free console, this
       succeeds if you are root or if the svgalib calling user own the current console.  This  is
       to  avoid people not using the console being able to fiddle with it.  On graceful exit the
       program returns to the console from which it was started.  Otherwise it  remains  in  text
       mode  at  the  VC  which  svgalib allocated to allow you to see any error messages. In any
       case, any I/O the svgalib makes in text mode (after calling vga_init) will also take place
       at this new console.

       Alas,  some  games misuse their suid root priviledge and run as full root process. svgalib
       cannot detect this and allows Joe Blow User to open a new  VC  on  the  console.  If  this
       annoys  you ROOT_VC_SHORTCUT in Makefile.cfg allows you to disable allocating a new VC for
       root (except when he owns the current console) when compiling svgalib. This is the default
       (disabling the allocation for root).

       vga_init()  returns  a non-zero value in case of errors. As of this writing it will return
       -1 if it is unable to allocate a graphical console. Otherwise, 0 is returned.

BUGS

       Svgalib versions prior to 1.2.11 had a security hole where it would be possible to  regain
       root  priviledges  even after a vga_init() call. This is not necessarily a problem, but if
       your program is vulnerable to buffer overflows and other attacks, an attacker may  exploit
       this.

       However,  prior  to your call, your program will need to run setuid root, so you should be
       very careful. The ioperm library by Olaf Titz will  allow  svgalib  programs  to  run  not
       setuid  root.  However,  it  gives all programs unlimited access to the hardware. Again, a
       malicious person can exploit this (albeit a bit more difficult) too.   Thus,  in  general,
       make your svgalib programs as secure as any setuid root program.

       Some  programs  may  (accidently) rely on the old behaviour (which was probably due to the
       author not knowing about saved uids (which might actually even not have existed  in  Linux
       at that time)). A line:

       security compat

       in the configuration file /etc/vga/libvga.conf will reinstate the old behaviour whereas

       security revoke-all-privs

       enables the (currently default) action.

SEE ALSO

       svgalib(7),   vga_setmode(3),   mouse_init(3),   vga_claimvideomemory(3),  vga_ext_set(3),
       vga_fillblt(3),   vga_getcurrentchipset(3),   vga_getdefaultmode(3),   vga_getgraphmem(3),
       vga_runinbackground(3),         vga_runinbackground_version(3),        vga_safety_fork(3),
       vga_setchipset(3), vga_setchipsetandfeatures(3), vgagl(7), libvga.config(5),

AUTHOR

       This manual page was edited by Michael Weller  <eowmob@exp-math.uni-essen.de>.  The  exact
       source of the referenced function as well as of the original documentation is unknown.

       It  is  very  likely  that  both  are  at  least to some extent are due to Harm Hanemaayer
       <H.Hanemaayer@inter.nl.net>.

       Occasionally this might be wrong. I hereby asked to be excused by the original author  and
       will  happily  accept  any  additions  or corrections to this first version of the svgalib
       manual.