.\" Copyright (c) 1986, 1987, University of Utah
.TH RLE_GET_SETUP 3 2/2/87 3
.UC 4 
.SH NAME
rle_get_setup \- Read the header from an RLE file.
.PD 0
.HP
rle_get_setup_ok \- Print error message and exit if rle_get_setup fails.
.HP
rle_get_error \- Print error message for rle_get_setup failure.
.LP
rle_debug \- Turn on or off debugging messages.
.PD
.SH SYNOPSIS
.B
#include <rle.h>
.sp
.B
rle_get_setup( the_hdr );
.br
.B
rle_hdr * the_hdr;
.sp
.B
rle_get_setup_ok( the_hdr, prog_name, file_name );
.br
.B
rle_hdr * the_hdr;
.br
.B
char * prog_name, * file_name;
.sp
.B
rle_get_error( code, prog_name, file_name )
.br
.B
int code;
.br
.B
char *prog_name, *file_name;
.sp
.B
rle_debug( on_off )
.br
.B int on_off;
.SH DESCRIPTION
.PP
.I Rle_get_setup
is called to initialize the process of reading an 
.IR RLE (5)
file.
It will fill in
.I the_hdr
with the header information from the \fIRLE\fP file, and will initialize
state for
.IR rle_getrow (3)
and
.IR rle_getraw (3).
The
.I rle_file
field of
.I the_hdr
should be initialized to the input stream before calling
.IR rle_get_setup .
The
.I bits
field is initialized by
.I rle_get_setup
to enable reading of all the channels present in the input file.  To
prevent \fIrle_getrow\fP or \fIrle_getraw\fP from reading certain
channels (e.g., the alpha channel), the appropriate bits should be
cleared before calling them.  The error codes returned by
\fIrle_get_setup\fP are defined in \fIrle.h\fP.

.I Rle_get_setup_ok
invokes
.IR rle_get_setup
and checks the return code.  If an error occurred, it calls
.I
rle_get_error( err_code, prog_name, file_name )
to print the appropriate error message
on
.IR stderr ,
and the program exits with the status code set.

.I Rle_get_error
can be called to print an appropriate error message on the standard
error output for the failure code returned by
.IR rle_get_setup .
The 
.IR prog_name 
and
.IR file_name 
parameters are used for the error message.  If
.IR file_name 
is NULL or "\-", the string "Standard input" is substituted.

The function
.I rle_debug
is used to enable or disable debug printing for the 
.I rle_get
functions.  If 
.I on_off
is non-zero, all input read from any
.I RLE
file will be printed in a readable form on the standard error output.
Calling
.I rle_debug(0)
will turn off this activity.
.SH SEE ALSO
.IR rle_hdr (3),
.IR rle_getrow (3),
.IR rle_getraw (3),
.IR librle (3),
.IR RLE (5).
.SH AUTHOR
Spencer W. Thomas, Todd Fuqua
.br
University of Utah