vga_init(3)							Svgalib User Manual						       vga_init(3)

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 con-
       sole. 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_getde-
       faultmode(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.

Svgalib (>;= 1.2.11)						   27 July 1997 						       vga_init(3)