.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "funenv 7"
.TH funenv 7 "April 14, 2011" "version 1.4.5" "SAORD Documentation"
.SH "NAME"
FunEnv \- Funtools Environment Variables
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Describes the environment variables which can be used to tailor the overall
Funtools environment.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The following environment variables are supported by Funtools:
.IP "\(bu" 4
\&\fB\s-1FITS_EXTNAME\s0\fR
.Sp
The \fB\s-1FITS_EXTNAME\s0\fR environment variable specifies the
default \s-1FITS\s0 extension name when \fIFunOpen()\fR is called on a file lacking
a primary image. Thus,
.Sp
.Vb 1
\&  setenv FITS_EXTNAME "NEWEV"
.Ve
.Sp
will allow you to call \fIFunOpen()\fR on files without specifying \s-1NEWEV\s0 in
the
Funtools bracket specification.
If no \s-1FITS_EXTNAME\s0 variable is defined and the extension name also is
not passed in the bracket specification, then the default will be to
look for standard X\-ray event table extension names \*(L"\s-1EVENTS\s0\*(R" or
\&\*(L"\s-1STDEVT\s0\*(R" (we are, after all, and X\-ray astronomy group at heart!).
.IP "\(bu" 4
\&\fB\s-1FITS_EXTNUM\s0\fR
.Sp
The \fB\s-1FITS_EXTNUM\s0\fR environment variable specifies the
default \s-1FITS\s0 extension number when \fIFunOpen()\fR is called on a file lacking
a primary image. Thus,
.Sp
.Vb 1
\&  setenv FITS_EXTNUM 7
.Ve
.Sp
will allow you to call \fIFunOpen()\fR on files to open the seventh 
extension without specifying the number in the
Funtools bracket specification.
.IP "\(bu" 4
\&\fB\s-1FITS_BINCOLS\s0\fR and \fB\s-1EVENTS_BINCOLS\s0\fR
.Sp
These environment variable specifies the default binning key for 
\&\s-1FITS\s0 binary tables and raw event files, respectively. They can be
over-ridden using the \fBbincols=[naxis1,naxis2]\fR keyword in a
Funtools bracket specification.
The value of each environment variable
is a pair of comma-delimited columns, enclosed in parentheses, to use
for binning.  For example, if you want to bin on detx and dety by
default, then use:
.Sp
.Vb 1
\&  setenv FITS_BINCOLS "(detx,dety)"
.Ve
.Sp
in preference to adding a bincols specification to each filename:
.Sp
.Vb 1
\&  foo.fits[bincols=(detx,dety)]
.Ve
.IP "\(bu" 4
\&\fB\s-1FITS_BITPIX\s0\fR and \fB\s-1EVENTS_BITPIX\s0\fR
.Sp
These environment variable specifies the default bitpix value for
binning \s-1FITS\s0 binary tables and raw event files, respectively. They can
be over-ridden using the \fBbitpix=[value]\fR keyword in a 
Funtools bracket specification.  The value
of each environment variable is one of the standard \s-1FITS\s0 bitpix values
(8,16,32,\-32,\-64).  For example, if you want binning routines to
create a floating array, then use:
.Sp
.Vb 1
\&  setenv FITS_BITPIX \-32
.Ve
.Sp
in preference to adding a bitpix specification to each filename:
.Sp
.Vb 1
\&  foo.fits[bitpix=-32]
.Ve
.IP "\(bu" 4
\&\fB\s-1ARRAY\s0\fR
.Sp
The \fB\s-1ARRAY\s0\fR environment variable specifies the default
definition of an array file for Funtools.
It is used if there is no array specification passed in the
\&\fB\s-1\f(BIARRAY\s0()\fB\fR directive in a
Non-FITS Array specification.
The value of the environment variable is a valid array specification such as:
.Sp
.Vb 2
\&  setenv ARRAY "s100.150"
\&  foo.arr[ARRAY()]
.Ve
.Sp
This can be defined in preference to adding the specification to each filename:
.Sp
.Vb 1
\&  foo.arr[ARRAY(s100.150)]
.Ve
.IP "\(bu" 4
\&\fB\s-1EVENTS\s0\fR
.Sp
The \fB\s-1EVENTS\s0\fR environment variable specifies the default
definition of an raw event file for Funtools.
It is used if there is no \s-1EVENTS\s0 specification passed in the
\&\fB\s-1\f(BIEVENTS\s0()\fB\fR directive in a
Non-FITS \s-1EVENTS\s0 specification.
The value of the environment variable is a valid \s-1EVENTS\s0 specification such as:
.Sp
.Vb 2
\&  setenv EVENTS "x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024"
\&  foo.ev[EVENTS()]
.Ve
.Sp
This can be defined in preference to adding the specification to each filename:
.Sp
.Vb 1
\&  foo.ev[EVENTS(x:J:1024,y:J:1024,pi:I,pha:I,time:D,dx:E:1024,dx:E:1024)]
.Ve
.PP
The following filter-related environment variables are supported by Funtools:
.IP "\(bu" 4
\&\fB\s-1FILTER_PTYPE\s0\fR
.Sp
The \fB\s-1FILTER_PTYPE\s0\fR environment variable specifies how to
build a filter.  There are three possible methods:
.RS 4
.IP "\(bu" 4
process or p
.Sp
The filter is compiled and linked against the funtools library (which
must therefore be accessible in the original install directory) to produce
a slave program. This program is fed events or image data and returns
filter results.
.IP "\(bu" 4
dynamic or d (gcc only)
.Sp
The filter is compiled and linked against the funtools library (which
must therefore be accessible in the original install directory) to produce
a dynamic shared object, which is loaded into the funtools program and
executed as a subroutine. (Extensive testing has shown that, contrary to
expectations, this method is no faster than using a slave process.)
.IP "\(bu" 4
contained or c
.Sp
The filter and all supporting region code is compiled and linked
without reference to the funtools library to produce a slave program
(which is fed events or image data and returns filter results). This method
is slower than the other two, because of the time it takes to compile the
region filtering code. It is used by stand-alone programs such as ds9,
which do not have access to the funtools library.
.RE
.RS 4
.Sp
By default, \fBdynamic\fR is generally used for gcc compilers and
\&\fBprocess\fR for other compilers. However the filter building algorithm
will check for required external files and will use \fBcontained\fR is
these are missing.
.RE
.IP "\(bu" 4
\&\fB\s-1FUN_MAXROW\s0\fR
.Sp
The \fB\s-1FUN_MAXROW\s0\fR environment variable is used by core
row-processing Funtools programs (funtable, fundisp, funcnts, funhist,
funmerge, and funcalc) to set the maximum number of rows read at once
(i.e. it sets the third argument to the \fIFunTableRowGet()\fR call).  The
default is 8192. Note that this variable is a convention only: it will
not be a part of a non-core Funtools program unless code is explicitly
added, since each call to \fIFunTableRowGet()\fR specifies its own maximum
number of rows to read. \s-1NB:\s0 if you make this value very large, you
probably will need to increase \fB\s-1FUN_MAXBUFSIZE\s0\fR (see below) as well.
.IP "\(bu" 4
\&\fB\s-1FUN_MAXBUFSIZE\s0\fR
.Sp
The \fB\s-1FUN_MAXBUFSIZE\s0\fR environment variable is used to limit the
max buffer size that will be allocated to hold table row data.  This
buffer size is calculated to be the row size of the table multiplied
by the maximum number of rows read at once (see above). Since the
row size is unlimited (and we have examples of it being larger than 5
Mb), it is possible that the total buffer size will exceed the machine
capabilities. We therefore set a default value of 5Mb for the max buffer
size, and adjust maxrow so that the total size calculated is less than
this max buffer size. (If the row size is greater than this max buffer
size, then maxrow is set to 1.) This environment variable will change
the max buffer size allowed.
.IP "\(bu" 4
\&\fB\s-1FILTER_CC\s0\fR
.Sp
The \fB\s-1FILTER_CC\s0\fR environment variable specifies the compiler to
use for compiling a filter specification. You also can use the \fB\s-1CC\s0\fR
environment variable. If neither has been set, then gcc will be used
if available. Otherwise cc is used if available.
.IP "\(bu" 4
\&\fB\s-1FILTER_EXTRA\s0\fR
.Sp
The \fB\s-1FILTER_EXTRA\s0\fR environment variable specifies extra options
to add to a filter compile command line. In principle, you can add libraries,
include files, and compiler switches. This variable should be used with care.
.IP "\(bu" 4
\&\fB\s-1FILTER_TMPDIR\s0\fR
.Sp
The \fB\s-1FILTER_TMPDIR\s0\fR environment variable specifies the temporary
directory for filter compilation intermediate files. You also can use
the \fB\s-1TMPDIR\s0\fR and \fB\s-1TMP\s0\fR variables. By default, /tmp is used
as the temporary directory.
.IP "\(bu" 4
\&\fB\s-1FILTER_KEEP\s0\fR
.Sp
The \fB\s-1FILTER_KEEP\s0\fR environment variable specifies whether the
intermediate filter files (i.e. C source file and compile log file)
should be saved after a filter is built. The default is \*(L"false\*(R", so that
these intermediate files are deleted. This variable is useful for debugging,
but care should be taken to reset its value to false when debugging is
complete.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See funtools(7) for a list of Funtools help pages