= Configuration Options =

This page discussed runtime configuration options for GDAL, and is distinct from options to the build-time configure script.  Runtime configuration options apply on all platforms, and are evaluated at runtime.  They can be set programmatically, by commandline switches or in the environment by the user. 

!ConfigOptions are normally used to alter the default behavior of GDAL and OGR drivers and in some cases the GDAL and OGR core.  They are essentially global variables the user can set.  

== Setting !ConfigOptions ==

One example of a config option is the GDAL_CACHEMAX option.  It controls the size of the GDAL block cache, in megabytes.  It can be set in the environment on unix (bash/bourne) shell like this:
{{{
export GDAL_CACHEMAX=64
}}}

In a DOS/Windows command shell it is done like this:

{{{
set GDAL_CACHEMAX=64
}}}

It can also be set on the commandline for most GDAL and OGR utilities with the --config switch, though in a few cases these switches are not evaluated in time to affect behavior. 

{{{
gdal_translate --config GDAL_CACHEMAX 64 in.tif out.tif
}}}

In C/C++ configuration switches can be set programmatically like this:

{{{
#include "cpl_conv.h"
...
    GDALSetConfigOption( "GDAL_CACHEMAX", "64" );
}}}

Normally a configuration option applies to all threads active in a program, but they can be limited to only the current thread this way:

{{{
    GDALSetThreadLocalConfigOption( "GDAL_CACHEMAX", "64" );
}}}

== What Configuration Options Exist? ==

Traditionally there hasn't been a good registry of configuration options, and they are often added adhoc to drivers to provide particular workarounds.  Below are some of the software wide configuration options. In some cases particular format drivers will document their configuration options, if any, in the user documentation - as is done for the [http://www.gdal.org/frmt_jp2kak.html JP2KAK] driver.

== Generic Options ==

=== CPL_DEBUG ===

This may be set to ON, OFF or specific prefixes.  If it is ON, all debug messages are reported to stdout.  If it is OFF or unset no debug messages are reported.  If it is set to a particular value, then only debug messages with that "type" value will be reported.  For instance debug messages from the HFA driver are normally reported with type "HFA" (seen in the message).

At the commandline this can also be set with --debug <value> as well as with --config CPL_DEBUG <value>. 

=== CPL_LOG ===

=== CPL_LOG_ERRORS ===

=== CPL_TIMESTAMP ===

=== CPL_MAX_ERROR_REPORTS ===

=== CPL_ACCUM_ERROR_MSG ===

=== CPL_TMPDIR ===

=== GDAL_DATA ===

=== GEOTIFF_CSV ===


== GDAL Options ==

=== GDAL_DISABLE_READDIR_ON_OPEN ===

=== GDAL_CACHEMAX ===

This option controls the default GDAL raster block cache size.  If it's value is small (less than 10000 in 1.7 and earlier, 100000 in 1.8 and later) it is assumed to be measured in megabytes, otherwise in bytes.   Note that this value is only consulted the first time the cache size is requested overriding the initial default (40MB in GDAL 1.7, but often changing for each release).  To change this value programmatically during operation of the pgoram it is better to use GDALSetCacheMax(int nNewSize) (always in bytes). 

=== GDAL_SKIP ===

=== GDAL_DRIVER_PATH ===

=== GDAL_FORCE_CACHING ===

=== GDAL_VALIDATE_CREATION_OPTIONS ===

=== GDAL_IGNORE_AXIS_ORIENTATION ===

=== GMLJP2OVERRIDE ===

=== GDAL_PAM_MODE ===

=== GDAL_PAM_PROXY_DIR ===

=== GDAL_MAX_DATASET_POOL_SIZE ===

=== GDAL_SWATH_SIZE ===

== OGR Options ==

=== PROJSO ===

The name of the PROJ.4 DLL or shared library to try and load at runtime. 

=== CENTER_LONG ===

=== CHECK_WITH_INVERT_PROJ ===

=== THRESHOLD ===

=== OGR_DEBUG_ORGANIZE_POLYGONS ===

=== OGR_ARC_STEPSIZE ===

=== OGR_FORCE_ASCII ===