# Common Portability Library

## cpl_conv.h

Various convenience functions for CPL.

Defines

`CPLFree`

  Alias of VSIFree()

Typedefs

typedef const char *(*`CPLFileFinder`)(const char *, const char *)

  Callback for CPLPushFileFinder.

Functions

const char *`CPLGetConfigOption`(const char *pszKey, const char *pszDefault)

  Get the value of a configuration option.

  The value is the value of a (key, value) option set with CPLSetConfigOption(), or CPLSetThreadLocalConfigOption() of the same thread. If the given option was no defined with CPLSetConfigOption(), it tries to find it in environment variables.

  Note: the string returned by CPLGetConfigOption() might be short-lived, and in particular it will become invalid after a call to CPLSetConfigOption() with the same key.

  To override temporary a potentially existing option with a new value, you can use the following snippet :

  Return

    the value associated to the key, or the default value if not found

  See

    CPLSetConfigOption(), http://trac.osgeo.org/gdal/wiki/ConfigOptions

  Parameters

    - `pszKey`: the key of the option to retrieve

    - `pszDefault`: a default value if the key does not match existing defined options (may be NULL)

const char *`CPLGetThreadLocalConfigOption`(const char *, const char *)

  Same as CPLGetConfigOption() but only with options set with CPLSetThreadLocalConfigOption()

void `CPLSetConfigOption`(const char *pszKey, const char *pszValue)

  Set a configuration option for GDAL/OGR use.

  Those options are defined as a (key, value) couple. The value corresponding to a key can be got later with the CPLGetConfigOption() method.

  This mechanism is similar to environment variables, but options set with CPLSetConfigOption() overrides, for CPLGetConfigOption() point of view, values defined in the environment.

  If CPLSetConfigOption() is called several times with the same key, the value provided during the last call will be used.

  Options can also be passed on the command line of most GDAL utilities with the with ‘config KEY VALUE’. For example, ogrinfo config CPL_DEBUG ON ~/data/test/point.shp

  This function can also be used to clear a setting by passing NULL as the value (note: passing NULL will not unset an existing environment variable; it will just unset a value previously set by CPLSetConfigOption()).

  See

    http://trac.osgeo.org/gdal/wiki/ConfigOptions

  Parameters

    - `pszKey`: the key of the option

    - `pszValue`: the value of the option, or NULL to clear a setting.

void `CPLSetThreadLocalConfigOption`(const char *pszKey, const char *pszValue)

  Set a configuration option for GDAL/OGR use.

  Those options are defined as a (key, value) couple. The value corresponding to a key can be got later with the CPLGetConfigOption() method.

  This function sets the configuration option that only applies in the current thread, as opposed to CPLSetConfigOption() which sets an option that applies on all threads. CPLSetThreadLocalConfigOption() will override the effect of CPLSetConfigOption) for the current thread.

  This function can also be used to clear a setting by passing NULL as the value (note: passing NULL will not unset an existing environment variable or a value set through CPLSetConfigOption(); it will just unset a value previously set by CPLSetThreadLocalConfigOption()).

  Parameters

    - `pszKey`: the key of the option

    - `pszValue`: the value of the option, or NULL to clear a setting.

char **`CPLGetConfigOptions`(void)

  Return the list of configuration options as KEY=VALUE pairs.

  The list is the one set through the CPLSetConfigOption() API.

  Options that through environment variables or with CPLSetThreadLocalConfigOption() will not be listed.

  Return

    a copy of the list, to be freed with CSLDestroy().

  Since

    GDAL 2.2

void `CPLSetConfigOptions`(const char *const *papszConfigOptions)

  Replace the full list of configuration options with the passed list of KEY=VALUE pairs.

  This has the same effect of clearing the existing list, and setting individually each pair with the CPLSetConfigOption() API.

  This does not affect options set through environment variables or with CPLSetThreadLocalConfigOption().

  The passed list is copied by the function.

  Since

    GDAL 2.2

  Parameters

    - `papszConfigOptions`: the new list (or NULL).

char **`CPLGetThreadLocalConfigOptions`(void)

  Return the list of thread local configuration options as KEY=VALUE pairs.

  Options that through environment variables or with CPLSetConfigOption() will not be listed.

  Return

    a copy of the list, to be freed with CSLDestroy().

  Since

    GDAL 2.2

void `CPLSetThreadLocalConfigOptions`(const char *const *papszConfigOptions)

  Replace the full list of thread local configuration options with the passed list of KEY=VALUE pairs.

  This has the same effect of clearing the existing list, and setting individually each pair with the CPLSetThreadLocalConfigOption() API.

  This does not affect options set through environment variables or with CPLSetConfigOption().

  The passed list is copied by the function.

  Since

    GDAL 2.2

  Parameters

    - `papszConfigOptions`: the new list (or NULL).

void *`CPLMalloc`(size_t nSize)

  Safe version of malloc().

  This function is like the C library malloc(), but raises a CE_Fatal error with CPLError() if it fails to allocate the desired memory. It should be used for small memory allocations that are unlikely to fail and for which the application is unwilling to test for out of memory conditions. It uses VSIMalloc() to get the memory, so any hooking of VSIMalloc() will apply to CPLMalloc() as well. CPLFree() or VSIFree() can be used free memory allocated by CPLMalloc().

  Return

    pointer to newly allocated memory, only NULL if nSize is zero.

  Parameters

    - `nSize`: size (in bytes) of memory block to allocate.

void *`CPLCalloc`(size_t nCount, size_t nSize)

  Safe version of calloc().

  This function is like the C library calloc(), but raises a CE_Fatal error with CPLError() if it fails to allocate the desired memory. It should be used for small memory allocations that are unlikely to fail and for which the application is unwilling to test for out of memory conditions. It uses VSICalloc() to get the memory, so any hooking of VSICalloc() will apply to CPLCalloc() as well. CPLFree() or VSIFree() can be used free memory allocated by CPLCalloc().

  Return

    pointer to newly allocated memory, only NULL if nSize * nCount is NULL.

  Parameters

    - `nCount`: number of objects to allocate.

    - `nSize`: size (in bytes) of object to allocate.

void *`CPLRealloc`(void *pData, size_t nNewSize)

  Safe version of realloc().

  This function is like the C library realloc(), but raises a CE_Fatal error with CPLError() if it fails to allocate the desired memory. It should be used for small memory allocations that are unlikely to fail and for which the application is unwilling to test for out of memory conditions. It uses VSIRealloc() to get the memory, so any hooking of VSIRealloc() will apply to CPLRealloc() as well. CPLFree() or VSIFree() can be used free memory allocated by CPLRealloc().

  It is also safe to pass NULL in as the existing memory block for CPLRealloc(), in which case it uses VSIMalloc() to allocate a new block.

  Return

    pointer to allocated memory, only NULL if nNewSize is zero.

  Parameters

    - `pData`: existing memory block which should be copied to the new block.

    - `nNewSize`: new size (in bytes) of memory block to allocate.

char *`CPLStrdup`(const char *pszString)

  Safe version of strdup() function.

  This function is similar to the C library strdup() function, but if the memory allocation fails it will issue a CE_Fatal error with CPLError() instead of returning NULL. Memory allocated with CPLStrdup() can be freed with CPLFree() or VSIFree().

  It is also safe to pass a NULL string into CPLStrdup(). CPLStrdup() will allocate and return a zero length string (as opposed to a NULL string).

  Return

    pointer to a newly allocated copy of the string. Free with CPLFree() or VSIFree().

  Parameters

    - `pszString`: input string to be duplicated. May be NULL.

char *`CPLStrlwr`(char *pszString)

  Convert each characters of the string to lower case.

  For example, “ABcdE” will be converted to “abcde”. This function is locale dependent.

  Return

    pointer to the same string, pszString.

  Parameters

    - `pszString`: input string to be converted.

char *`CPLFGets`(char *pszBuffer, int nBufferSize, FILE *fp)

  Reads in at most one less than nBufferSize characters from the fp stream and stores them into the buffer pointed to by pszBuffer.

  Reading stops after an EOF or a newline. If a newline is read, it is not stored into the buffer. A ‘\0’ is stored after the last character in the buffer. All three types of newline terminators recognized by the CPLFGets(): single ‘\r’ and ‘\n’ and ‘\r\n’ combination.

  Return

    pointer to the pszBuffer containing a string read from the file or NULL if the error or end of file was encountered.

  Parameters

    - `pszBuffer`: pointer to the targeting character buffer.

    - `nBufferSize`: maximum size of the string to read (not including terminating ‘\0’).

    - `fp`: file pointer to read from.

const char *`CPLReadLine`(FILE *fp)

  Simplified line reading from text file.

  Read a line of text from the given file handle, taking care to capture CR and/or LF and strip off … equivalent of DKReadLine(). Pointer to an internal buffer is returned. The application shouldn’t free it, or depend on its value past the next call to CPLReadLine().

  Note that CPLReadLine() uses VSIFGets(), so any hooking of VSI file services should apply to CPLReadLine() as well.

  CPLReadLine() maintains an internal buffer, which will appear as a single block memory leak in some circumstances. CPLReadLine() may be called with a NULL FILE * at any time to free this working buffer.

  Return

    pointer to an internal buffer containing a line of text read from the file or NULL if the end of file was encountered.

  Parameters

    - `fp`: file pointer opened with VSIFOpen().

const char *`CPLReadLineL`(VSILFILE *fp)

  Simplified line reading from text file.

  Similar to CPLReadLine(), but reading from a large file API handle.

  Return

    pointer to an internal buffer containing a line of text read from the file or NULL if the end of file was encountered.

  Parameters

    - `fp`: file pointer opened with VSIFOpenL().

const char *`CPLReadLine2L`(VSILFILE *fp, int nMaxCars, CSLConstList papszOptions)

  Simplified line reading from text file.

  Similar to CPLReadLine(), but reading from a large file API handle.

  Return

    pointer to an internal buffer containing a line of text read from the file or NULL if the end of file was encountered or the maximum number of characters allowed reached.

  Since

    GDAL 1.7.0

  Parameters

    - `fp`: file pointer opened with VSIFOpenL().

    - `nMaxCars`: maximum number of characters allowed, or -1 for no limit.

    - `papszOptions`: NULL-terminated array of options. Unused for now.

const char *`CPLReadLine3L`(VSILFILE *fp, int nMaxCars, int *pnBufLength, CSLConstList papszOptions)

  Simplified line reading from text file.

  Similar to CPLReadLine(), but reading from a large file API handle.

  Return

    pointer to an internal buffer containing a line of text read from the file or NULL if the end of file was encountered or the maximum number of characters allowed reached.

  Since

    GDAL 2.3.0

  Parameters

    - `fp`: file pointer opened with VSIFOpenL().

    - `nMaxCars`: maximum number of characters allowed, or -1 for no limit.

    - `papszOptions`: NULL-terminated array of options. Unused for now.

    - `[out] pnBufLength`: size of output string (must be non-NULL)

double `CPLAtof`(const char *nptr)

  Converts ASCII string to floating point number.

  This function converts the initial portion of the string pointed to by nptr to double floating point representation. The behaviour is the same as

  CPLStrtod(nptr, (char **)NULL);

  This function does the same as standard atof(3), but does not take locale in account. That means, the decimal delimiter is always ‘.’ (decimal point). Use CPLAtofDelim() function if you want to specify custom delimiter.

  IMPORTANT NOTE:

  Existence of this function does not mean you should always use it. Sometimes you should use standard locale aware atof(3) and its family. When you need to process the user’s input (for example, command line parameters) use atof(3), because the user works in a localized environment and the user’s input will be done according to the locale set. In particular that means we should not make assumptions about character used as decimal delimiter, it can be either “.” or “,”.

  But when you are parsing some ASCII file in predefined format, you most likely need CPLAtof(), because such files distributed across the systems with different locales and floating point representation should be considered as a part of file format. If the format uses “.” as a delimiter the same character must be used when parsing number regardless of actual locale setting.

  Return

    Converted value, if any.

  Parameters

    - `nptr`: Pointer to string to convert.

double `CPLAtofDelim`(const char *nptr, char point)

  Converts ASCII string to floating point number.

  This function converts the initial portion of the string pointed to by nptr to double floating point representation. The behaviour is the same as

  CPLStrtodDelim(nptr, (char **)NULL, point);

  This function does the same as standard atof(3), but does not take locale in account. Instead of locale defined decimal delimiter you can specify your own one. Also see notes for CPLAtof() function.

  Return

    Converted value, if any.

  Parameters

    - `nptr`: Pointer to string to convert.

    - `point`: Decimal delimiter.

double `CPLStrtod`(const char *nptr, char **endptr)

  Converts ASCII string to floating point number.

  This function converts the initial portion of the string pointed to by nptr to double floating point representation. This function does the same as standard strtod(3), but does not take locale in account. That means, the decimal delimiter is always ‘.’ (decimal point). Use CPLStrtodDelim() function if you want to specify custom delimiter. Also see notes for CPLAtof() function.

  Return

    Converted value, if any.

  Parameters

    - `nptr`: Pointer to string to convert.

    - `endptr`: If is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr.

double `CPLStrtodDelim`(const char *nptr, char **endptr, char point)

  Converts ASCII string to floating point number using specified delimiter.

  This function converts the initial portion of the string pointed to by nptr to double floating point representation. This function does the same as standard strtod(3), but does not take locale in account. Instead of locale defined decimal delimiter you can specify your own one. Also see notes for CPLAtof() function.

  Return

    Converted value, if any.

  Parameters

    - `nptr`: Pointer to string to convert.

    - `endptr`: If is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr.

    - `point`: Decimal delimiter.

float `CPLStrtof`(const char *nptr, char **endptr)

  Converts ASCII string to floating point number.

  This function converts the initial portion of the string pointed to by nptr to single floating point representation. This function does the same as standard strtof(3), but does not take locale in account. That means, the decimal delimiter is always ‘.’ (decimal point). Use CPLStrtofDelim() function if you want to specify custom delimiter. Also see notes for CPLAtof() function.

  Return

    Converted value, if any.

  Parameters

    - `nptr`: Pointer to string to convert.

    - `endptr`: If is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr.

float `CPLStrtofDelim`(const char *nptr, char **endptr, char point)

  Converts ASCII string to floating point number using specified delimiter.

  This function converts the initial portion of the string pointed to by nptr to single floating point representation. This function does the same as standard strtof(3), but does not take locale in account. Instead of locale defined decimal delimiter you can specify your own one. Also see notes for CPLAtof() function.

  Return

    Converted value, if any.

  Parameters

    - `nptr`: Pointer to string to convert.

    - `endptr`: If is not NULL, a pointer to the character after the last character used in the conversion is stored in the location referenced by endptr.

    - `point`: Decimal delimiter.

double `CPLAtofM`(const char *nptr)

  Converts ASCII string to floating point number using any numeric locale.

  This function converts the initial portion of the string pointed to by nptr to double floating point representation. This function does the same as standard atof(), but it allows a variety of locale representations. That is it supports numeric values with either a comma or a period for the decimal delimiter.

  PS. The M stands for Multi-lingual.

  Return

    Converted value, if any. Zero on failure.

  Parameters

    - `nptr`: The string to convert.

char *`CPLScanString`(const char *pszString, int nMaxLength, int bTrimSpaces, int bNormalize)

  Scan up to a maximum number of characters from a given string, allocate a buffer for a new string and fill it with scanned characters.

  Return

    Pointer to the resulting string buffer. Caller responsible to free this buffer with CPLFree().

  Parameters

    - `pszString`: String containing characters to be scanned. It may be terminated with a null character.

    - `nMaxLength`: The maximum number of character to read. Less characters will be read if a null character is encountered.

    - `bTrimSpaces`: If TRUE, trim ending spaces from the input string. Character considered as empty using isspace(3) function.

    - `bNormalize`: If TRUE, replace ‘:’ symbol with the ‘_’. It is needed if resulting string will be used in CPL dictionaries.

double `CPLScanDouble`(const char *pszString, int nMaxLength)

  Extract double from string.

  Scan up to a maximum number of characters from a string and convert the result to a double. This function uses CPLAtof() to convert string to double value, so it uses a comma as a decimal delimiter.

  Return

    Double value, converted from its ASCII form.

  Parameters

    - `pszString`: String containing characters to be scanned. It may be terminated with a null character.

    - `nMaxLength`: The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered.

long `CPLScanLong`(const char *pszString, int nMaxLength)

  Scan up to a maximum number of characters from a string and convert the result to a long.

  Return

    Long value, converted from its ASCII form.

  Parameters

    - `pszString`: String containing characters to be scanned. It may be terminated with a null character.

    - `nMaxLength`: The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered.

unsigned long `CPLScanULong`(const char *pszString, int nMaxLength)

  Scan up to a maximum number of characters from a string and convert the result to a unsigned long.

  Return

    Unsigned long value, converted from its ASCII form.

  Parameters

    - `pszString`: String containing characters to be scanned. It may be terminated with a null character.

    - `nMaxLength`: The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered.

GUIntBig `CPLScanUIntBig`(const char *pszString, int nMaxLength)

  Extract big integer from string.

  Scan up to a maximum number of characters from a string and convert the result to a GUIntBig.

  Return

    GUIntBig value, converted from its ASCII form.

  Parameters

    - `pszString`: String containing characters to be scanned. It may be terminated with a null character.

    - `nMaxLength`: The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered.

GIntBig `CPLAtoGIntBig`(const char *pszString)

  Convert a string to a 64 bit signed integer.

  Return

    64 bit signed integer.

  Since

    GDAL 2.0

  Parameters

    - `pszString`: String containing 64 bit signed integer.

GIntBig `CPLAtoGIntBigEx`(const char *pszString, int bWarn, int *pbOverflow)

  Convert a string to a 64 bit signed integer.

  Return

    64 bit signed integer.

  Since

    GDAL 2.0

  Parameters

    - `pszString`: String containing 64 bit signed integer.

    - `bWarn`: Issue a warning if an overflow occurs during conversion

    - `pbOverflow`: Pointer to an integer to store if an overflow occurred, or NULL

void *`CPLScanPointer`(const char *pszString, int nMaxLength)

  Extract pointer from string.

  Scan up to a maximum number of characters from a string and convert the result to a pointer.

  Return

    pointer value, converted from its ASCII form.

  Parameters

    - `pszString`: String containing characters to be scanned. It may be terminated with a null character.

    - `nMaxLength`: The maximum number of character to consider as part of the number. Less characters will be considered if a null character is encountered.

int `CPLPrintString`(char *pszDest, const char *pszSrc, int nMaxLen)

  Copy the string pointed to by pszSrc, NOT including the terminating `\0’ character, to the array pointed to by pszDest.

  Return

    Number of characters printed.

  Parameters

    - `pszDest`: Pointer to the destination string buffer. Should be large enough to hold the resulting string.

    - `pszSrc`: Pointer to the source buffer.

    - `nMaxLen`: Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated.

int `CPLPrintStringFill`(char *pszDest, const char *pszSrc, int nMaxLen)

  Copy the string pointed to by pszSrc, NOT including the terminating `\0’ character, to the array pointed to by pszDest.

  Remainder of the destination string will be filled with space characters. This is only difference from the PrintString().

  Return

    Number of characters printed.

  Parameters

    - `pszDest`: Pointer to the destination string buffer. Should be large enough to hold the resulting string.

    - `pszSrc`: Pointer to the source buffer.

    - `nMaxLen`: Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated.

int `CPLPrintInt32`(char *pszBuffer, GInt32 iValue, int nMaxLen)

  Print GInt32 value into specified string buffer.

  This string will not be NULL-terminated.

  Return

    Number of characters printed.

  Parameters

    - `pszBuffer`: Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed.

    - `iValue`: Numerical value to print.

    - `nMaxLen`: Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated.

int `CPLPrintUIntBig`(char *pszBuffer, GUIntBig iValue, int nMaxLen)

  Print GUIntBig value into specified string buffer.

  This string will not be NULL-terminated.

  Return

    Number of characters printed.

  Parameters

    - `pszBuffer`: Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed.

    - `iValue`: Numerical value to print.

    - `nMaxLen`: Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated.

int `CPLPrintDouble`(char *pszBuffer, const char *pszFormat, double dfValue, const char *pszLocale)

  Print double value into specified string buffer.

  Exponential character flag ‘E’ (or ‘e’) will be replaced with ‘D’, as in Fortran. Resulting string will not to be NULL-terminated.

  Return

    Number of characters printed.

  Parameters

    - `pszBuffer`: Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed.

    - `pszFormat`: Format specifier (for example, “%16.9E”).

    - `dfValue`: Numerical value to print.

    - `pszLocale`: Unused.

int `CPLPrintTime`(char *pszBuffer, int nMaxLen, const char *pszFormat, const struct tm *poBrokenTime, const char *pszLocale)

  Print specified time value accordingly to the format options and specified locale name.

  This function does following:

  - if locale parameter is not NULL, the current locale setting will be stored and replaced with the specified one;

  - format time value with the strftime(3) function;

  - restore back current locale, if was saved.

  Return

    Number of characters printed.

  Parameters

    - `pszBuffer`: Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed.

    - `nMaxLen`: Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated.

    - `pszFormat`: Controls the output format. Options are the same as for strftime(3) function.

    - `poBrokenTime`: Pointer to the broken-down time structure. May be requested with the VSIGMTime() and VSILocalTime() functions.

    - `pszLocale`: Pointer to a character string containing locale name (“C”, “POSIX”, “us_US”, “ru_RU.KOI8-R” etc.). If NULL we will not manipulate with locale settings and current process locale will be used for printing. Be aware that it may be unsuitable to use current locale for printing time, because all names will be printed in your native language, as well as time format settings also may be adjusted differently from the C/POSIX defaults. To solve these problems this option was introduced.

int `CPLPrintPointer`(char *pszBuffer, void *pValue, int nMaxLen)

  Print pointer value into specified string buffer.

  This string will not be NULL-terminated.

  Return

    Number of characters printed.

  Parameters

    - `pszBuffer`: Pointer to the destination string buffer. Should be large enough to hold the resulting string. Note, that the string will not be NULL-terminated, so user should do this himself, if needed.

    - `pValue`: Pointer to ASCII encode.

    - `nMaxLen`: Maximum length of the resulting string. If string length is greater than nMaxLen, it will be truncated.

void *`CPLGetSymbol`(const char *pszLibrary, const char *pszSymbolName)

  Fetch a function pointer from a shared library / DLL.

  This function is meant to abstract access to shared libraries and DLLs and performs functions similar to dlopen()/dlsym() on Unix and LoadLibrary() / GetProcAddress() on Windows.

  If no support for loading entry points from a shared library is available this function will always return NULL. Rules on when this function issues a CPLError() or not are not currently well defined, and will have to be resolved in the future.

  Currently CPLGetSymbol() doesn’t try to:

  - prevent the reference count on the library from going up for every request, or given any opportunity to unload the library.

  - Attempt to look for the library in non-standard locations.

  - Attempt to try variations on the symbol name, like pre-pending or post-pending an underscore.

  Some of these issues may be worked on in the future.

  Return

    A pointer to the function if found, or NULL if the function isn’t found, or the shared library can’t be loaded.

  Parameters

    - `pszLibrary`: the name of the shared library or DLL containing the function. May contain path to file. If not system supplies search paths will be used.

    - `pszSymbolName`: the name of the function to fetch a pointer to.

int `CPLGetExecPath`(char *pszPathBuf, int nMaxLength)

  Fetch path of executable.

  The path to the executable currently running is returned. This path includes the name of the executable. Currently this only works on win32 and linux platforms. The returned path is UTF-8 encoded.

  Return

    FALSE on failure or TRUE on success.

  Parameters

    - `pszPathBuf`: the buffer into which the path is placed.

    - `nMaxLength`: the buffer size, MAX_PATH+1 is suggested.

const char *`CPLGetPath`(const char *pszFilename)

  Extract directory path portion of filename.

  Returns a string containing the directory path portion of the passed filename. If there is no path in the passed filename an empty string will be returned (not NULL).

  Return

    Path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call. The returned will generally not contain a trailing path separator.

  Parameters

    - `pszFilename`: the filename potentially including a path.

const char *`CPLGetDirname`(const char *pszFilename)

  Extract directory path portion of filename.

  Returns a string containing the directory path portion of the passed filename. If there is no path in the passed filename the dot will be returned. It is the only difference from CPLGetPath().

  Return

    Path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call. The returned will generally not contain a trailing path separator.

  Parameters

    - `pszFilename`: the filename potentially including a path.

const char *`CPLGetFilename`(const char *pszFullFilename)

  Extract non-directory portion of filename.

  Returns a string containing the bare filename portion of the passed filename. If there is no filename (passed value ends in trailing directory separator) an empty string is returned.

  Return

    just the non-directory portion of the path (points back into original string).

  Parameters

    - `pszFullFilename`: the full filename potentially including a path.

const char *`CPLGetBasename`(const char *pszFullFilename)

  Extract basename (non-directory, non-extension) portion of filename.

  Returns a string containing the file basename portion of the passed name. If there is no basename (passed value ends in trailing directory separator, or filename starts with a dot) an empty string is returned.

  Return

    just the non-directory, non-extension portion of the path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call.

  Parameters

    - `pszFullFilename`: the full filename potentially including a path.

const char *`CPLGetExtension`(const char *pszFullFilename)

  Extract filename extension from full filename.

  Returns a string containing the extension portion of the passed name. If there is no extension (the filename has no dot) an empty string is returned. The returned extension will not include the period.

  Return

    just the extension portion of the path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call.

  Parameters

    - `pszFullFilename`: the full filename potentially including a path.

char *`CPLGetCurrentDir`(void)

  Get the current working directory name.

  Return

    a pointer to buffer, containing current working directory path or NULL in case of error. User is responsible to free that buffer after usage with CPLFree() function. If HAVE_GETCWD macro is not defined, the function returns NULL.

const char *`CPLFormFilename`(const char *pszPath, const char *pszBasename, const char *pszExtension)

  Build a full file path from a passed path, file basename and extension.

  The path, and extension are optional. The basename may in fact contain an extension if desired.

  Return

    a fully formed filename in an internal static string. Do not modify or free the returned string. The string may be destroyed by the next CPL call.

  Parameters

    - `pszPath`: directory path to the directory containing the file. This may be relative or absolute, and may have a trailing path separator or not. May be NULL.

    - `pszBasename`: file basename. May optionally have path and/or extension. Must NOT be NULL.

    - `pszExtension`: file extension, optionally including the period. May be NULL.

const char *`CPLFormCIFilename`(const char *pszPath, const char *pszBasename, const char *pszExtension)

  Case insensitive file searching, returning full path.

  This function tries to return the path to a file regardless of whether the file exactly matches the basename, and extension case, or is all upper case, or all lower case. The path is treated as case sensitive. This function is equivalent to CPLFormFilename() on case insensitive file systems (like Windows).

  Return

    a fully formed filename in an internal static string. Do not modify or free the returned string. The string may be destroyed by the next CPL call.

  Parameters

    - `pszPath`: directory path to the directory containing the file. This may be relative or absolute, and may have a trailing path separator or not. May be NULL.

    - `pszBasename`: file basename. May optionally have path and/or extension. May not be NULL.

    - `pszExtension`: file extension, optionally including the period. May be NULL.

const char *`CPLResetExtension`(const char *pszPath, const char *pszExt)

  Replace the extension with the provided one.

  Return

    an altered filename with the new extension. Do not modify or free the returned string. The string may be destroyed by the next CPL call.

  Parameters

    - `pszPath`: the input path, this string is not altered.

    - `pszExt`: the new extension to apply to the given path.

const char *`CPLProjectRelativeFilename`(const char *pszProjectDir, const char *pszSecondaryFilename)

  Find a file relative to a project file.

  Given the path to a “project” directory, and a path to a secondary file referenced from that project, build a path to the secondary file that the current application can use. If the secondary path is already absolute, rather than relative, then it will be returned unaltered.

  Examples:

  Return

    a composed path to the secondary file. The returned string is internal and should not be altered, freed, or depending on past the next CPL call.

  Parameters

    - `pszProjectDir`: the directory relative to which the secondary files path should be interpreted.

    - `pszSecondaryFilename`: the filename (potentially with path) that is to be interpreted relative to the project directory.

int `CPLIsFilenameRelative`(const char *pszFilename)

  Is filename relative or absolute?

  The test is filesystem convention agnostic. That is it will test for Unix style and windows style path conventions regardless of the actual system in use.

  Return

    TRUE if the filename is relative or FALSE if it is absolute.

  Parameters

    - `pszFilename`: the filename with path to test.

const char *`CPLExtractRelativePath`(const char *pszBaseDir, const char *pszTarget, int *pbGotRelative)

  Get relative path from directory to target file.

  Computes a relative path for pszTarget relative to pszBaseDir. Currently this only works if they share a common base path. The returned path is normally into the pszTarget string. It should only be considered valid as long as pszTarget is valid or till the next call to this function, whichever comes first.

  Return

    an adjusted path or the original if it could not be made relative to the pszBaseFile’s path.

  Parameters

    - `pszBaseDir`: the name of the directory relative to which the path should be computed. pszBaseDir may be NULL in which case the original target is returned without relativizing.

    - `pszTarget`: the filename to be changed to be relative to pszBaseDir.

    - `pbGotRelative`: Pointer to location in which a flag is placed indicating that the returned path is relative to the basename (TRUE) or not (FALSE). This pointer may be NULL if flag is not desired.

const char *`CPLCleanTrailingSlash`(const char *pszPath)

  Remove trailing forward/backward slash from the path for UNIX/Windows resp.

  Returns a string containing the portion of the passed path string with trailing slash removed. If there is no path in the passed filename an empty string will be returned (not NULL).

  Return

    Path in an internal string which must not be freed. The string may be destroyed by the next CPL filename handling call.

  Parameters

    - `pszPath`: the path to be cleaned up

char **`CPLCorrespondingPaths`(const char *pszOldFilename, const char *pszNewFilename, char **papszFileList)

  Identify corresponding paths.

  Given a prototype old and new filename this function will attempt to determine corresponding names for a set of other old filenames that will rename them in a similar manner. This correspondence assumes there are two possibly kinds of renaming going on. A change of path, and a change of filename stem.

  If a consistent renaming cannot be established for all the files this function will return indicating an error.

  The returned file list becomes owned by the caller and should be destroyed with CSLDestroy().

  Return

    a list of files corresponding to papszFileList but renamed to correspond to pszNewFilename.

  Parameters

    - `pszOldFilename`: path to old prototype file.

    - `pszNewFilename`: path to new prototype file.

    - `papszFileList`: list of other files associated with pszOldFilename to rename similarly.

int `CPLCheckForFile`(char *pszFilename, char **papszSiblingList)

  Check for file existence.

  The function checks if a named file exists in the filesystem, hopefully in an efficient fashion if a sibling file list is available. It exists primarily to do faster file checking for functions like GDAL open methods that get a list of files from the target directory.

  If the sibling file list exists (is not NULL) it is assumed to be a list of files in the same directory as the target file, and it will be checked (case insensitively) for a match. If a match is found, pszFilename is updated with the correct case and TRUE is returned.

  If papszSiblingFiles is NULL, a VSIStatL() is used to test for the files existence, and no case insensitive testing is done.

  Return

    TRUE if a match is found, or FALSE if not.

  Parameters

    - `pszFilename`: name of file to check for - filename case updated in some cases.

    - `papszSiblingFiles`: a list of files in the same directory as pszFilename if available, or NULL. This list should have no path components.

const char *`CPLGenerateTempFilename`(const char *pszStem)

  Generate temporary file name.

  Returns a filename that may be used for a temporary file. The location of the file tries to follow operating system semantics but may be forced via the CPL_TMPDIR configuration option.

  Return

    a filename which is valid till the next CPL call in this thread.

  Parameters

    - `pszStem`: if non-NULL this will be part of the filename.

const char *`CPLExpandTilde`(const char *pszFilename)

  Expands ~/ at start of filename.

  Assumes that the HOME configuration option is defined.

  Return

    an expanded filename.

  Since

    GDAL 2.2

  Parameters

    - `pszFilename`: filename potentially starting with ~/

const char *`CPLGetHomeDir`(void)

  Return the path to the home directory.

  That is the value of the USERPROFILE environment variable on Windows, or HOME on other platforms.

  Return

    the home directory, or NULL.

  Since

    GDAL 2.3

const char *`CPLLaunderForFilename`(const char *pszName, const char *pszOutputPath)

  Launder a string to be compatible of a filename.

  Return

    the laundered name.

  Since

    GDAL 3.1

  Parameters

    - `pszName`: The input string to launder.

    - `pszOutputPath`: The directory where the file would be created. Unused for now. May be NULL.

const char *`CPLFindFile`(const char *pszClass, const char *pszBasename)

  CPLFindFile.

const char *`CPLDefaultFindFile`(const char *pszClass, const char *pszBasename)

  CPLDefaultFindFile.

void `CPLPushFileFinder`(CPLFileFinder pfnFinder)

  CPLPushFileFinder.

CPLFileFinder `CPLPopFileFinder`(void)

  CPLPopFileFinder.

void `CPLPushFinderLocation`(const char *)

  CPLPushFinderLocation.

void `CPLPopFinderLocation`(void)

  CPLPopFinderLocation.

void `CPLFinderClean`(void)

  CPLFinderClean.

int `CPLStat`(const char *pszPath, VSIStatBuf *psStatBuf)

  Same as VSIStat() except it works on “C:” as if it were “C:".

FILE *`CPLOpenShared`(const char *pszFilename, const char *pszAccess, int bLargeIn)

  Open a shared file handle.

  Some operating systems have limits on the number of file handles that can be open at one time. This function attempts to maintain a registry of already open file handles, and reuse existing ones if the same file is requested by another part of the application.

  Note that access is only shared for access types “r”, “rb”, “r+” and “rb+”. All others will just result in direct VSIOpen() calls. Keep in mind that a file is only reused if the file name is exactly the same. Different names referring to the same file will result in different handles.

  The VSIFOpen() or VSIFOpenL() function is used to actually open the file, when an existing file handle can’t be shared.

  Return

    a file handle or NULL if opening fails.

  Parameters

    - `pszFilename`: the name of the file to open.

    - `pszAccess`: the normal fopen()/VSIFOpen() style access string.

    - `bLargeIn`: If TRUE VSIFOpenL() (for large files) will be used instead of VSIFOpen().

void `CPLCloseShared`(FILE *fp)

  Close shared file.

  Dereferences the indicated file handle, and closes it if the reference count has dropped to zero. A CPLError() is issued if the file is not in the shared file list.

  Parameters

    - `fp`: file handle from CPLOpenShared() to deaccess.

CPLSharedFileInfo *`CPLGetSharedList`(int *pnCount)

  Fetch list of open shared files.

  Return

    the pointer to the first in the array of shared file info structures.

  Parameters

    - `pnCount`: place to put the count of entries.

void `CPLDumpSharedList`(FILE *fp)

  Report open shared files.

  Dumps all open shared files to the indicated file handle. If the file handle is NULL information is sent via the CPLDebug() call.

  Parameters

    - `fp`: File handle to write to.

double `CPLDMSToDec`(const char *is)

  CPLDMSToDec.

const char *`CPLDecToDMS`(double dfAngle, const char *pszAxis, int nPrecision)

  Translate a decimal degrees value to a DMS string with hemisphere.

double `CPLPackedDMSToDec`(double dfPacked)

  Convert a packed DMS value (DDDMMMSSS.SS) into decimal degrees.

  This function converts a packed DMS angle to seconds. The standard packed DMS format is:

  degrees * 1000000 + minutes * 1000 + seconds

  Example: angle = 120025045.25 yields deg = 120 min = 25 sec = 45.25

  The algorithm used for the conversion is as follows:

  1. The absolute value of the angle is used.

  2. The degrees are separated out: deg = angle/1000000 (fractional portion truncated)

  3. The minutes are separated out: min = (angle - deg * 1000000) / 1000 (fractional portion truncated)

  4. The seconds are then computed: sec = angle - deg * 1000000 - min * 1000

  5. The total angle in seconds is computed: sec = deg * 3600.0 + min * 60.0 + sec

  6. The sign of sec is set to that of the input angle.

  Packed DMS values used by the USGS GCTP package and probably by other software.

  NOTE: This code does not validate input value. If you give the wrong value, you will get the wrong result.

  Return

    Angle in decimal degrees.

  Parameters

    - `dfPacked`: Angle in packed DMS format.

double `CPLDecToPackedDMS`(double dfDec)

  Convert decimal degrees into packed DMS value (DDDMMMSSS.SS).

  This function converts a value, specified in decimal degrees into packed DMS angle. The standard packed DMS format is:

  degrees * 1000000 + minutes * 1000 + seconds

  See also CPLPackedDMSToDec().

  Return

    Angle in packed DMS format.

  Parameters

    - `dfDec`: Angle in decimal degrees.

void `CPLStringToComplex`(const char *pszString, double *pdfReal, double *pdfImag)

  Fetch the real and imaginary part of a serialized complex number.

int `CPLUnlinkTree`(const char *pszPath)

  Recursively unlink a directory.

  Return

    0 on successful completion, -1 if function fails.

int `CPLCopyFile`(const char *pszNewPath, const char *pszOldPath)

  Copy a file.

int `CPLCopyTree`(const char *pszNewPath, const char *pszOldPath)

  Recursively copy a tree.

int `CPLMoveFile`(const char *pszNewPath, const char *pszOldPath)

  Move a file.

int `CPLSymlink`(const char *pszOldPath, const char *pszNewPath, CSLConstList papszOptions)

  Create a symbolic link.

void *`CPLCreateZip`(const char *pszZipFilename, char **papszOptions)

  Create ZIP file.

CPLErr `CPLCreateFileInZip`(void *hZip, const char *pszFilename, char **papszOptions)

  Create a file in a ZIP file.

CPLErr `CPLWriteFileInZip`(void *hZip, const void *pBuffer, int nBufferSize)

  Write in current file inside a ZIP file.

CPLErr `CPLCloseFileInZip`(void *hZip)

  Close current file inside ZIP file.

CPLErr `CPLCloseZip`(void *hZip)

  Close ZIP file.

void *`CPLZLibDeflate`(const void *ptr, size_t nBytes, int nLevel, void *outptr, size_t nOutAvailableBytes, size_t *pnOutBytes)

  Compress a buffer with ZLib DEFLATE compression.

  Return

    the output buffer (to be freed with VSIFree() if not provided) or NULL in case of error.

  Since

    GDAL 1.10.0

  Parameters

    - `ptr`: input buffer.

    - `nBytes`: size of input buffer in bytes.

    - `nLevel`: ZLib compression level (-1 for default). Currently unused

    - `outptr`: output buffer, or NULL to let the function allocate it.

    - `nOutAvailableBytes`: size of output buffer if provided, or ignored.

    - `pnOutBytes`: pointer to a size_t, where to store the size of the output buffer.

void *`CPLZLibInflate`(const void *ptr, size_t nBytes, void *outptr, size_t nOutAvailableBytes, size_t *pnOutBytes)

  Uncompress a buffer compressed with ZLib DEFLATE compression.

  Return

    the output buffer (to be freed with VSIFree() if not provided) or NULL in case of error.

  Since

    GDAL 1.10.0

  Parameters

    - `ptr`: input buffer.

    - `nBytes`: size of input buffer in bytes.

    - `outptr`: output buffer, or NULL to let the function allocate it.

    - `nOutAvailableBytes`: size of output buffer if provided, or ignored.

    - `pnOutBytes`: pointer to a size_t, where to store the size of the output buffer.

int `CPLValidateXML`(const char *pszXMLFilename, const char *pszXSDFilename, CSLConstList papszOptions)

  Validate a XML file against a XML schema.

  Return

    TRUE if the XML file validates against the XML schema.

  Since

    GDAL 1.10.0

  Parameters

    - `pszXMLFilename`: the filename of the XML file to validate.

    - `pszXSDFilename`: the filename of the XSD schema.

    - `papszOptions`: unused for now. Set to NULL.

char *`CPLsetlocale`(int category, const char *locale)

  Prevents parallel executions of setlocale().

  Calling setlocale() concurrently from two or more threads is a potential data race. A mutex is used to provide a critical region so that only one thread at a time can be executing setlocale().

  The return should not be freed, and copied quickly as it may be invalidated by a following next call to CPLsetlocale().

  Return

    See your compiler’s documentation on setlocale.

  Parameters

    - `category`: See your compiler’s documentation on setlocale.

    - `locale`: See your compiler’s documentation on setlocale.

int `CPLIsPowerOfTwo`(unsigned int i)

  CPLIsPowerOfTwo()

  Return

    TRUE if i is power of two otherwise return FALSE

  Parameters

    - `i`: - tested number

struct `CPLSharedFileInfo`
  #include <cpl_conv.h>

  Information on a shared file.

  Public Members

  FILE *`fp`

    File pointer.

  int `nRefCount`

    Reference counter.

  int `bLarge`

    Whether fp must be interpreted as VSIFILE*.

  char *`pszFilename`

    Filename.

  char *`pszAccess`

    Access mode.

namespace `cpl`

  Functions

  template<typename `To`, typename `From`>
  To `down_cast`(From *f)

    Use cpl::down_cast<Derived*>(pointer_to_base) as equivalent of static_cast<Derived*>(pointer_to_base) with safe checking in debug mode.

    Only works if no virtual inheritance is involved.

    Return

      pointer to a derived class

    Parameters

      - `f`: pointer to a base class

## cpl_csv.h

Enums

enum `CSVCompareCriteria`

  Values:

  `CC_ExactString`
  `CC_ApproxString`
  `CC_Integer`

Functions

const char *`CSVFilename`(const char *)

char `CSVDetectSeperator`(const char *pszLine)

  Detect which field separator is used.

  Currently, it can detect comma, semicolon, space or tabulation. In case of ambiguity or no separator found, comma will be considered as the separator.

  Return

    ’,’, ‘;’, ‘ ‘ or ‘’

char **`CSVReadParseLine`(FILE *fp)

char **`CSVReadParseLine2`(FILE *fp, char chDelimiter)

char **`CSVReadParseLineL`(VSILFILE *fp)

char **`CSVReadParseLine2L`(VSILFILE *fp, char chDelimiter)

char **`CSVScanLines`(FILE *, int, const char *, CSVCompareCriteria)

char **`CSVScanLinesL`(VSILFILE *, int, const char *, CSVCompareCriteria)

char **`CSVScanFile`(const char *, int, const char *, CSVCompareCriteria)

char **`CSVScanFileByName`(const char *, const char *, const char *, CSVCompareCriteria)

char **`CSVGetNextLine`(const char *)

int `CSVGetFieldId`(FILE *, const char *)

int `CSVGetFieldIdL`(VSILFILE *, const char *)

int `CSVGetFileFieldId`(const char *, const char *)

void `CSVDeaccess`(const char *)

const char *`CSVGetField`(const char *, const char *, const char *, CSVCompareCriteria, const char *)

## cpl_error.h

CPL error handling services.

Defines

`CPLE_None`

  No error.

`CPLE_AppDefined`

  Application defined error.

`CPLE_OutOfMemory`

  Out of memory error.

`CPLE_FileIO`

  File I/O error.

`CPLE_OpenFailed`

  Open failed.

`CPLE_IllegalArg`

  Illegal argument.

`CPLE_NotSupported`

  Not supported.

`CPLE_AssertionFailed`

  Assertion failed.

`CPLE_NoWriteAccess`

  No write access.

`CPLE_UserInterrupt`

  User interrupted.

`CPLE_ObjectNull`

  NULL object.

`CPLE_HttpResponse`

  HTTP response.

`CPLE_AWSBucketNotFound`

  AWSBucketNotFound.

`CPLE_AWSObjectNotFound`

  AWSObjectNotFound.

`CPLE_AWSAccessDenied`

  AWSAccessDenied.

`CPLE_AWSInvalidCredentials`

  AWSInvalidCredentials.

`CPLE_AWSSignatureDoesNotMatch`

  AWSSignatureDoesNotMatch.

`CPLE_AWSError`

  VSIE_AWSError.

`CPLDebugOnly`(...)

  Same as CPLDebug(), but expands to nothing for non-DEBUG builds.

  Since

    GDAL 3.1

`CPLAssert`(expr)

  Assert on an expression.

  Only enabled in DEBUG mode

`CPLAssertAlwaysEval`(expr)

  Assert on an expression in DEBUG mode.

  Evaluate it also in non-DEBUG mode (useful to ‘consume’ a error return variable)

`VALIDATE_POINTER0`(ptr, func)

  Validate that a pointer is not NULL.

`VALIDATE_POINTER1`(ptr, func, rc)

  Validate that a pointer is not NULL, and return rc if it is NULL.

Typedefs

typedef int `CPLErrorNum`

  Error number.

typedef void (*`CPLErrorHandler`)(CPLErr, CPLErrorNum, const char *)

  Callback for a custom error handler.

Enums

enum `CPLErr`

  Error category.

  Values:

  `CE_None` = 0
  `CE_Debug` = 1
  `CE_Warning` = 2
  `CE_Failure` = 3
  `CE_Fatal` = 4

Functions

void `CPLError`(CPLErr eErrClass, CPLErrorNum err_no, const char *fmt, ...)

  Report an error.

  This function reports an error in a manner that can be hooked and reported appropriate by different applications.

  The effect of this function can be altered by applications by installing a custom error handling using CPLSetErrorHandler().

  The eErrClass argument can have the value CE_Warning indicating that the message is an informational warning, CE_Failure indicating that the action failed, but that normal recover mechanisms will be used or CE_Fatal meaning that a fatal error has occurred, and that CPLError() should not return.

  The default behaviour of CPLError() is to report errors to stderr, and to abort() after reporting a CE_Fatal error. It is expected that some applications will want to suppress error reporting, and will want to install a C++ exception, or longjmp() approach to no local fatal error recovery.

  Regardless of how application error handlers or the default error handler choose to handle an error, the error number, and message will be stored for recovery with CPLGetLastErrorNo() and CPLGetLastErrorMsg().

  Parameters

    - `eErrClass`: one of CE_Warning, CE_Failure or CE_Fatal.

    - `err_no`: the error number (CPLE_*) from cpl_error.h.

    - `fmt`: a printf() style format string. Any additional arguments will be treated as arguments to fill in this format in a manner similar to printf().

void `CPLErrorV`(CPLErr, CPLErrorNum, const char *, va_list)

  Same as CPLError() but with a va_list.

void `CPLEmergencyError`(const char *pszMessage)

  Fatal error when things are bad.

  This function should be called in an emergency situation where it is unlikely that a regular error report would work. This would include in the case of heap exhaustion for even small allocations, or any failure in the process of reporting an error (such as TLS allocations).

  This function should never return. After the error message has been reported as best possible, the application will abort() similarly to how CPLError() aborts on CE_Fatal class errors.

  Parameters

    - `pszMessage`: the error message to report.

void `CPLErrorReset`(void)

  Erase any traces of previous errors.

  This is normally used to ensure that an error which has been recovered from does not appear to be still in play with high level functions.

CPLErrorNum `CPLGetLastErrorNo`(void)

  Fetch the last error number.

  Fetches the last error number posted with CPLError(), that hasn’t been cleared by CPLErrorReset(). This is the error number, not the error class.

  Return

    the error number of the last error to occur, or CPLE_None (0) if there are no posted errors.

CPLErr `CPLGetLastErrorType`(void)

  Fetch the last error type.

  Fetches the last error type posted with CPLError(), that hasn’t been cleared by CPLErrorReset(). This is the error class, not the error number.

  Return

    the error type of the last error to occur, or CE_None (0) if there are no posted errors.

const char *`CPLGetLastErrorMsg`(void)

  Get the last error message.

  Fetches the last error message posted with CPLError(), that hasn’t been cleared by CPLErrorReset(). The returned pointer is to an internal string that should not be altered or freed.

  Return

    the last error message, or NULL if there is no posted error message.

GUInt32 `CPLGetErrorCounter`(void)

  Get the error counter.

  Fetches the number of errors emitted in the current error context, since the last call to CPLErrorReset()

  Return

    the error counter.

  Since

    GDAL 2.3

void *`CPLGetErrorHandlerUserData`(void)

  Fetch the user data for the error context.

  Fetches the user data for the current error context. You can set the user data for the error context when you add your handler by issuing CPLSetErrorHandlerEx() and CPLPushErrorHandlerEx(). Note that user data is primarily intended for providing context within error handlers themselves, but they could potentially be abused in other useful ways with the usual caveat emptor understanding.

  Return

    the user data pointer for the error context

void `CPLErrorSetState`(CPLErr eErrClass, CPLErrorNum err_no, const char *pszMsg)

  Restore an error state, without emitting an error.

  Can be useful if a routine might call CPLErrorReset() and one wants to preserve the previous error state.

  Since

    GDAL 2.0

void `CPLLoggingErrorHandler`(CPLErr, CPLErrorNum, const char *)

  Error handler that logs into the file defined by the CPL_LOG configuration option, or stderr otherwise.

void `CPLDefaultErrorHandler`(CPLErr eErrClass, CPLErrorNum nError, const char *pszErrorMsg)

  Default error handler.

void `CPLQuietErrorHandler`(CPLErr eErrClass, CPLErrorNum nError, const char *pszErrorMsg)

  Error handler that does not do anything, except for debug messages.

void `CPLTurnFailureIntoWarning`(int bOn)

  Whether failures should be turned into warnings.

CPLErrorHandler `CPLSetErrorHandler`(CPLErrorHandler pfnErrorHandlerNew)

  Install custom error handler.

  Allow the library’s user to specify an error handler function. A valid error handler is a C function with the following prototype:

  Pass NULL to come back to the default behavior. The default behaviour (CPLDefaultErrorHandler()) is to write the message to stderr.

  The msg will be a partially formatted error message not containing the “ERROR %d:” portion emitted by the default handler. Message formatting is handled by CPLError() before calling the handler. If the error handler function is passed a CE_Fatal class error and returns, then CPLError() will call abort(). Applications wanting to interrupt this fatal behaviour will have to use longjmp(), or a C++ exception to indirectly exit the function.

  Another standard error handler is CPLQuietErrorHandler() which doesn’t make any attempt to report the passed error or warning messages but will process debug messages via CPLDefaultErrorHandler.

  Note that error handlers set with CPLSetErrorHandler() apply to all threads in an application, while error handlers set with CPLPushErrorHandler are thread-local. However, any error handlers pushed with CPLPushErrorHandler (and not removed with CPLPopErrorHandler) take precedence over the global error handlers set with CPLSetErrorHandler(). Generally speaking CPLSetErrorHandler() would be used to set a desired global error handler, while CPLPushErrorHandler() would be used to install a temporary local error handler, such as CPLQuietErrorHandler() to suppress error reporting in a limited segment of code.

  Return

    returns the previously installed error handler.

  Parameters

    - `pfnErrorHandlerNew`: new error handler function.

CPLErrorHandler `CPLSetErrorHandlerEx`(CPLErrorHandler pfnErrorHandlerNew, void *pUserData)

  Install custom error handle with user’s data.

  This method is essentially CPLSetErrorHandler with an added pointer to pUserData. The pUserData is not returned in the CPLErrorHandler, however, and must be fetched via CPLGetErrorHandlerUserData.

  Return

    returns the previously installed error handler.

  Parameters

    - `pfnErrorHandlerNew`: new error handler function.

    - `pUserData`: User data to carry along with the error context.

void `CPLPushErrorHandler`(CPLErrorHandler pfnErrorHandlerNew)

  Push a new CPLError handler.

  This pushes a new error handler on the thread-local error handler stack. This handler will be used until removed with CPLPopErrorHandler().

  The CPLSetErrorHandler() docs have further information on how CPLError handlers work.

  Parameters

    - `pfnErrorHandlerNew`: new error handler function.

void `CPLPushErrorHandlerEx`(CPLErrorHandler pfnErrorHandlerNew, void *pUserData)

  Push a new CPLError handler with user data on the error context.

  This pushes a new error handler on the thread-local error handler stack. This handler will be used until removed with CPLPopErrorHandler(). Obtain the user data back by using CPLGetErrorContext().

  The CPLSetErrorHandler() docs have further information on how CPLError handlers work.

  Parameters

    - `pfnErrorHandlerNew`: new error handler function.

    - `pUserData`: User data to put on the error context.

void `CPLSetCurrentErrorHandlerCatchDebug`(int bCatchDebug)

  Set if the current error handler should intercept debug messages, or if they should be processed by the previous handler.

  By default when installing a custom error handler, this one intercepts debug messages. In some cases, this might not be desirable and the user would prefer that the previous installed handler (or the default one if no previous installed handler exists in the stack) deal with it. In which case, this function should be called with bCatchDebug = FALSE.

  Since

    GDAL 2.1

  Parameters

    - `bCatchDebug`: FALSE if the current error handler should not intercept debug messages

void `CPLPopErrorHandler`(void)

  Pop error handler off stack.

  Discards the current error handler on the error handler stack, and restores the one in use before the last CPLPushErrorHandler() call. This method has no effect if there are no error handlers on the current threads error handler stack.

void `CPLDebug`(const char *pszCategory, const char *pszFormat, ...)

  Display a debugging message.

  The category argument is used in conjunction with the CPL_DEBUG environment variable to establish if the message should be displayed. If the CPL_DEBUG environment variable is not set, no debug messages are emitted (use CPLError(CE_Warning, …) to ensure messages are displayed). If CPL_DEBUG is set, but is an empty string or the word “ON” then all debug messages are shown. Otherwise only messages whose category appears somewhere within the CPL_DEBUG value are displayed (as determined by strstr()).

  Categories are usually an identifier for the subsystem producing the error. For instance “GDAL” might be used for the GDAL core, and “TIFF” for messages from the TIFF translator.

  Parameters

    - `pszCategory`: name of the debugging message category.

    - `pszFormat`: printf() style format string for message to display. Remaining arguments are assumed to be for format.

void `_CPLAssert`(const char *pszExpression, const char *pszFile, int iLine)

  Report failure of a logical assertion.

  Applications would normally use the CPLAssert() macro which expands into code calling _CPLAssert() only if the condition fails. _CPLAssert() will generate a CE_Fatal error call to CPLError(), indicating the file name, and line number of the failed assertion, as well as containing the assertion itself.

  There is no reason for application code to call _CPLAssert() directly.

## cpl_http.h

Interface for downloading HTTP, FTP documents.

Functions

int `CPLHTTPEnabled`(void)

  Return if CPLHTTP services can be useful.

  Those services depend on GDAL being build with libcurl support.

  Return

    TRUE if libcurl support is enabled

CPLHTTPResult *`CPLHTTPFetch`(const char *pszURL, CSLConstList papszOptions)

  Fetch a document from an url and return in a string.

  Alternatively, if not defined in the papszOptions arguments, the CONNECTTIMEOUT, TIMEOUT, LOW_SPEED_TIME, LOW_SPEED_LIMIT, USERPWD, PROXY, HTTPS_PROXY, PROXYUSERPWD, PROXYAUTH, NETRC, MAX_RETRY and RETRY_DELAY, HEADER_FILE, HTTP_VERSION, SSL_VERIFYSTATUS, USE_CAPI_STORE values are searched in the configuration options respectively named GDAL_HTTP_CONNECTTIMEOUT, GDAL_HTTP_TIMEOUT, GDAL_HTTP_LOW_SPEED_TIME, GDAL_HTTP_LOW_SPEED_LIMIT, GDAL_HTTP_USERPWD, GDAL_HTTP_PROXY, GDAL_HTTPS_PROXY, GDAL_HTTP_PROXYUSERPWD, GDAL_PROXY_AUTH, GDAL_HTTP_NETRC, GDAL_HTTP_MAX_RETRY, GDAL_HTTP_RETRY_DELAY, GDAL_HTTP_HEADER_FILE, GDAL_HTTP_VERSION, GDAL_HTTP_SSL_VERIFYSTATUS, GDAL_HTTP_USE_CAPI_STORE

  Parameters

    - `pszURL`: valid URL recognized by underlying download library (libcurl)

    - `papszOptions`: option list as a NULL-terminated array of strings. May be NULL. The following options are handled :

      - CONNECTTIMEOUT=val, where val is in seconds (possibly with decimals). This is the maximum delay for the connection to be established before being aborted (GDAL >= 2.2).

      - TIMEOUT=val, where val is in seconds. This is the maximum delay for the whole request to complete before being aborted.

      - LOW_SPEED_TIME=val, where val is in seconds. This is the maximum time where the transfer speed should be below the LOW_SPEED_LIMIT (if not specified 1b/s), before the transfer to be considered too slow and aborted. (GDAL >= 2.1)

      - LOW_SPEED_LIMIT=val, where val is in bytes/second. See LOW_SPEED_TIME. Has only effect if LOW_SPEED_TIME is specified too. (GDAL >= 2.1)

      - HEADERS=val, where val is an extra header to use when getting a web page. For example “Accept: application/x-ogcwkt”

      - HEADER_FILE=filename: filename of a text file with “key: value” headers. (GDAL >= 2.2)

      - HTTPAUTH=[BASIC/NTLM/GSSNEGOTIATE/ANY] to specify an authentication scheme to use.

      - USERPWD=userid:password to specify a user and password for authentication

      - POSTFIELDS=val, where val is a nul-terminated string to be passed to the server with a POST request.

      - PROXY=val, to make requests go through a proxy server, where val is of the form proxy.server.com:port_number. This option affects both HTTP and HTTPS URLs.

      - HTTPS_PROXY=val (GDAL >= 2.4), the same meaning as PROXY, but this option is taken into account only for HTTPS URLs.

      - PROXYUSERPWD=val, where val is of the form username:password

      - PROXYAUTH=[BASIC/NTLM/DIGEST/ANY] to specify an proxy authentication scheme to use.

      - NETRC=[YES/NO] to enable or disable use of $HOME/.netrc, default YES.

      - CUSTOMREQUEST=val, where val is GET, PUT, POST, DELETE, etc.. (GDAL >= 1.9.0)

      - FORM_FILE_NAME=val, where val is upload file name. If this option and FORM_FILE_PATH present, request type will set to POST.

      - FORM_FILE_PATH=val, where val is upload file path.

      - FORM_KEY_0=val…FORM_KEY_N, where val is name of form item.

      - FORM_VALUE_0=val…FORM_VALUE_N, where val is value of the form item.

      - FORM_ITEM_COUNT=val, where val is count of form items.

      - COOKIE=val, where val is formatted as COOKIE1=VALUE1; COOKIE2=VALUE2; …

      - COOKIEFILE=val, where val is file name to read cookies from (GDAL >= 2.4)

      - COOKIEJAR=val, where val is file name to store cookies to (GDAL >= 2.4)

      - MAX_RETRY=val, where val is the maximum number of retry attempts if a 429, 502, 503 or 504 HTTP error occurs. Default is 0. (GDAL >= 2.0)

      - RETRY_DELAY=val, where val is the number of seconds between retry attempts. Default is 30. (GDAL >= 2.0)

      - MAX_FILE_SIZE=val, where val is a number of bytes (GDAL >= 2.2)

      - CAINFO=/path/to/bundle.crt. This is path to Certificate Authority (CA) bundle file. By default, it will be looked in a system location. If the CAINFO options is not defined, GDAL will also look if the CURL_CA_BUNDLE environment variable is defined to use it as the CAINFO value, and as a fallback to the SSL_CERT_FILE environment variable. (GDAL >= 2.1.3)

      - HTTP_VERSION=1.0/1.1/2/2TLS (GDAL >= 2.3). Specify HTTP version to use. Will default to 1.1 generally (except on some controlled environments, like Google Compute Engine VMs, where 2TLS will be the default). Support for HTTP/2 requires curl 7.33 or later, built against nghttp2. “2TLS” means that HTTP/2 will be attempted for HTTPS connections only. Whereas “2” means that HTTP/2 will be attempted for HTTP or HTTPS.

      - SSL_VERIFYSTATUS=YES/NO (GDAL >= 2.3, and curl >= 7.41): determines whether the status of the server cert using the “Certificate Status Request” TLS extension (aka. OCSP stapling) should be checked. If this option is enabled but the server does not support the TLS extension, the verification will fail. Default to NO.

      - USE_CAPI_STORE=YES/NO (GDAL >= 2.3, Windows only): whether CA certificates from the Windows certificate store. Defaults to NO.

  Return

    a CPLHTTPResult* structure that must be freed by CPLHTTPDestroyResult(), or NULL if libcurl support is disabled

CPLHTTPResult *`CPLHTTPFetchEx`(const char *pszURL, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressArg, CPLHTTPFetchWriteFunc pfnWrite, void *pWriteArg)

  Fetch a document from an url and return in a string.

  Return

    A CPLHTTPResult* structure that must be freed by CPLHTTPDestroyResult(), or NULL if libcurl support is disabled.

  Parameters

    - `pszURL`: Url to fetch document from web.

    - `papszOptions`: Option list as a NULL-terminated array of strings. Available keys see in CPLHTTPFetch.

    - `pfnProgress`: Callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL.

    - `pProgressArg`: Callback argument passed to pfnProgress.

    - `pfnWrite`: Write function pointer matching the CPLHTTPWriteFunc() semantics. May be NULL.

    - `pWriteArg`: Argument which will pass to a write function.

CPLHTTPResult **`CPLHTTPMultiFetch`(const char *const *papszURL, int nURLCount, int nMaxSimultaneous, CSLConstList papszOptions)

  Fetch several documents at once.

  Return

    an array of CPLHTTPResult* structures that must be freed by CPLHTTPDestroyMultiResult() or NULL if libcurl support is disabled

  Since

    GDAL 2.3

  Parameters

    - `papszURL`: array of valid URLs recognized by underlying download library (libcurl)

    - `nURLCount`: number of URLs of papszURL

    - `nMaxSimultaneous`: maximum number of downloads to issue simultaneously. Any negative or zer value means unlimited.

    - `papszOptions`: option list as a NULL-terminated array of strings. May be NULL. Refer to CPLHTTPFetch() for valid options.

void `CPLHTTPCleanup`(void)

  Cleanup function to call at application termination.

void `CPLHTTPDestroyResult`(CPLHTTPResult *psResult)

  Clean the memory associated with the return value of CPLHTTPFetch()

  Parameters

    - `psResult`: pointer to the return value of CPLHTTPFetch()

void `CPLHTTPDestroyMultiResult`(CPLHTTPResult **papsResults, int nCount)

  Clean the memory associated with the return value of CPLHTTPMultiFetch()

  Since

    GDAL 2.3

  Parameters

    - `papsResults`: pointer to the return value of CPLHTTPMultiFetch()

    - `nCount`: value of the nURLCount parameter passed to CPLHTTPMultiFetch()

int `CPLHTTPParseMultipartMime`(CPLHTTPResult *psResult)

  Parses a MIME multipart message.

  This function will iterate over each part and put it in a separate element of the pasMimePart array of the provided psResult structure.

  Return

    TRUE if the message contains MIME multipart message.

  Parameters

    - `psResult`: pointer to the return value of CPLHTTPFetch()

char *`GOA2GetAuthorizationURL`(const char *pszScope)

  Return authorization url for a given scope.

  Returns the URL that a user should visit, and use for authentication in order to get an “auth token” indicating their willingness to use a service.

  Note that when the user visits this url they will be asked to login (using a google/gmail/etc) account, and to authorize use of the requested scope for the application “GDAL/OGR”. Once they have done so, they will be presented with a lengthy string they should “enter

  into their application”. This is the “auth token” to be passed to

  GOA2GetRefreshToken(). The “auth token” can only be used once.

  This function should never fail.

  Return

    the URL to visit - should be freed with CPLFree().

  Parameters

    - `pszScope`: the service being requested, not yet URL encoded, such as “https://www.googleapis.com/auth/fusiontables”.

char *`GOA2GetRefreshToken`(const char *pszAuthToken, const char *pszScope)

  Turn Auth Token into a Refresh Token.

  A one time “auth token” provided by the user is turned into a reusable “refresh token” using a google oauth2 web service.

  A CPLError will be reported if the translation fails for some reason. Common reasons include the auth token already having been used before, it not being appropriate for the passed scope and configured client api or http connection problems. NULL is returned on error.

  Return

    refresh token, to be freed with CPLFree(), null on failure.

  Parameters

    - `pszAuthToken`: the authorization token from the user.

    - `pszScope`: the scope for which it is valid.

char *`GOA2GetAccessToken`(const char *pszRefreshToken, const char *pszScope)

  Fetch access token using refresh token.

  The permanent refresh token is used to fetch a temporary (usually one hour) access token using Google OAuth2 web services.

  A CPLError will be reported if the request fails for some reason. Common reasons include the refresh token having been revoked by the user or http connection problems.

  Return

    access token, to be freed with CPLFree(), null on failure.

  Parameters

    - `pszRefreshToken`: the refresh token from GOA2GetRefreshToken().

    - `pszScope`: the scope for which it is valid. Currently unused

char **`GOA2GetAccessTokenFromServiceAccount`(const char *pszPrivateKey, const char *pszClientEmail, const char *pszScope, CSLConstList papszAdditionalClaims, CSLConstList papszOptions)

  Fetch access token using Service Account OAuth2.

  See https://developers.google.com/identity/protocols/OAuth2ServiceAccount

  A CPLError will be reported if the request fails for some reason.

  Return

    a list of key=value pairs, including a access_token and expires_in

  Since

    GDAL 2.3

  Parameters

    - `pszPrivateKey`: Private key as a RSA private key

    - `pszClientEmail`: Client email

    - `pszScope`: the service being requested

    - `papszAdditionalClaims`: additional claims, or NULL

    - `papszOptions`: NULL terminated list of options. None currently

char **`GOA2GetAccessTokenFromCloudEngineVM`(CSLConstList papszOptions)

  Fetch access token using Cloud Engine internal REST API.

  The default service accounts bound to the current Google Cloud Engine VM is used for OAuth2 authentication

  A CPLError will be reported if the request fails for some reason. Common reasons include the refresh token having been revoked by the user or http connection problems.

  Return

    a list of key=value pairs, including a access_token and expires_in

  Since

    GDAL 2.3

  Parameters

    - `papszOptions`: NULL terminated list of options. None currently

bool `CPLIsMachinePotentiallyGCEInstance`()

  Returns whether the current machine is potentially a Google Compute Engine instance.

  This does a very quick check without network access. To confirm if the machine is effectively a GCE instance, metadata.google.internal must be queried.

  Return

    true if the current machine is potentially a GCE instance.

  Since

    GDAL 2.3

bool `CPLIsMachineForSureGCEInstance`()

  Returns whether the current machine is surely a Google Compute Engine instance.

  This does a very quick check without network access. Note: only works for Linux GCE instances.

  Return

    true if the current machine is surely a GCE instance.

  Since

    GDAL 2.3

struct `CPLMimePart`
  #include <cpl_http.h>

  Describe a part of a multipart message

  Public Members

  char **`papszHeaders`

    NULL terminated array of headers

  GByte *`pabyData`

    Buffer with data of the part

  int `nDataLen`

    Buffer length

struct `CPLHTTPResult`
  #include <cpl_http.h>

  Describe the result of a CPLHTTPFetch() call

  Public Members

  int `nStatus`

    cURL error code : 0=success, non-zero if request failed

  char *`pszContentType`

    Content-Type of the response

  char *`pszErrBuf`

    Error message from curl, or NULL

  int `nDataLen`

    Length of the pabyData buffer

  int `nDataAlloc`

    Allocated size of the pabyData buffer

  GByte *`pabyData`

    Buffer with downloaded data

  char **`papszHeaders`

    Headers returned

  int `nMimePartCount`

    Number of parts in a multipart message

  CPLMimePart *`pasMimePart`

    Array of parts (resolved by CPLHTTPParseMultipartMime())

class `GOA2Manager`
  #include <cpl_http.h>

  Manager of Google OAuth2 authentication.

  This class handles different authentication methods and handles renewal of access token.

  Since

    GDAL 2.3

  Public Types

  enum `AuthMethod`

    Authentication method.

    Values:

    `NONE`
    `GCE`
    `ACCESS_TOKEN_FROM_REFRESH`
    `SERVICE_ACCOUNT`

  Public Functions

  `GOA2Manager`()

    Constructor.

  bool `SetAuthFromGCE`(CSLConstList papszOptions)

    Specifies that the authentication will be done using the local credentials of the current Google Compute Engine VM.

    This queries http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token

    Return

      true in case of success (no network access is done at this stage)

    Parameters

      - `papszOptions`: NULL terminated list of options.

  bool `SetAuthFromRefreshToken`(const char *pszRefreshToken, const char *pszClientId, const char *pszClientSecret, CSLConstList papszOptions)

    Specifies that the authentication will be done using the OAuth2 client id method.

    See http://code.google.com/apis/accounts/docs/OAuth2.html

    Return

      true in case of success (no network access is done at this stage)

    Parameters

      - `pszRefreshToken`: refresh token. Must be non NULL.

      - `pszClientId`: client id (may be NULL, in which case the GOA2_CLIENT_ID configuration option is used)

      - `pszClientSecret`: client secret (may be NULL, in which case the GOA2_CLIENT_SECRET configuration option is used)

      - `papszOptions`: NULL terminated list of options, or NULL.

  bool `SetAuthFromServiceAccount`(const char *pszPrivateKey, const char *pszClientEmail, const char *pszScope, CSLConstList papszAdditionalClaims, CSLConstList papszOptions)

    Specifies that the authentication will be done using the OAuth2 service account method.

    See https://developers.google.com/identity/protocols/OAuth2ServiceAccount

    Return

      true in case of success (no network access is done at this stage)

    Parameters

      - `pszPrivateKey`: RSA private key. Must be non NULL.

      - `pszClientEmail`: client email. Must be non NULL.

      - `pszScope`: authorization scope. Must be non NULL.

      - `papszAdditionalClaims`: NULL terminate list of additional claims, or NULL.

      - `papszOptions`: NULL terminated list of options, or NULL.

  AuthMethod `GetAuthMethod`() const

    Returns the authentication method.

  const char *`GetBearer`() const

    Return the access token.

    This is the value to append to a “Authorization: Bearer ” HTTP header.

    A network request is issued only if no access token has been yet queried, or if its expiration delay has been reached.

    Return

      the access token, or NULL in case of error.

  const CPLString &`GetPrivateKey`() const

    Returns private key for SERVICE_ACCOUNT method.

  const CPLString &`GetClientEmail`() const

    Returns client email for SERVICE_ACCOUNT method.

  Private Members

  CPLString `m_osCurrentBearer` = {}
  time_t `m_nExpirationTime` = 0
  AuthMethod `m_eMethod` = NONE
  CPLString `m_osClientId` = {}
  CPLString `m_osClientSecret` = {}
  CPLString `m_osRefreshToken` = {}
  CPLString `m_osPrivateKey` = {}
  CPLString `m_osClientEmail` = {}
  CPLString `m_osScope` = {}
  CPLStringList `m_aosAdditionalClaims` = {}
  CPLStringList `m_aosOptions` = {}

## cpl_minixml.h

Definitions for CPL mini XML Parser/Serializer.

Enums

enum `CPLXMLNodeType`

  XML node type.

  Values:

  `CXT_Element` = 0

    Node is an element

  `CXT_Text` = 1

    Node is a raw text value

  `CXT_Attribute` = 2

    Node is attribute

  `CXT_Comment` = 3

    Node is an XML comment.

  `CXT_Literal` = 4

    Node is a special literal

Functions

CPLXMLNode *`CPLParseXMLString`(const char *pszString)

  Parse an XML string into tree form.

  The passed document is parsed into a CPLXMLNode tree representation. If the document is not well formed XML then NULL is returned, and errors are reported via CPLError(). No validation beyond wellformedness is done. The CPLParseXMLFile() convenience function can be used to parse from a file.

  The returned document tree is owned by the caller and should be freed with CPLDestroyXMLNode() when no longer needed.

  If the document has more than one “root level” element then those after the first will be attached to the first as siblings (via the psNext pointers) even though there is no common parent. A document with no XML structure (no angle brackets for instance) would be considered well formed, and returned as a single CXT_Text node.

  Return

    parsed tree or NULL on error.

  Parameters

    - `pszString`: the document to parse.

void `CPLDestroyXMLNode`(CPLXMLNode *psNode)

  Destroy a tree.

  This function frees resources associated with a CPLXMLNode and all its children nodes.

  Parameters

    - `psNode`: the tree to free.

CPLXMLNode *`CPLGetXMLNode`(CPLXMLNode *poRoot, const char *pszPath)

  Find node by path.

  Searches the document or subdocument indicated by psRoot for an element (or attribute) with the given path. The path should consist of a set of element names separated by dots, not including the name of the root element (psRoot). If the requested element is not found NULL is returned.

  Attribute names may only appear as the last item in the path.

  The search is done from the root nodes children, but all intermediate nodes in the path must be specified. Searching for “name” would only find a name element or attribute if it is a direct child of the root, not at any level in the subdocument.

  If the pszPath is prefixed by “=” then the search will begin with the root node, and its siblings, instead of the root nodes children. This is particularly useful when searching within a whole document which is often prefixed by one or more “junk” nodes like the <?xml> declaration.

  Return

    the requested element node, or NULL if not found.

  Parameters

    - `psRoot`: the subtree in which to search. This should be a node of type CXT_Element. NULL is safe.

    - `pszPath`: the list of element names in the path (dot separated).

CPLXMLNode *`CPLSearchXMLNode`(CPLXMLNode *poRoot, const char *pszTarget)

  Search for a node in document.

  Searches the children (and potentially siblings) of the documented passed in for the named element or attribute. To search following siblings as well as children, prefix the pszElement name with an equal sign. This function does an in-order traversal of the document tree. So it will first match against the current node, then its first child, that child’s first child, and so on.

  Use CPLGetXMLNode() to find a specific child, or along a specific node path.

  Return

    The matching node or NULL on failure.

  Parameters

    - `psRoot`: the subtree to search. This should be a node of type CXT_Element. NULL is safe.

    - `pszElement`: the name of the element or attribute to search for.

const char *`CPLGetXMLValue`(const CPLXMLNode *poRoot, const char *pszPath, const char *pszDefault)

  Fetch element/attribute value.

  Searches the document for the element/attribute value associated with the path. The corresponding node is internally found with CPLGetXMLNode() (see there for details on path handling). Once found, the value is considered to be the first CXT_Text child of the node.

  If the attribute/element search fails, or if the found node has no value then the passed default value is returned.

  The returned value points to memory within the document tree, and should not be altered or freed.

  Return

    the requested value or pszDefault if not found.

  Parameters

    - `psRoot`: the subtree in which to search. This should be a node of type CXT_Element. NULL is safe.

    - `pszPath`: the list of element names in the path (dot separated). An empty path means get the value of the psRoot node.

    - `pszDefault`: the value to return if a corresponding value is not found, may be NULL.

CPLXMLNode *`CPLCreateXMLNode`(CPLXMLNode *poParent, CPLXMLNodeType eType, const char *pszText)

  Create an document tree item.

  Create a single CPLXMLNode object with the desired value and type, and attach it as a child of the indicated parent.

  Return

    the newly created node, now owned by the caller (or parent node).

  Parameters

    - `poParent`: the parent to which this node should be attached as a child. May be NULL to keep as free standing.

    - `eType`: the type of the newly created node

    - `pszText`: the value of the newly created node

char *`CPLSerializeXMLTree`(const CPLXMLNode *psNode)

  Convert tree into string document.

  This function converts a CPLXMLNode tree representation of a document into a flat string representation. White space indentation is used visually preserve the tree structure of the document. The returned document becomes owned by the caller and should be freed with CPLFree() when no longer needed.

  Return

    the document on success or NULL on failure.

  Parameters

    - `psNode`: the node to serialize.

void `CPLAddXMLChild`(CPLXMLNode *psParent, CPLXMLNode *psChild)

  Add child node to parent.

  The passed child is added to the list of children of the indicated parent. Normally the child is added at the end of the parents child list, but attributes (CXT_Attribute) will be inserted after any other attributes but before any other element type. Ownership of the child node is effectively assumed by the parent node. If the child has siblings (its psNext is not NULL) they will be trimmed, but if the child has children they are carried with it.

  Parameters

    - `psParent`: the node to attach the child to. May not be NULL.

    - `psChild`: the child to add to the parent. May not be NULL. Should not be a child of any other parent.

int `CPLRemoveXMLChild`(CPLXMLNode *psParent, CPLXMLNode *psChild)

  Remove child node from parent.

  The passed child is removed from the child list of the passed parent, but the child is not destroyed. The child retains ownership of its own children, but is cleanly removed from the child list of the parent.

  Return

    TRUE on success or FALSE if the child was not found.

  Parameters

    - `psParent`: the node to the child is attached to.

    - `psChild`: the child to remove.

void `CPLAddXMLSibling`(CPLXMLNode *psOlderSibling, CPLXMLNode *psNewSibling)

  Add new sibling.

  The passed psNewSibling is added to the end of siblings of the psOlderSibling node. That is, it is added to the end of the psNext chain. There is no special handling if psNewSibling is an attribute. If this is required, use CPLAddXMLChild().

  Parameters

    - `psOlderSibling`: the node to attach the sibling after.

    - `psNewSibling`: the node to add at the end of psOlderSiblings psNext chain.

CPLXMLNode *`CPLCreateXMLElementAndValue`(CPLXMLNode *psParent, const char *pszName, const char *pszValue)

  Create an element and text value.

  This is function is a convenient short form for:

      CPLXMLNode *psTextNode;
      CPLXMLNode *psElementNode;

      psElementNode = CPLCreateXMLNode( psParent, CXT_Element, pszName );
      psTextNode = CPLCreateXMLNode( psElementNode, CXT_Text, pszValue );

      return psElementNode;

  It creates a CXT_Element node, with a CXT_Text child, and attaches the element to the passed parent.

  Return

    the pointer to the new element node.

  Parameters

    - `psParent`: the parent node to which the resulting node should be attached. May be NULL to keep as freestanding.

    - `pszName`: the element name to create.

    - `pszValue`: the text to attach to the element. Must not be NULL.

void `CPLAddXMLAttributeAndValue`(CPLXMLNode *psParent, const char *pszName, const char *pszValue)

  Create an attribute and text value.

  This is function is a convenient short form for:

      CPLXMLNode *psAttributeNode;

      psAttributeNode = CPLCreateXMLNode( psParent, CXT_Attribute, pszName );
      CPLCreateXMLNode( psAttributeNode, CXT_Text, pszValue );

  It creates a CXT_Attribute node, with a CXT_Text child, and attaches the element to the passed parent.

  Since

    GDAL 2.0

  Parameters

    - `psParent`: the parent node to which the resulting node should be attached. Must not be NULL.

    - `pszName`: the attribute name to create.

    - `pszValue`: the text to attach to the attribute. Must not be NULL.

CPLXMLNode *`CPLCloneXMLTree`(const CPLXMLNode *psTree)

  Copy tree.

  Creates a deep copy of a CPLXMLNode tree.

  Return

    a copy of the whole tree.

  Parameters

    - `psTree`: the tree to duplicate.

int `CPLSetXMLValue`(CPLXMLNode *psRoot, const char *pszPath, const char *pszValue)

  Set element value by path.

  Find (or create) the target element or attribute specified in the path, and assign it the indicated value.

  Any path elements that do not already exist will be created. The target nodes value (the first CXT_Text child) will be replaced with the provided value.

  If the target node is an attribute instead of an element, the name should be prefixed with a #.

  Example: CPLSetXMLValue( “Citation.Id.Description”, “DOQ dataset” ); CPLSetXMLValue( “Citation.Id.Description.#name”, “doq” );

  Return

    TRUE on success.

  Parameters

    - `psRoot`: the subdocument to be updated.

    - `pszPath`: the dot separated path to the target element/attribute.

    - `pszValue`: the text value to assign.

void `CPLStripXMLNamespace`(CPLXMLNode *psRoot, const char *pszNameSpace, int bRecurse)

  Strip indicated namespaces.

  The subdocument (psRoot) is recursively examined, and any elements with the indicated namespace prefix will have the namespace prefix stripped from the element names. If the passed namespace is NULL, then all namespace prefixes will be stripped.

  Nodes other than elements should remain unaffected. The changes are made “in place”, and should not alter any node locations, only the pszValue field of affected nodes.

  Parameters

    - `psRoot`: the document to operate on.

    - `pszNamespace`: the name space prefix (not including colon), or NULL.

    - `bRecurse`: TRUE to recurse over whole document, or FALSE to only operate on the passed node.

void `CPLCleanXMLElementName`(char *pszTarget)

  Make string into safe XML token.

  Modifies a string in place to try and make it into a legal XML token that can be used as an element name. This is accomplished by changing any characters not legal in a token into an underscore.

  NOTE: This function should implement the rules in section 2.3 of http://www.w3.org/TR/xml11/ but it doesn’t yet do that properly. We only do a rough approximation of that.

  Parameters

    - `pszTarget`: the string to be adjusted. It is altered in place.

CPLXMLNode *`CPLParseXMLFile`(const char *pszFilename)

  Parse XML file into tree.

  The named file is opened, loaded into memory as a big string, and parsed with CPLParseXMLString(). Errors in reading the file or parsing the XML will be reported by CPLError().

  The “large file” API is used, so XML files can come from virtualized files.

  Return

    NULL on failure, or the document tree on success.

  Parameters

    - `pszFilename`: the file to open.

int `CPLSerializeXMLTreeToFile`(const CPLXMLNode *psTree, const char *pszFilename)

  Write document tree to a file.

  The passed document tree is converted into one big string (with CPLSerializeXMLTree()) and then written to the named file. Errors writing the file will be reported by CPLError(). The source document tree is not altered. If the output file already exists it will be overwritten.

  Return

    TRUE on success, FALSE otherwise.

  Parameters

    - `psTree`: the document tree to write.

    - `pszFilename`: the name of the file to write to.

struct `CPLXMLNode`
  #include <cpl_minixml.h>

  Document node structure.

  This C structure is used to hold a single text fragment representing a component of the document when parsed. It should be allocated with the appropriate CPL function, and freed with CPLDestroyXMLNode(). The structure contents should not normally be altered by application code, but may be freely examined by application code.

  Using the psChild and psNext pointers, a hierarchical tree structure for a document can be represented as a tree of CPLXMLNode structures.

  Public Members

  CPLXMLNodeType `eType`

    Node type.

    One of CXT_Element, CXT_Text, CXT_Attribute, CXT_Comment, or CXT_Literal.

  char *`pszValue`

    Node value.

    For CXT_Element this is the name of the element, without the angle brackets. Note there is a single CXT_Element even when the document contains a start and end element tag. The node represents the pair. All text or other elements between the start and end tag will appear as children nodes of this CXT_Element node.

    For CXT_Attribute the pszValue is the attribute name. The value of the attribute will be a CXT_Text child.

    For CXT_Text this is the text itself (value of an attribute, or a text fragment between an element start and end tags.

    For CXT_Literal it is all the literal text. Currently this is just used for !DOCTYPE lines, and the value would be the entire line.

    For CXT_Comment the value is all the literal text within the comment, but not including the comment start/end indicators (“<–” and “–>”).

  struct CPLXMLNode *`psNext`

    Next sibling.

    Pointer to next sibling, that is the next node appearing after this one that has the same parent as this node. NULL if this node is the last child of the parent element.

  struct CPLXMLNode *`psChild`

    Child node.

    Pointer to first child node, if any. Only CXT_Element and CXT_Attribute nodes should have children. For CXT_Attribute it should be a single CXT_Text value node, while CXT_Element can have any kind of child. The full list of children for a node are identified by walking the psNext’s starting with the psChild node.

class `CPLXMLTreeCloser` : public std::unique_ptr<CPLXMLNode, CPLXMLTreeCloserDeleter>
  #include <cpl_minixml.h>

  Manage a tree of XML nodes so that all nodes are freed when the instance goes out of scope.

  Only the top level node should be in a CPLXMLTreeCloser.

  Public Functions

  `CPLXMLTreeCloser`(CPLXMLNode *data)

    Constructor.

  CPLXMLNode *`getDocumentElement`()

    Returns a pointer to the document (root) element.

    Return

      the node pointer

## cpl_multiproc.h

Defines

`CPLMutex`

`CPLCond`

`CPLJoinableThread`

`CPL_MUTEX_RECURSIVE`

`CPL_MUTEX_ADAPTIVE`

`CPL_MUTEX_REGULAR`

`CPLMutexHolderD`(x)

`CPLMutexHolderExD`(x, nOptions)

`CPLMutexHolderOptionalLockD`(x)

`CPLLockHolderD`(x, eType)

`CPLLockHolderOptionalLockD`(x)

`CTLS_RLBUFFERINFO`

`CTLS_WIN32_COND`

`CTLS_CSVTABLEPTR`

`CTLS_CSVDEFAULTFILENAME`

`CTLS_ERRORCONTEXT`

`CTLS_VSICURL_CACHEDCONNECTION`

`CTLS_PATHBUF`

`CTLS_ABSTRACTARCHIVE_SPLIT`

`CTLS_GDALOPEN_ANTIRECURSION`

`CTLS_CPLSPRINTF`

`CTLS_RESPONSIBLEPID`

`CTLS_VERSIONINFO`

`CTLS_VERSIONINFO_LICENCE`

`CTLS_CONFIGOPTIONS`

`CTLS_FINDFILE`

`CTLS_VSIERRORCONTEXT`

`CTLS_ERRORHANDLERACTIVEDATA`

`CTLS_PROJCONTEXTHOLDER`

`CTLS_GDALDEFAULTOVR_ANTIREC`

`CTLS_MAX`

Typedefs

typedef void (*`CPLThreadFunc`)(void *)

typedef struct _CPLLock `CPLLock`

typedef void (*`CPLTLSFreeFunc`)(void *pData)

Enums

enum `CPLCondTimedWaitReason`

  Values:

  `COND_TIMED_WAIT_COND`
  `COND_TIMED_WAIT_TIME_OUT`
  `COND_TIMED_WAIT_OTHER`

enum `CPLLockType`

  Values:

  `LOCK_RECURSIVE_MUTEX`
  `LOCK_ADAPTIVE_MUTEX`
  `LOCK_SPIN`

Functions

void *`CPLLockFile`(const char *pszPath, double dfWaitInSeconds)

void `CPLUnlockFile`(void *hLock)

CPLMutex *`CPLCreateMutex`(void)

CPLMutex *`CPLCreateMutexEx`(int nOptions)

int `CPLCreateOrAcquireMutex`(CPLMutex **, double dfWaitInSeconds)

int `CPLCreateOrAcquireMutexEx`(CPLMutex **, double dfWaitInSeconds, int nOptions)

int `CPLAcquireMutex`(CPLMutex *hMutex, double dfWaitInSeconds)

void `CPLReleaseMutex`(CPLMutex *hMutex)

void `CPLDestroyMutex`(CPLMutex *hMutex)

void `CPLCleanupMasterMutex`(void)

CPLCond *`CPLCreateCond`(void)

void `CPLCondWait`(CPLCond *hCond, CPLMutex *hMutex)

CPLCondTimedWaitReason `CPLCondTimedWait`(CPLCond *hCond, CPLMutex *hMutex, double dfWaitInSeconds)

void `CPLCondSignal`(CPLCond *hCond)

void `CPLCondBroadcast`(CPLCond *hCond)

void `CPLDestroyCond`(CPLCond *hCond)

GIntBig `CPLGetPID`(void)

  Contrary to what its name suggests, CPLGetPID() actually returns the thread id.

int `CPLGetCurrentProcessID`(void)

int `CPLCreateThread`(CPLThreadFunc pfnMain, void *pArg)

CPLJoinableThread *`CPLCreateJoinableThread`(CPLThreadFunc pfnMain, void *pArg)

void `CPLJoinThread`(CPLJoinableThread *hJoinableThread)

void `CPLSleep`(double dfWaitInSeconds)

const char *`CPLGetThreadingModel`(void)

int `CPLGetNumCPUs`(void)

CPLLock *`CPLCreateLock`(CPLLockType eType)

int `CPLCreateOrAcquireLock`(CPLLock **, CPLLockType eType)

int `CPLAcquireLock`(CPLLock *)

void `CPLReleaseLock`(CPLLock *)

void `CPLDestroyLock`(CPLLock *)

void `CPLLockSetDebugPerf`(CPLLock *, int bEnableIn)

void *`CPLGetTLS`(int nIndex)

void *`CPLGetTLSEx`(int nIndex, int *pbMemoryErrorOccurred)

void `CPLSetTLS`(int nIndex, void *pData, int bFreeOnExit)

void `CPLSetTLSWithFreeFunc`(int nIndex, void *pData, CPLTLSFreeFunc pfnFree)

void `CPLSetTLSWithFreeFuncEx`(int nIndex, void *pData, CPLTLSFreeFunc pfnFree, int *pbMemoryErrorOccurred)

void `CPLCleanupTLS`(void)

class `CPLMutexHolder`
  #include <cpl_multiproc.h>

  Object to hold a mutex.

  Public Functions

  `CPLMutexHolder`(CPLMutex **phMutex, double dfWaitInSeconds = 1000.0, const char *pszFile = __FILE__, int nLine = __LINE__, int nOptions = CPL_MUTEX_RECURSIVE)

    Instantiates the mutex if not already done.

  `CPLMutexHolder`(CPLMutex *hMutex, double dfWaitInSeconds = 1000.0, const char *pszFile = __FILE__, int nLine = __LINE__)

    This variant assumes the mutex has already been created.

    If not, it will be a no-op

  `~CPLMutexHolder`()

  Private Members

  CPLMutex *`hMutex` = nullptr
  const char *`pszFile` = nullptr
  int `nLine` = 0

class `CPLLockHolder`
  #include <cpl_multiproc.h>

  Object to hold a lock.

  Public Functions

  `CPLLockHolder`(CPLLock **phSpin, CPLLockType eType, const char *pszFile = __FILE__, int nLine = __LINE__)

    Instantiates the lock if not already done.

  `CPLLockHolder`(CPLLock *hSpin, const char *pszFile = __FILE__, int nLine = __LINE__)

    This variant assumes the lock has already been created.

    If not, it will be a no-op

  `~CPLLockHolder`()

  Private Members

  CPLLock *`hLock` = nullptr
  const char *`pszFile` = nullptr
  int `nLine` = 0

## cpl_odbc.h

ODBC Abstraction Layer (C++).

class `CPLODBCDriverInstaller`
  #include <cpl_odbc.h>

  A class providing functions to install or remove ODBC driver.

  Public Functions

  `CPLODBCDriverInstaller`()
  int `InstallDriver`(const char *pszDriver, const char *pszPathIn, WORD fRequest = ODBC_INSTALL_COMPLETE)

    Installs ODBC driver or updates definition of already installed driver.

    Interanally, it calls ODBC’s SQLInstallDriverEx function.

    Return

      TRUE indicates success, FALSE if it fails.

    Parameters

      - `pszDriver`: - The driver definition as a list of keyword-value pairs describing the driver (See ODBC API Reference).

      - `pszPathIn`: - Full path of the target directory of the installation, or a null pointer (for unixODBC, NULL is passed).

      - `fRequest`: - The fRequest argument must contain one of the following values: ODBC_INSTALL_COMPLETE - (default) complete the installation request ODBC_INSTALL_INQUIRY - inquire about where a driver can be installed

  int `RemoveDriver`(const char *pszDriverName, int fRemoveDSN = FALSE)

    Removes or changes information about the driver from the Odbcinst.ini entry in the system information.

    Return

      The function returns TRUE if it is successful, FALSE if it fails. If no entry exists in the system information when this function is called, the function returns FALSE. In order to obtain usage count value, call GetUsageCount().

    Parameters

      - `pszDriverName`: - The name of the driver as registered in the Odbcinst.ini key of the system information.

      - `fRemoveDSN`: - TRUE: Remove DSNs associated with the driver specified in lpszDriver. FALSE: Do not remove DSNs associated with the driver specified in lpszDriver.

  int `GetUsageCount`() const

    The usage count of the driver after this function has been called.

  const char *`GetPathOut`() const

    Path of the target directory where the driver should be installed.

    For details, see ODBC API Reference and lpszPathOut parameter of SQLInstallDriverEx

  const char *`GetLastError`() const

    If InstallDriver returns FALSE, then GetLastError then error message can be obtained by calling this function.

    Internally, it calls ODBC’s SQLInstallerError function.

  DWORD `GetLastErrorCode`() const

    If InstallDriver returns FALSE, then GetLastErrorCode then error code can be obtained by calling this function.

    Internally, it calls ODBC’s SQLInstallerError function. See ODBC API Reference for possible error flags.

  Private Members

  char `m_szPathOut`[`ODBC_FILENAME_MAX`]
  char `m_szError`[`SQL_MAX_MESSAGE_LENGTH`]
  DWORD `m_nErrorCode`
  DWORD `m_nUsageCount`

class `CPLODBCSession`
  #include <cpl_odbc.h>

  A class representing an ODBC database session.

  Includes error collection services.

  Public Functions

  `CPLODBCSession`()

    Constructor.

  `~CPLODBCSession`()

    Destructor.

  int `EstablishSession`(const char *pszDSN, const char *pszUserid, const char *pszPassword)

    Connect to database and logon.

    Return

      TRUE on success or FALSE on failure. Call GetLastError() to get details on failure.

    Parameters

      - `pszDSN`: The name of the DSN being used to connect. This is not optional.

      - `pszUserid`: the userid to logon as, may be NULL if not not required, or provided by the DSN.

      - `pszPassword`: the password to logon with. May be NULL if not required or provided by the DSN.

  const char *`GetLastError`()

    Returns the last ODBC error message.

    Return

      pointer to an internal buffer with the error message in it. Do not free or alter. Will be an empty (but not NULL) string if there is no pending error info.

  int `ClearTransaction`()

    Clear transaction.

  int `BeginTransaction`()

    Begin transaction.

  int `CommitTransaction`()

    Commit transaction.

  int `RollbackTransaction`()

    Rollback transaction.

  int `IsInTransaction`()

    Returns whether a transaction is active.

  int `CloseSession`()

    Close session.

  int `Failed`(int nRetCode, HSTMT hStmt = nullptr)

    Test if a return code indicates failure, return TRUE if that is the case.

    Also update error text.

    ODBC error messages are reported in the following format: [SQLState]ErrorMessage(NativeErrorCode)

    Multiple error messages are delimeted by “,”.

  HDBC `GetConnection`()

    Return connection handle.

  HENV `GetEnvironment`()

    Return GetEnvironment handle.

  Private Members

  CPLString `m_osLastError` = {}
  HENV `m_hEnv` = nullptr
  HDBC `m_hDBC` = nullptr
  int `m_bInTransaction` = false
  int `m_bAutoCommit` = true

class `CPLODBCStatement`
  #include <cpl_odbc.h>

  Abstraction for statement, and resultset.

  Includes methods for executing an SQL statement, and for accessing the resultset from that statement. Also provides for executing other ODBC requests that produce results sets such as SQLColumns() and SQLTables() requests.

  Public Functions

  `CPLODBCStatement`(CPLODBCSession *poSession)

    Constructor.

  `~CPLODBCStatement`()

    Destructor.

  HSTMT `GetStatement`()

    Return statement handle.

  void `Clear`()

    Clear internal command text and result set definitions.

  void `AppendEscaped`(const char *pszText)

    Append text to internal command.

    The passed text is appended to the internal SQL command text after escaping any special characters so it can be used as a character string in an SQL statement.

    Parameters

      - `pszText`: text to append.

  void `Append`(const char *pszText)

    Append text to internal command.

    The passed text is appended to the internal SQL command text.

    Parameters

      - `pszText`: text to append.

  void `Append`(int nValue)

    Append to internal command.

    The passed value is formatted and appended to the internal SQL command text.

    Parameters

      - `nValue`: value to append to the command.

  void `Append`(double dfValue)

    Append to internal command.

    The passed value is formatted and appended to the internal SQL command text.

    Parameters

      - `dfValue`: value to append to the command.

  int `Appendf`(const char *pszFormat, ...)

    Append to internal command.

    The passed format is used to format other arguments and the result is appended to the internal command text. Long results may not be formatted properly, and should be appended with the direct Append() methods.

    Return

      FALSE if formatting fails due to result being too large.

    Parameters

      - `pszFormat`: printf() style format string.

  const char *`GetCommand`()

    Return statement string.

  int `ExecuteSQL`(const char *pszStatement = nullptr)

    Execute an SQL statement.

    This method will execute the passed (or stored) SQL statement, and initialize information about the resultset if there is one. If a NULL statement is passed, the internal stored statement that has been previously set via Append() or Appendf() calls will be used.

    Return

      TRUE on success or FALSE if there is an error. Error details can be fetched with OGRODBCSession::GetLastError().

    Parameters

      - `pszStatement`: the SQL statement to execute, or NULL if the internally saved one should be used.

  int `Fetch`(int nOrientation = SQL_FETCH_NEXT, int nOffset = 0)

    Fetch a new record.

    Requests the next row in the current resultset using the SQLFetchScroll() call. Note that many ODBC drivers only support the default forward fetching one record at a time. Only SQL_FETCH_NEXT (the default) should be considered reliable on all drivers.

    Currently it isn’t clear how to determine whether an error or a normal out of data condition has occurred if Fetch() fails.

    Return

      TRUE if a new row is successfully fetched, or FALSE if not.

    Parameters

      - `nOrientation`: One of SQL_FETCH_NEXT, SQL_FETCH_LAST, SQL_FETCH_PRIOR, SQL_FETCH_ABSOLUTE, or SQL_FETCH_RELATIVE (default is SQL_FETCH_NEXT).

      - `nOffset`: the offset (number of records), ignored for some orientations.

  void `ClearColumnData`()

    ClearColumnData.

  int `GetColCount`()

    Fetch the resultset column count.

    Return

      the column count, or zero if there is no resultset.

  const char *`GetColName`(int iCol)

    Fetch a column name.

    Return

      NULL on failure (out of bounds column), or a pointer to an internal copy of the column name.

    Parameters

      - `iCol`: the zero based column index.

  short `GetColType`(int iCol)

    Fetch a column data type.

    The return type code is a an ODBC SQL_ code, one of SQL_UNKNOWN_TYPE, SQL_CHAR, SQL_NUMERIC, SQL_DECIMAL, SQL_INTEGER, SQL_SMALLINT, SQL_FLOAT, SQL_REAL, SQL_DOUBLE, SQL_DATETIME, SQL_VARCHAR, SQL_TYPE_DATE, SQL_TYPE_TIME, SQL_TYPE_TIMESTAMPT.

    Return

      type code or -1 if the column is illegal.

    Parameters

      - `iCol`: the zero based column index.

  const char *`GetColTypeName`(int iCol)

    Fetch a column data type name.

    Returns data source-dependent data type name; for example, “CHAR”, “VARCHAR”, “MONEY”, “LONG VARBINAR”, or “CHAR ( ) FOR BIT DATA”.

    Return

      NULL on failure (out of bounds column), or a pointer to an internal copy of the column dat type name.

    Parameters

      - `iCol`: the zero based column index.

  short `GetColSize`(int iCol)

    Fetch the column width.

    Return

      column width, zero for unknown width columns.

    Parameters

      - `iCol`: the zero based column index.

  short `GetColPrecision`(int iCol)

    Fetch the column precision.

    Return

      column precision, may be zero or the same as column size for columns to which it does not apply.

    Parameters

      - `iCol`: the zero based column index.

  short `GetColNullable`(int iCol)

    Fetch the column nullability.

    Return

      TRUE if the column may contains or FALSE otherwise.

    Parameters

      - `iCol`: the zero based column index.

  const char *`GetColColumnDef`(int iCol)

    Fetch a column default value.

    Returns the default value of a column.

    Return

      NULL if the default value is not dpecified or the internal copy of the default value.

    Parameters

      - `iCol`: the zero based column index.

  int `GetColId`(const char *pszColName)

    Fetch column index.

    Gets the column index corresponding with the passed name. The name comparisons are case insensitive.

    Return

      the column index, or -1 if not found.

    Parameters

      - `pszColName`: the name to search for.

  const char *`GetColData`(int iCol, const char *pszDefault = nullptr)

    Fetch column data.

    Fetches the data contents of the requested column for the currently loaded row. The result is returned as a string regardless of the column type. NULL is returned if an illegal column is given, or if the actual column is “NULL”.

    Return

      pointer to internal column data or NULL on failure.

    Parameters

      - `iCol`: the zero based column to fetch.

      - `pszDefault`: the value to return if the column does not exist, or is NULL. Defaults to NULL.

  const char *`GetColData`(const char *pszColName, const char *pszDefault = nullptr)

    Fetch column data.

    Fetches the data contents of the requested column for the currently loaded row. The result is returned as a string regardless of the column type. NULL is returned if an illegal column is given, or if the actual column is “NULL”.

    Return

      pointer to internal column data or NULL on failure.

    Parameters

      - `pszColName`: the name of the column requested.

      - `pszDefault`: the value to return if the column does not exist, or is NULL. Defaults to NULL.

  int `GetColDataLength`(int iCol)

    GetColDataLength.

  int `GetRowCountAffected`()

    GetRowCountAffected.

  int `GetColumns`(const char *pszTable, const char *pszCatalog = nullptr, const char *pszSchema = nullptr)

    Fetch column definitions for a table.

    The SQLColumn() method is used to fetch the definitions for the columns of a table (or other queryable object such as a view). The column definitions are digested and used to populate the CPLODBCStatement column definitions essentially as if a “SELECT * FROM tablename” had been done; however, no resultset will be available.

    Return

      TRUE on success or FALSE on failure.

    Parameters

      - `pszTable`: the name of the table to query information on. This should not be empty.

      - `pszCatalog`: the catalog to find the table in, use NULL (the default) if no catalog is available.

      - `pszSchema`: the schema to find the table in, use NULL (the default) if no schema is available.

  int `GetPrimaryKeys`(const char *pszTable, const char *pszCatalog = nullptr, const char *pszSchema = nullptr)

    Fetch primary keys for a table.

    The SQLPrimaryKeys() function is used to fetch a list of fields forming the primary key. The result is returned as a result set matching the SQLPrimaryKeys() function result set. The 4th column in the result set is the column name of the key, and if the result set contains only one record then that single field will be the complete primary key.

    Return

      TRUE on success or FALSE on failure.

    Parameters

      - `pszTable`: the name of the table to query information on. This should not be empty.

      - `pszCatalog`: the catalog to find the table in, use NULL (the default) if no catalog is available.

      - `pszSchema`: the schema to find the table in, use NULL (the default) if no schema is available.

  int `GetTables`(const char *pszCatalog = nullptr, const char *pszSchema = nullptr)

    Fetch tables in database.

    The SQLTables() function is used to fetch a list tables in the database. The result is returned as a result set matching the SQLTables() function result set. The 3rd column in the result set is the table name. Only tables of type “TABLE” are returned.

    Return

      TRUE on success or FALSE on failure.

    Parameters

      - `pszCatalog`: the catalog to find the table in, use NULL (the default) if no catalog is available.

      - `pszSchema`: the schema to find the table in, use NULL (the default) if no schema is available.

  void `DumpResult`(FILE *fp, int bShowSchema = FALSE)

    Dump resultset to file.

    The contents of the current resultset are dumped in a simply formatted form to the provided file. If requested, the schema definition will be written first.

    Parameters

      - `fp`: the file to write to. stdout or stderr are acceptable.

      - `bShowSchema`: TRUE to force writing schema information for the rowset before the rowset data itself. Default is FALSE.

  int `CollectResultsInfo`()

    CollectResultsInfo.

  Public Static Functions

  CPLString `GetTypeName`(int nTypeCode)

    Get name for SQL column type.

    Returns a string name for the indicated type code (as returned from CPLODBCStatement::GetColType()).

    Return

      internal string, “UNKNOWN” if code not recognised.

    Parameters

      - `nTypeCode`: the SQL_ code, such as SQL_CHAR.

  SQLSMALLINT `GetTypeMapping`(SQLSMALLINT nTypeCode)

    Get appropriate C data type for SQL column type.

    Returns a C data type code, corresponding to the indicated SQL data type code (as returned from CPLODBCStatement::GetColType()).

    Return

      data type code. The valid code is always returned. If SQL code is not recognised, SQL_C_BINARY will be returned.

    Parameters

      - `nTypeCode`: the SQL_ code, such as SQL_CHAR.

  Private Functions

  int `Failed`(int nResultCode)

    Failed.

  Private Members

  CPLODBCSession *`m_poSession` = nullptr
  HSTMT `m_hStmt` = nullptr
  SQLSMALLINT `m_nColCount` = 0
  char **`m_papszColNames` = nullptr
  SQLSMALLINT *`m_panColType` = nullptr
  char **`m_papszColTypeNames` = nullptr
  CPL_SQLULEN *`m_panColSize` = nullptr
  SQLSMALLINT *`m_panColPrecision` = nullptr
  SQLSMALLINT *`m_panColNullable` = nullptr
  char **`m_papszColColumnDef` = nullptr
  char **`m_papszColValues` = nullptr
  CPL_SQLLEN *`m_panColValueLengths` = nullptr
  char *`m_pszStatement` = nullptr
  size_t `m_nStatementMax` = 0
  size_t `m_nStatementLen` = 0

## cpl_port.h

Core portability definitions for CPL.

Defines

`GINTBIG_MIN`

  Minimum GIntBig value.

`GINTBIG_MAX`

  Maximum GIntBig value.

`GUINTBIG_MAX`

  Maximum GUIntBig value.

`GINT64_MIN`

  Minimum GInt64 value.

`GINT64_MAX`

  Maximum GInt64 value.

`GUINT64_MAX`

  Minimum GUInt64 value.

`CPL_FRMT_GB_WITHOUT_PREFIX`

  Printf formatting suffix for GIntBig.

`CPL_FRMT_GIB`

  Printf formatting for GIntBig.

`CPL_FRMT_GUIB`

  Printf formatting for GUIntBig.

`CPL_C_START`

  Macro to start a block of C symbols.

`CPL_C_END`

  Macro to end a block of C symbols.

`MIN`(a, b)

  Macro to compute the minimum of 2 values.

`MAX`(a, b)

  Macro to compute the maximum of 2 values.

`ABS`(x)

  Macro to compute the absolute value.

`M_PI`

  PI definition.

`STRCASECMP`(a, b)

  Alias for strcasecmp()

`STRNCASECMP`(a, b, n)

  Alias for strncasecmp()

`EQUALN`(a, b, n)

  Alias for strncasecmp() == 0.

`EQUAL`(a, b)

  Alias for strcasecmp() == 0.

`STARTS_WITH`(a, b)

  Returns whether a starts with b.

`STARTS_WITH_CI`(a, b)

  Returns whether a starts with b (case insensitive comparison)

`CPL_SWAP16`(x)

  Byte-swap a 16bit unsigned integer.

`CPL_SWAP32`(x)

  Byte-swap a 32bit unsigned integer.

`CPL_SWAP64`(x)

  Byte-swap a 64bit unsigned integer.

`CPL_SWAP16PTR`(x)

  Byte-swap a 16 bit pointer.

`CPL_SWAP32PTR`(x)

  Byte-swap a 32 bit pointer.

`CPL_SWAP64PTR`(x)

  Byte-swap a 64 bit pointer.

`CPL_SWAPDOUBLE`(p)

  Byte-swap a 64 bit pointer.

`CPL_LSBWORD16`(x)

  Return a 16bit word from a originally LSB ordered word.

`CPL_MSBWORD16`(x)

  Return a 16bit word from a originally MSB ordered word.

`CPL_LSBWORD32`(x)

  Return a 32bit word from a originally LSB ordered word.

`CPL_MSBWORD32`(x)

  Return a 32bit word from a originally MSB ordered word.

`CPL_LSBPTR16`(x)

  Byte-swap if necessary a 16bit word at the location pointed from a originally LSB ordered pointer.

`CPL_MSBPTR16`(x)

  Byte-swap if necessary a 16bit word at the location pointed from a originally MSB ordered pointer.

`CPL_LSBPTR32`(x)

  Byte-swap if necessary a 32bit word at the location pointed from a originally LSB ordered pointer.

`CPL_MSBPTR32`(x)

  Byte-swap if necessary a 32bit word at the location pointed from a originally MSB ordered pointer.

`CPL_LSBPTR64`(x)

  Byte-swap if necessary a 64bit word at the location pointed from a originally LSB ordered pointer.

`CPL_MSBPTR64`(x)

  Byte-swap if necessary a 64bit word at the location pointed from a originally MSB ordered pointer.

`CPL_LSBINT16PTR`(x)

  Return a Int16 from the 2 bytes ordered in LSB order at address x.

`CPL_LSBINT32PTR`(x)

  Return a Int32 from the 4 bytes ordered in LSB order at address x.

`CPL_LSBSINT16PTR`(x)

  Return a signed Int16 from the 2 bytes ordered in LSB order at address x.

`CPL_LSBUINT16PTR`(x)

  Return a unsigned Int16 from the 2 bytes ordered in LSB order at address x.

`CPL_LSBSINT32PTR`(x)

  Return a signed Int32 from the 4 bytes ordered in LSB order at address x.

`CPL_LSBUINT32PTR`(x)

  Return a unsigned Int32 from the 4 bytes ordered in LSB order at address x.

`CPL_NULL_TERMINATED`

  Null terminated variadic.

`CPL_PRINT_FUNC_FORMAT`(format_idx, arg_idx)

  Tag a function to have printf() formatting.

`CPL_SCAN_FUNC_FORMAT`(format_idx, arg_idx)

  Tag a function to have scanf() formatting.

`CPL_FORMAT_STRING`(arg)

  Macro into which to wrap the format argument of a printf-like function.

`CPL_SCANF_FORMAT_STRING`(arg)

  Macro into which to wrap the format argument of a sscanf-like function.

`CPL_WARN_UNUSED_RESULT`

  Qualifier to warn when the return value of a function is not used.

`CPL_UNUSED`

  Qualifier for an argument that is unused.

`CPL_NO_RETURN`

  Qualifier for a function that does not return at all (terminates the process)

`CPL_RETURNS_NONNULL`

  Qualifier for a function that does not return NULL.

`CPL_RESTRICT`

  restrict keyword to declare that pointers do not alias

`CPL_OVERRIDE`

  To be used in public headers only.

  For non-public headers or .cpp files, use override directly.

`CPL_FINAL`

  C++11 final qualifier.

`CPL_NON_FINAL`

  Mark that a class is explicitly recognized as non-final.

`CPL_DISALLOW_COPY_ASSIGN`(ClassName)

  Helper to remove the copy and assignment constructors so that the compiler will not generate the default versions.

  Must be placed in the private section of a class and should be at the end.

`CPL_ARRAYSIZE`(array)

  Returns the size of C style arrays.

`CPL_FALLTHROUGH`

  Macro for fallthrough in a switch case construct.

Typedefs

typedef int `GInt32`

  Int32 type.

typedef unsigned int `GUInt32`

  Unsigned int32 type.

typedef short `GInt16`

  Int16 type.

typedef unsigned short `GUInt16`

  Unsigned int16 type.

typedef unsigned char `GByte`

  Unsigned byte type.

typedef int `GBool`

  Type for boolean values (alias to int)

typedef long long `GIntBig`

  Large signed integer type (generally 64-bit integer type).

  Use GInt64 when exactly 64 bit is needed

typedef unsigned long long `GUIntBig`

  Large unsigned integer type (generally 64-bit unsigned integer type).

  Use GUInt64 when exactly 64 bit is needed

typedef GIntBig `GInt64`

  Signed 64 bit integer type.

typedef GUIntBig `GUInt64`

  Unsigned 64 bit integer type.

typedef GIntBig `GPtrDiff_t`

  Integer type large enough to hold the difference between 2 addresses.

typedef char **`CSLConstList`

  Type of a constant null-terminated list of nul terminated strings.

  Seen as char** from C and const char* const* from C++

Functions

static int `CPLIsNan`(float f)

static int `CPLIsNan`(double f)

static int `CPLIsInf`(float f)

static int `CPLIsInf`(double f)

static int `CPLIsFinite`(float f)

static int `CPLIsFinite`(double f)

template<class `T`>
static void `CPL_IGNORE_RET_VAL`(T)

static bool `CPL_TO_BOOL`(int x)

## cpl_progress.h

Typedefs

typedef int (*`GDALProgressFunc`)(double dfComplete, const char *pszMessage, void *pProgressArg)

Functions

int `GDALDummyProgress`(double, const char *, void *)

  Stub progress function.

  This is a stub (does nothing) implementation of the GDALProgressFunc() semantics. It is primarily useful for passing to functions that take a GDALProgressFunc() argument but for which the application does not want to use one of the other progress functions that actually do something.

int `GDALTermProgress`(double dfComplete, const char *pszMessage, void *pProgressArg)

  Simple progress report to terminal.

  This progress reporter prints simple progress report to the terminal window. The progress report generally looks something like this:

      0...10...20...30...40...50...60...70...80...90...100 - done.

  Every 2.5% of progress another number or period is emitted. Note that GDALTermProgress() uses internal static data to keep track of the last percentage reported and will get confused if two terminal based progress reportings are active at the same time.

  The GDALTermProgress() function maintains an internal memory of the last percentage complete reported in a static variable, and this makes it unsuitable to have multiple GDALTermProgress()’s active either in a single thread or across multiple threads.

  Return

    Always returns TRUE indicating the process should continue.

  Parameters

    - `dfComplete`: completion ratio from 0.0 to 1.0.

    - `pszMessage`: optional message.

    - `pProgressArg`: ignored callback data argument.

int `GDALScaledProgress`(double dfComplete, const char *pszMessage, void *pData)

  Scaled progress transformer.

  This is the progress function that should be passed along with the callback data returned by GDALCreateScaledProgress().

void *`GDALCreateScaledProgress`(double dfMin, double dfMax, GDALProgressFunc pfnProgress, void *pData)

  Create scaled progress transformer.

  Sometimes when an operations wants to report progress it actually invokes several subprocesses which also take GDALProgressFunc()s, and it is desirable to map the progress of each sub operation into a portion of 0.0 to 1.0 progress of the overall process. The scaled progress function can be used for this.

  For each subsection a scaled progress function is created and instead of passing the overall progress func down to the sub functions, the GDALScaledProgress() function is passed instead.

  Example:

  Return

    pointer to pass as pProgressArg to sub functions. Should be freed with GDALDestroyScaledProgress().

  Parameters

    - `dfMin`: the value to which 0.0 in the sub operation is mapped.

    - `dfMax`: the value to which 1.0 is the sub operation is mapped.

    - `pfnProgress`: the overall progress function.

    - `pData`: the overall progress function callback data.

      int MyOperation( ..., GDALProgressFunc pfnProgress, void *pProgressData );

      {
          void *pScaledProgress;

          pScaledProgress = GDALCreateScaledProgress( 0.0, 0.5, pfnProgress,
                                                      pProgressData );
          GDALDoLongSlowOperation( ..., GDALScaledProgress, pScaledProgress );
          GDALDestroyScaledProgress( pScaledProgress );

          pScaledProgress = GDALCreateScaledProgress( 0.5, 1.0, pfnProgress,
                                                      pProgressData );
          GDALDoAnotherOperation( ..., GDALScaledProgress, pScaledProgress );
          GDALDestroyScaledProgress( pScaledProgress );

          return ...;
      }

void `GDALDestroyScaledProgress`(void *pData)

  Cleanup scaled progress handle.

  This function cleans up the data associated with a scaled progress function as returned by GADLCreateScaledProgress().

  Parameters

    - `pData`: scaled progress handle returned by GDALCreateScaledProgress().

## cpl_string.h

Various convenience functions for working with strings and string lists.

A StringList is just an array of strings with the last pointer being NULL. An empty StringList may be either a NULL pointer, or a pointer to a pointer memory location with a NULL value.

A common convention for StringLists is to use them to store name/value lists. In this case the contents are treated like a dictionary of name/value pairs. The actual data is formatted with each string having the format “<name>:<value>” (though “=” is also an acceptable separator). A number of the functions in the file operate on name/value style string lists (such as CSLSetNameValue(), and CSLFetchNameValue()).

To some extent the CPLStringList C++ class can be used to abstract managing string lists a bit but still be able to return them from C functions.

Defines

`CSLT_HONOURSTRINGS`

  Flag for CSLTokenizeString2() to honour strings.

`CSLT_ALLOWEMPTYTOKENS`

  Flag for CSLTokenizeString2() to allow empty tokens.

`CSLT_PRESERVEQUOTES`

  Flag for CSLTokenizeString2() to preserve quotes.

`CSLT_PRESERVEESCAPES`

  Flag for CSLTokenizeString2() to preserve escape characters.

`CSLT_STRIPLEADSPACES`

  Flag for CSLTokenizeString2() to strip leading spaces.

`CSLT_STRIPENDSPACES`

  Flag for CSLTokenizeString2() to strip trailaing spaces.

`CPLES_BackslashQuotable`

  Scheme for CPLEscapeString()/CPLUnescapeString() for backlash quoting.

`CPLES_XML`

  Scheme for CPLEscapeString()/CPLUnescapeString() for XML.

`CPLES_URL`

  Scheme for CPLEscapeString()/CPLUnescapeString() for URL.

`CPLES_SQL`

  Scheme for CPLEscapeString()/CPLUnescapeString() for SQL.

`CPLES_CSV`

  Scheme for CPLEscapeString()/CPLUnescapeString() for CSV.

`CPLES_XML_BUT_QUOTES`

  Scheme for CPLEscapeString()/CPLUnescapeString() for XML (preserves quotes)

`CPLES_CSV_FORCE_QUOTING`

  Scheme for CPLEscapeString()/CPLUnescapeString() for CSV (forced quoting)

`CPLES_SQLI`

  Scheme for CPLEscapeString()/CPLUnescapeString() for SQL identifiers.

`CPL_ENC_LOCALE`

  Encoding of the current locale.

`CPL_ENC_UTF8`

  UTF-8 encoding.

`CPL_ENC_UTF16`

  UTF-16 encoding.

`CPL_ENC_UCS2`

  UCS-2 encoding.

`CPL_ENC_UCS4`

  UCS-4 encoding.

`CPL_ENC_ASCII`

  ASCII encoding.

`CPL_ENC_ISO8859_1`

  ISO-8859-1 (LATIN1) encoding.

Enums

enum `CPLValueType`

  Type of value.

  Values:

  `CPL_VALUE_STRING`

    String.

  `CPL_VALUE_REAL`

    Real number.

  `CPL_VALUE_INTEGER`

    Integer.

Functions

char **`CSLAddString`(char **papszStrList, const char *pszNewString)

  Append a string to a StringList and return a pointer to the modified StringList.

  If the input StringList is NULL, then a new StringList is created. Note that CSLAddString performance when building a list is in O(n^2) which can cause noticeable slow down when n > 10000.

char **`CSLAddStringMayFail`(char **papszStrList, const char *pszNewString)

  Same as CSLAddString() but may return NULL in case of (memory) failure.

int `CSLCount`(CSLConstList papszStrList)

  Return number of items in a string list.

  Returns the number of items in a string list, not counting the terminating NULL. Passing in NULL is safe, and will result in a count of zero.

  Lists are counted by iterating through them so long lists will take more time than short lists. Care should be taken to avoid using CSLCount() as an end condition for loops as it will result in O(n^2) behavior.

  Return

    the number of entries.

  Parameters

    - `papszStrList`: the string list to count.

const char *`CSLGetField`(CSLConstList papszStrList, int iField)

  Fetches the indicated field, being careful not to crash if the field doesn’t exist within this string list.

  The returned pointer should not be freed, and doesn’t necessarily last long.

void `CSLDestroy`(char **papszStrList)

  Free string list.

  Frees the passed string list (null terminated array of strings). It is safe to pass NULL.

  Parameters

    - `papszStrList`: the list to free.

char **`CSLDuplicate`(CSLConstList papszStrList)

  Clone a string list.

  Efficiently allocates a copy of a string list. The returned list is owned by the caller and should be freed with CSLDestroy().

  Return

    newly allocated copy.

  Parameters

    - `papszStrList`: the input string list.

char **`CSLMerge`(char **papszOrig, CSLConstList papszOverride)

  Merge two lists.

  The two lists are merged, ensuring that if any keys appear in both that the value from the second (papszOverride) list take precedence.

  Return

    updated list.

  Parameters

    - `papszOrig`: the original list, being modified.

    - `papszOverride`: the list of items being merged in. This list is unaltered and remains owned by the caller.

char **`CSLTokenizeString`(const char *pszString)

  Tokenizes a string and returns a StringList with one string for each token.

char **`CSLTokenizeStringComplex`(const char *pszString, const char *pszDelimiter, int bHonourStrings, int bAllowEmptyTokens)

  Obsolete tokenizing api.

  Use CSLTokenizeString2()

char **`CSLTokenizeString2`(const char *pszString, const char *pszDelimiter, int nCSLTFlags)

  Tokenize a string.

  This function will split a string into tokens based on specified’ delimiter(s) with a variety of options. The returned result is a string list that should be freed with CSLDestroy() when no longer needed.

  The available parsing options are:

  - CSLT_ALLOWEMPTYTOKENS: allow the return of empty tokens when two delimiters in a row occur with no other text between them. If not set, empty tokens will be discarded;

  - CSLT_STRIPLEADSPACES: strip leading space characters from the token (as reported by isspace());

  - CSLT_STRIPENDSPACES: strip ending space characters from the token (as reported by isspace());

  - CSLT_HONOURSTRINGS: double quotes can be used to hold values that should not be broken into multiple tokens;

  - CSLT_PRESERVEQUOTES: string quotes are carried into the tokens when this is set, otherwise they are removed;

  - CSLT_PRESERVEESCAPES: if set backslash escapes (for backslash itself, and for literal double quotes) will be preserved in the tokens, otherwise the backslashes will be removed in processing.

  Example:

  Parse a string into tokens based on various white space (space, newline, tab) and then print out results and cleanup. Quotes may be used to hold white space in tokens.

      char **papszTokens =
          CSLTokenizeString2( pszCommand, " \t\n",
                              CSLT_HONOURSTRINGS | CSLT_ALLOWEMPTYTOKENS );

      for( int i = 0; papszTokens != NULL && papszTokens[i] != NULL; ++i )
          printf( "arg %d: '%s'", papszTokens[i] );  // ok

      CSLDestroy( papszTokens );

  Return

    a string list of tokens owned by the caller.

  Parameters

    - `pszString`: the string to be split into tokens.

    - `pszDelimiters`: one or more characters to be used as token delimiters.

    - `nCSLTFlags`: an ORing of one or more of the CSLT_ flag values.

int `CSLPrint`(CSLConstList papszStrList, FILE *fpOut)

  Print a StringList to fpOut.

  If fpOut==NULL, then output is sent to stdout.

  Returns the number of lines printed.

char **`CSLLoad`(const char *pszFname)

  Load a text file into a string list.

  The VSI*L API is used, so VSIFOpenL() supported objects that aren’t physical files can also be accessed. Files are returned as a string list, with one item in the string list per line. End of line markers are stripped (by CPLReadLineL()).

  If reading the file fails a CPLError() will be issued and NULL returned.

  Return

    a string list with the files lines, now owned by caller. To be freed with CSLDestroy()

  Parameters

    - `pszFname`: the name of the file to read.

char **`CSLLoad2`(const char *pszFname, int nMaxLines, int nMaxCols, CSLConstList papszOptions)

  Load a text file into a string list.

  The VSI*L API is used, so VSIFOpenL() supported objects that aren’t physical files can also be accessed. Files are returned as a string list, with one item in the string list per line. End of line markers are stripped (by CPLReadLineL()).

  If reading the file fails a CPLError() will be issued and NULL returned.

  Return

    a string list with the files lines, now owned by caller. To be freed with CSLDestroy()

  Since

    GDAL 1.7.0

  Parameters

    - `pszFname`: the name of the file to read.

    - `nMaxLines`: maximum number of lines to read before stopping, or -1 for no limit.

    - `nMaxCols`: maximum number of characters in a line before stopping, or -1 for no limit.

    - `papszOptions`: NULL-terminated array of options. Unused for now.

int `CSLSave`(CSLConstList papszStrList, const char *pszFname)

  Write a StringList to a text file.

  Returns the number of lines written, or 0 if the file could not be written.

char **`CSLInsertStrings`(char **papszStrList, int nInsertAtLineNo, CSLConstList papszNewLines)

  Copies the contents of a StringList inside another StringList before the specified line.

  nInsertAtLineNo is a 0-based line index before which the new strings should be inserted. If this value is -1 or is larger than the actual number of strings in the list then the strings are added at the end of the source StringList.

  Returns the modified StringList.

char **`CSLInsertString`(char **papszStrList, int nInsertAtLineNo, const char *pszNewLine)

  Insert a string at a given line number inside a StringList.

  nInsertAtLineNo is a 0-based line index before which the new string should be inserted. If this value is -1 or is larger than the actual number of strings in the list then the string is added at the end of the source StringList.

  Returns the modified StringList.

char **`CSLRemoveStrings`(char **papszStrList, int nFirstLineToDelete, int nNumToRemove, char ***ppapszRetStrings)

  Remove strings inside a StringList.

  nFirstLineToDelete is the 0-based line index of the first line to remove. If this value is -1 or is larger than the actual number of strings in list then the nNumToRemove last strings are removed.

  If ppapszRetStrings != NULL then the deleted strings won’t be free’d, they will be stored in a new StringList and the pointer to this new list will be returned in *ppapszRetStrings.

  Returns the modified StringList.

int `CSLFindString`(CSLConstList papszList, const char *pszTarget)

  Find a string within a string list (case insensitive).

  Returns the index of the entry in the string list that contains the target string. The string in the string list must be a full match for the target, but the search is case insensitive.

  Return

    the index of the string within the list or -1 on failure.

  Parameters

    - `papszList`: the string list to be searched.

    - `pszTarget`: the string to be searched for.

int `CSLFindStringCaseSensitive`(CSLConstList papszList, const char *pszTarget)

  Find a string within a string list(case sensitive)

  Returns the index of the entry in the string list that contains the target string. The string in the string list must be a full match for the target.

  Return

    the index of the string within the list or -1 on failure.

  Since

    GDAL 2.0

  Parameters

    - `papszList`: the string list to be searched.

    - `pszTarget`: the string to be searched for.

int `CSLPartialFindString`(CSLConstList papszHaystack, const char *pszNeedle)

  Find a substring within a string list.

  Returns the index of the entry in the string list that contains the target string as a substring. The search is case sensitive (unlike CSLFindString()).

  Return

    the index of the string within the list or -1 on failure.

  Parameters

    - `papszHaystack`: the string list to be searched.

    - `pszNeedle`: the substring to be searched for.

int `CSLFindName`(CSLConstList papszStrList, const char *pszName)

  Find StringList entry with given key name.

  Return

    -1 on failure or the list index of the first occurrence matching the given key.

  Parameters

    - `papszStrList`: the string list to search.

    - `pszName`: the key value to look for (case insensitive).

int `CSLFetchBoolean`(CSLConstList papszStrList, const char *pszKey, int bDefault)

  DEPRECATED.

  Check for boolean key value.

  In a StringList of “Name=Value” pairs, look to see if there is a key with the given name, and if it can be interpreted as being TRUE. If the key appears without any “=Value” portion it will be considered true. If the value is NO, FALSE or 0 it will be considered FALSE otherwise if the key appears in the list it will be considered TRUE. If the key doesn’t appear at all, the indicated default value will be returned.

  Return

    TRUE or FALSE

  Parameters

    - `papszStrList`: the string list to search.

    - `pszKey`: the key value to look for (case insensitive).

    - `bDefault`: the value to return if the key isn’t found at all.

int `CSLTestBoolean`(const char *pszValue)

  Test what boolean value contained in the string.

  If pszValue is “NO”, “FALSE”, “OFF” or “0” will be returned FALSE. Otherwise, TRUE will be returned.

  Deprecated. Removed in GDAL 3.x.

  Use CPLTestBoolean() for C and CPLTestBool() for C++.

  Return

    TRUE or FALSE.

  Parameters

    - `pszValue`: the string should be tested.

int `CPLTestBoolean`(const char *pszValue)

  Test what boolean value contained in the string.

  If pszValue is “NO”, “FALSE”, “OFF” or “0” will be returned FALSE. Otherwise, TRUE will be returned.

  Use this only in C code. In C++, prefer CPLTestBool().

  Return

    TRUE or FALSE.

  Parameters

    - `pszValue`: the string should be tested.

bool `CPLTestBool`(const char *pszValue)

  Test what boolean value contained in the string.

  If pszValue is “NO”, “FALSE”, “OFF” or “0” will be returned false. Otherwise, true will be returned.

  Return

    true or false.

  Parameters

    - `pszValue`: the string should be tested.

bool `CPLFetchBool`(CSLConstList papszStrList, const char *pszKey, bool bDefault)

  Check for boolean key value.

  In a StringList of “Name=Value” pairs, look to see if there is a key with the given name, and if it can be interpreted as being TRUE. If the key appears without any “=Value” portion it will be considered true. If the value is NO, FALSE or 0 it will be considered FALSE otherwise if the key appears in the list it will be considered TRUE. If the key doesn’t appear at all, the indicated default value will be returned.

  Return

    true or false

  Parameters

    - `papszStrList`: the string list to search.

    - `pszKey`: the key value to look for (case insensitive).

    - `bDefault`: the value to return if the key isn’t found at all.

const char *`CPLParseNameValue`(const char *pszNameValue, char **ppszKey)

  Parse NAME=VALUE string into name and value components.

  Note that if ppszKey is non-NULL, the key (or name) portion will be allocated using CPLMalloc(), and returned in that pointer. It is the applications responsibility to free this string, but the application should not modify or free the returned value portion.

  This function also support “NAME:VALUE” strings and will strip white space from around the delimiter when forming name and value strings.

  Eventually CSLFetchNameValue() and friends may be modified to use CPLParseNameValue().

  Return

    the value portion (pointing into original string).

  Parameters

    - `pszNameValue`: string in “NAME=VALUE” format.

    - `ppszKey`: optional pointer though which to return the name portion.

const char *`CSLFetchNameValue`(CSLConstList papszStrList, const char *pszName)

  In a StringList of “Name=Value” pairs, look for the first value associated with the specified name.

  The search is not case sensitive. (“Name:Value” pairs are also supported for backward compatibility with older stuff.)

  Returns a reference to the value in the StringList that the caller should not attempt to free.

  Returns NULL if the name is not found.

const char *`CSLFetchNameValueDef`(CSLConstList papszStrList, const char *pszName, const char *pszDefault)

  Same as CSLFetchNameValue() but return pszDefault in case of no match.

char **`CSLFetchNameValueMultiple`(CSLConstList papszStrList, const char *pszName)

  In a StringList of “Name=Value” pairs, look for all the values with the specified name.

  The search is not case sensitive. (“Name:Value” pairs are also supported for backward compatibility with older stuff.)

  Returns StringList with one entry for each occurrence of the specified name. The StringList should eventually be destroyed by calling CSLDestroy().

  Returns NULL if the name is not found.

char **`CSLAddNameValue`(char **papszStrList, const char *pszName, const char *pszValue)

  Add a new entry to a StringList of “Name=Value” pairs, (“Name:Value” pairs are also supported for backward compatibility with older stuff.)

  This function does not check if a “Name=Value” pair already exists for that name and can generate multiple entries for the same name. Use CSLSetNameValue() if you want each name to have only one value.

  Returns the modified StringList.

char **`CSLSetNameValue`(char **papszStrList, const char *pszName, const char *pszValue)

  Assign value to name in StringList.

  Set the value for a given name in a StringList of “Name=Value” pairs (“Name:Value” pairs are also supported for backward compatibility with older stuff.)

  If there is already a value for that name in the list then the value is changed, otherwise a new “Name=Value” pair is added.

  Return

    modified StringList.

  Parameters

    - `papszList`: the original list, the modified version is returned.

    - `pszName`: the name to be assigned a value. This should be a well formed token (no spaces or very special characters).

    - `pszValue`: the value to assign to the name. This should not contain any newlines (CR or LF) but is otherwise pretty much unconstrained. If NULL any corresponding value will be removed.

void `CSLSetNameValueSeparator`(char **papszStrList, const char *pszSeparator)

  Replace the default separator (“:” or “=”) with the passed separator in the given name/value list.

  Note that if a separator other than “:” or “=” is used, the resulting list will not be manipulable by the CSL name/value functions any more.

  The CPLParseNameValue() function is used to break the existing lines, and it also strips white space from around the existing delimiter, thus the old separator, and any white space will be replaced by the new separator. For formatting purposes it may be desirable to include some white space in the new separator. e.g. “: ” or ” = “.

  Parameters

    - `papszList`: the list to update. Component strings may be freed but the list array will remain at the same location.

    - `pszSeparator`: the new separator string to insert.

char **`CSLParseCommandLine`(const char *pszCommandLine)

  Tokenize command line arguments in a list of strings.

  Return

    NULL terminated list of strings to free with CSLDestroy()

  Since

    GDAL 2.1

  Parameters

    - `pszCommandLine`: command line

char *`CPLEscapeString`(const char *pszString, int nLength, int nScheme)

  Apply escaping to string to preserve special characters.

  This function will “escape” a variety of special characters to make the string suitable to embed within a string constant or to write within a text stream but in a form that can be reconstituted to its original form. The escaping will even preserve zero bytes allowing preservation of raw binary data.

  CPLES_BackslashQuotable(0): This scheme turns a binary string into a form suitable to be placed within double quotes as a string constant. The backslash, quote, ‘\0’ and newline characters are all escaped in the usual C style.

  CPLES_XML(1): This scheme converts the ‘<’, ‘>’, ‘”’ and ‘&’ characters into their XML/HTML equivalent (<, >, ” and &) making a string safe to embed as CDATA within an XML element. The ‘\0’ is not escaped and should not be included in the input.

  CPLES_URL(2): Everything except alphanumerics and the characters ‘$’, ‘-‘, ‘_’, ‘.’, ‘+’, ‘!’, ‘*’, ‘’’, ‘(‘, ‘)’ and ‘,’ (see RFC1738) are converted to a percent followed by a two digit hex encoding of the character (leading zero supplied if needed). This is the mechanism used for encoding values to be passed in URLs.

  CPLES_SQL(3): All single quotes are replaced with two single quotes. Suitable for use when constructing literal values for SQL commands where the literal will be enclosed in single quotes.

  CPLES_CSV(4): If the values contains commas, semicolons, tabs, double quotes, or newlines it placed in double quotes, and double quotes in the value are doubled. Suitable for use when constructing field values for .csv files. Note that CPLUnescapeString() currently does not support this format, only CPLEscapeString(). See cpl_csv.cpp for CSV parsing support.

  CPLES_SQLI(7): All double quotes are replaced with two double quotes. Suitable for use when constructing identifiers for SQL commands where the literal will be enclosed in double quotes.

  Return

    an escaped, zero terminated string that should be freed with CPLFree() when no longer needed.

  Parameters

    - `pszInput`: the string to escape.

    - `nLength`: The number of bytes of data to preserve. If this is -1 the strlen(pszString) function will be used to compute the length.

    - `nScheme`: the encoding scheme to use.

char *`CPLUnescapeString`(const char *pszString, int *pnLength, int nScheme)

  Unescape a string.

  This function does the opposite of CPLEscapeString(). Given a string with special values escaped according to some scheme, it will return a new copy of the string returned to its original form.

  Return

    a copy of the unescaped string that should be freed by the application using CPLFree() when no longer needed.

  Parameters

    - `pszInput`: the input string. This is a zero terminated string.

    - `pnLength`: location to return the length of the unescaped string, which may in some cases include embedded ‘\0’ characters.

    - `nScheme`: the escaped scheme to undo (see CPLEscapeString() for a list). Does not yet support CSV.

char *`CPLBinaryToHex`(int nBytes, const GByte *pabyData)

  Binary to hexadecimal translation.

  Return

    hexadecimal translation, zero terminated. Free with CPLFree().

  Parameters

    - `nBytes`: number of bytes of binary data in pabyData.

    - `pabyData`: array of data bytes to translate.

GByte *`CPLHexToBinary`(const char *pszHex, int *pnBytes)

  Hexadecimal to binary translation.

  Return

    returns binary buffer of data - free with CPLFree().

  Parameters

    - `pszHex`: the input hex encoded string.

    - `pnBytes`: the returned count of decoded bytes placed here.

char *`CPLBase64Encode`(int nBytes, const GByte *pabyData)

  Base64 encode a buffer.

int `CPLBase64DecodeInPlace`(GByte *pszBase64)

  Decode base64 string “pszBase64” (null terminated) in place.

  Returns length of decoded array or 0 on failure.

CPLValueType `CPLGetValueType`(const char *pszValue)

  Detect the type of the value contained in a string, whether it is a real, an integer or a string Leading and trailing spaces are skipped in the analysis.

  Note: in the context of this function, integer must be understood in a broad sense. It does not mean that the value can fit into a 32 bit integer for example. It might be larger.

  Return

    returns the type of the value contained in the string.

  Parameters

    - `pszValue`: the string to analyze

size_t `CPLStrlcpy`(char *pszDest, const char *pszSrc, size_t nDestSize)

  Copy source string to a destination buffer.

  This function ensures that the destination buffer is always NUL terminated (provided that its length is at least 1).

  This function is designed to be a safer, more consistent, and less error prone replacement for strncpy. Its contract is identical to libbsd’s strlcpy.

  Truncation can be detected by testing if the return value of CPLStrlcpy is greater or equal to nDestSize.

      char szDest[5] = {};
      if( CPLStrlcpy(szDest, "abcde", sizeof(szDest)) >= sizeof(szDest) )
          fprintf(stderr, "truncation occurred !\n");

  Return

    the length of the source string (=strlen(pszSrc))

  Since

    GDAL 1.7.0

  Parameters

    - `pszDest`: destination buffer

    - `pszSrc`: source string. Must be NUL terminated

    - `nDestSize`: size of destination buffer (including space for the NUL terminator character)

size_t `CPLStrlcat`(char *pszDest, const char *pszSrc, size_t nDestSize)

  Appends a source string to a destination buffer.

  This function ensures that the destination buffer is always NUL terminated (provided that its length is at least 1 and that there is at least one byte free in pszDest, that is to say strlen(pszDest_before) < nDestSize)

  This function is designed to be a safer, more consistent, and less error prone replacement for strncat. Its contract is identical to libbsd’s strlcat.

  Truncation can be detected by testing if the return value of CPLStrlcat is greater or equal to nDestSize.

      char szDest[5] = {};
      CPLStrlcpy(szDest, "ab", sizeof(szDest));
      if( CPLStrlcat(szDest, "cde", sizeof(szDest)) >= sizeof(szDest) )
          fprintf(stderr, "truncation occurred !\n");

  Return

    the theoretical length of the destination string after concatenation (=strlen(pszDest_before) + strlen(pszSrc)). If strlen(pszDest_before) >= nDestSize, then it returns nDestSize + strlen(pszSrc)

  Since

    GDAL 1.7.0

  Parameters

    - `pszDest`: destination buffer. Must be NUL terminated before running CPLStrlcat

    - `pszSrc`: source string. Must be NUL terminated

    - `nDestSize`: size of destination buffer (including space for the NUL terminator character)

size_t `CPLStrnlen`(const char *pszStr, size_t nMaxLen)

  Returns the length of a NUL terminated string by reading at most the specified number of bytes.

  The CPLStrnlen() function returns min(strlen(pszStr), nMaxLen). Only the first nMaxLen bytes of the string will be read. Useful to test if a string contains at least nMaxLen characters without reading the full string up to the NUL terminating character.

  Return

    strlen(pszStr) if the length is lesser than nMaxLen, otherwise nMaxLen if the NUL character has not been found in the first nMaxLen bytes.

  Since

    GDAL 1.7.0

  Parameters

    - `pszStr`: a NUL terminated string

    - `nMaxLen`: maximum number of bytes to read in pszStr

int `CPLvsnprintf`(char *str, size_t size, const char *fmt, va_list args)

  vsnprintf() wrapper that is not sensitive to LC_NUMERIC settings.

  This function has the same contract as standard vsnprintf(), except that formatting of floating-point numbers will use decimal point, whatever the current locale is set.

  Return

    the number of characters (excluding terminating nul) that would be written if size is big enough. Or potentially -1 with Microsoft C runtime for Visual Studio < 2015.

  Since

    GDAL 2.0

  Parameters

    - `str`: output buffer

    - `size`: size of the output buffer (including space for terminating nul)

    - `fmt`: formatting string

    - `args`: arguments

int `CPLsnprintf`(char *str, size_t size, const char *fmt, ...)

  snprintf() wrapper that is not sensitive to LC_NUMERIC settings.

  This function has the same contract as standard snprintf(), except that formatting of floating-point numbers will use decimal point, whatever the current locale is set.

  Return

    the number of characters (excluding terminating nul) that would be written if size is big enough. Or potentially -1 with Microsoft C runtime for Visual Studio < 2015.

  Since

    GDAL 2.0

  Parameters

    - `str`: output buffer

    - `size`: size of the output buffer (including space for terminating nul)

    - `fmt`: formatting string

    - `...`: arguments

int `CPLprintf`(const char *fmt, ...)

  printf() wrapper that is not sensitive to LC_NUMERIC settings.

  This function has the same contract as standard printf(), except that formatting of floating-point numbers will use decimal point, whatever the current locale is set.

  Return

    the number of characters (excluding terminating nul) written in output buffer.

  Since

    GDAL 2.0

  Parameters

    - `fmt`: formatting string

    - `...`: arguments

const char *`CPLSPrintf`(const char *fmt, ...)

  CPLSPrintf() that works with 10 static buffer.

  It returns a ref. to a static buffer that should not be freed and is valid only until the next call to CPLSPrintf().

char **`CSLAppendPrintf`(char **papszStrList, const char *fmt, ...)

  Use CPLSPrintf() to append a new line at the end of a StringList.

  Returns the modified StringList.

int `CPLVASPrintf`(char **buf, const char *fmt, va_list args)

  This is intended to serve as an easy to use C callable vasprintf() alternative.

  Used in the GeoJSON library for instance

int `CPLEncodingCharSize`(const char *pszEncoding)

  Return bytes per character for encoding.

  This function returns the size in bytes of the smallest character in this encoding. For fixed width encodings (ASCII, UCS-2, UCS-4) this is straight forward. For encodings like UTF8 and UTF16 which represent some characters as a sequence of atomic character sizes the function still returns the atomic character size (1 for UTF8, 2 for UTF16).

  This function will return the correct value for well known encodings with corresponding CPL_ENC_ values. It may not return the correct value for other encodings even if they are supported by the underlying iconv or windows transliteration services. Hopefully it will improve over time.

  Return

    the size of a minimal character in bytes or -1 if the size is unknown.

  Parameters

    - `pszEncoding`: the name of the encoding.

char *`CPLRecode`(const char *pszSource, const char *pszSrcEncoding, const char *pszDstEncoding)

  Convert a string from a source encoding to a destination encoding.

  The only guaranteed supported encodings are CPL_ENC_UTF8, CPL_ENC_ASCII and CPL_ENC_ISO8859_1. Currently, the following conversions are supported :

  - CPL_ENC_ASCII -> CPL_ENC_UTF8 or CPL_ENC_ISO8859_1 (no conversion in fact)

  - CPL_ENC_ISO8859_1 -> CPL_ENC_UTF8

  - CPL_ENC_UTF8 -> CPL_ENC_ISO8859_1

  If an error occurs an error may, or may not be posted with CPLError().

  Return

    a NULL terminated string which should be freed with CPLFree().

  Since

    GDAL 1.6.0

  Parameters

    - `pszSource`: a NULL terminated string.

    - `pszSrcEncoding`: the source encoding.

    - `pszDstEncoding`: the destination encoding.

char *`CPLRecodeFromWChar`(const wchar_t *pwszSource, const char *pszSrcEncoding, const char *pszDstEncoding)

  Convert wchar_t string to UTF-8.

  Convert a wchar_t string into a multibyte utf-8 string. The only guaranteed supported source encoding is CPL_ENC_UCS2, and the only guaranteed supported destination encodings are CPL_ENC_UTF8, CPL_ENC_ASCII and CPL_ENC_ISO8859_1. In some cases (i.e. using iconv()) other encodings may also be supported.

  Note that the wchar_t type varies in size on different systems. On win32 it is normally 2 bytes, and on UNIX 4 bytes.

  If an error occurs an error may, or may not be posted with CPLError().

  Return

    a zero terminated multi-byte string which should be freed with CPLFree(), or NULL if an error occurs.

  Since

    GDAL 1.6.0

  Parameters

    - `pwszSource`: the source wchar_t string, terminated with a 0 wchar_t.

    - `pszSrcEncoding`: the source encoding, typically CPL_ENC_UCS2.

    - `pszDstEncoding`: the destination encoding, typically CPL_ENC_UTF8.

wchar_t *`CPLRecodeToWChar`(const char *pszSource, const char *pszSrcEncoding, const char *pszDstEncoding)

  Convert UTF-8 string to a wchar_t string.

  Convert a 8bit, multi-byte per character input string into a wide character (wchar_t) string. The only guaranteed supported source encodings are CPL_ENC_UTF8, CPL_ENC_ASCII and CPL_ENC_ISO8869_1 (LATIN1). The only guaranteed supported destination encoding is CPL_ENC_UCS2. Other source and destination encodings may be supported depending on the underlying implementation.

  Note that the wchar_t type varies in size on different systems. On win32 it is normally 2 bytes, and on UNIX 4 bytes.

  If an error occurs an error may, or may not be posted with CPLError().

  Return

    the zero terminated wchar_t string (to be freed with CPLFree()) or NULL on error.

  Since

    GDAL 1.6.0

  Parameters

    - `pszSource`: input multi-byte character string.

    - `pszSrcEncoding`: source encoding, typically CPL_ENC_UTF8.

    - `pszDstEncoding`: destination encoding, typically CPL_ENC_UCS2.

int `CPLIsUTF8`(const char *pabyData, int nLen)

  Test if a string is encoded as UTF-8.

  Return

    TRUE if the string is encoded as UTF-8. FALSE otherwise

  Since

    GDAL 1.7.0

  Parameters

    - `pabyData`: input string to test

    - `nLen`: length of the input string, or -1 if the function must compute the string length. In which case it must be null terminated.

char *`CPLForceToASCII`(const char *pabyData, int nLen, char chReplacementChar)

  Return a new string that is made only of ASCII characters.

  If non-ASCII characters are found in the input string, they will be replaced by the provided replacement character.

  Return

    a new string that must be freed with CPLFree().

  Since

    GDAL 1.7.0

  Parameters

    - `pabyData`: input string to test

    - `nLen`: length of the input string, or -1 if the function must compute the string length. In which case it must be null terminated.

    - `chReplacementChar`: character which will be used when the input stream contains a non ASCII character. Must be valid ASCII!

int `CPLStrlenUTF8`(const char *pszUTF8Str)

  Return the number of UTF-8 characters of a nul-terminated string.

  This is different from strlen() which returns the number of bytes.

  Return

    the number of UTF-8 characters.

  Parameters

    - `pszUTF8Str`: a nul-terminated UTF-8 string

int `CPLCanRecode`(const char *pszTestStr, const char *pszSrcEncoding, const char *pszDstEncoding)

  Checks if it is possible to recode a string from one encoding to another.

  Return

    a TRUE if recode is possible.

  Since

    GDAL 3.1.0

  Parameters

    - `pszTestStr`: a NULL terminated string.

    - `pszSrcEncoding`: the source encoding.

    - `pszDstEncoding`: the destination encoding.

CPLString `CPLOPrintf`(const char *pszFormat, ...)

  Return a CPLString with the content of sprintf()

CPLString `CPLOvPrintf`(const char *pszFormat, va_list args)

  Return a CPLString with the content of vsprintf()

CPLString `CPLQuotedSQLIdentifier`(const char *pszIdent)

  Return a CPLString of the SQL quoted identifier.

CPLString `CPLURLGetValue`(const char *pszURL, const char *pszKey)

  Return the value matching a key from a key=value pair in a URL.

  Return

    the value of empty string if not found.

  Since

    GDAL 1.9.0

  Parameters

    - `pszURL`: the URL.

    - `pszKey`: the key to find.

CPLString `CPLURLAddKVP`(const char *pszURL, const char *pszKey, const char *pszValue)

  Return a new URL with a new key=value pair.

  Return

    the modified URL.

  Since

    GDAL 1.9.0

  Parameters

    - `pszURL`: the URL.

    - `pszKey`: the key to find.

    - `pszValue`: the value of the key (may be NULL to unset an existing KVP).

class `CPLString` : public string
  #include <cpl_string.h>

  Convenient string class based on std::string.

  Public Functions

  `CPLString`(void)

    Constructor.

  `CPLString`(const std::string &oStr)

    Constructor.

  `CPLString`(const char *pszStr)

    Constructor.

  `CPLString`(const char *pszStr, size_t n)

    Constructor.

  `operator const char *`(void) const

    Return string as zero terminated character array.

  char &`operator[]`(std::string::size_type i)

    Return character at specified index.

  const char &`operator[]`(std::string::size_type i) const

    Return character at specified index.

  char &`operator[]`(int i)

    Return character at specified index.

  const char &`operator[]`(int i) const

    Return character at specified index.

  void `Clear`()

    Clear the string.

  void `Seize`(char *pszValue)

    Assign specified string and take ownership of it (assumed to be allocated with CPLMalloc()).

    NULL can be safely passed to clear the string.

  CPLString &`Printf`(const char *pszFormat, ...)

    Assign the content of the string using sprintf()

  CPLString &`vPrintf`(const char *pszFormat, va_list args)

    Assign the content of the string using vsprintf()

  CPLString &`FormatC`(double dfValue, const char *pszFormat = nullptr)

    Format double in C locale.

    The passed value is formatted using the C locale (period as decimal separator) and appended to the target CPLString.

    Return

      a reference to the CPLString.

    Parameters

      - `dfValue`: the value to format.

      - `pszFormat`: the sprintf() style format to use or omit for default. Note that this format string should only include one substitution argument and it must be for a double (f or g).

  CPLString &`Trim`()

    Trim white space.

    Trims white space off the let and right of the string. White space is any of a space, a tab, a newline (‘\n’) or a carriage control (‘\r’).

    Return

      a reference to the CPLString.

  CPLString &`Recode`(const char *pszSrcEncoding, const char *pszDstEncoding)

    Recode the string.

  CPLString &`replaceAll`(const std::string &osBefore, const std::string &osAfter)

    Replace all occurrences of osBefore with osAfter.

  CPLString &`replaceAll`(const std::string &osBefore, char chAfter)

    Replace all occurrences of osBefore with chAfter.

  CPLString &`replaceAll`(char chBefore, const std::string &osAfter)

    Replace all occurrences of chBefore with osAfter.

  CPLString &`replaceAll`(char chBefore, char chAfter)

    Replace all occurrences of chBefore with chAfter.

  size_t `ifind`(const std::string &str, size_t pos = 0) const

    Case insensitive find() alternative.

    Return

      the position of substring in the string or std::string::npos if not found.

    Since

      GDAL 1.9.0

    Parameters

      - `str`: substring to find.

      - `pos`: offset in the string at which the search starts.

  size_t `ifind`(const char *s, size_t pos = 0) const

    Case insensitive find() alternative.

    Return

      the position of the substring in the string or std::string::npos if not found.

    Since

      GDAL 1.9.0

    Parameters

      - `s`: substring to find.

      - `nPos`: offset in the string at which the search starts.

  CPLString &`toupper`(void)

    Convert to upper case in place.

  CPLString &`tolower`(void)

    Convert to lower case in place.

  bool `endsWith`(const std::string &osStr) const

    Returns whether the string ends with another string.

    Return

      true if the string ends wit osStr.

    Parameters

      - `osStr`: other string.

class `CPLStringList`
  #include <cpl_string.h>

  String list class designed around our use of C “char**” string lists.

  Public Functions

  `CPLStringList`()
  `CPLStringList`(char **papszList, int bTakeOwnership = TRUE)

    CPLStringList constructor.

    Parameters

      - `papszListIn`: the NULL terminated list of strings to consume.

      - `bTakeOwnership`: TRUE if the CPLStringList should take ownership of the list of strings which implies responsibility to free them.

  `CPLStringList`(CSLConstList papszList)

    CPLStringList constructor.

    The input list is copied.

    Parameters

      - `papszListIn`: the NULL terminated list of strings to ingest.

  `CPLStringList`(const CPLStringList &oOther)

    Copy constructor.

  `~CPLStringList`()
  CPLStringList &`Clear`()

    Clear the string list.

  int `size`() const

    Return size of list.

  int `Count`() const

    Return

      count of strings in the list, zero if empty.

  bool `empty`() const

    Return whether the list is empty.

  CPLStringList &`AddString`(const char *pszNewString)

    Add a string to the list.

    A copy of the passed in string is made and inserted in the list.

    Parameters

      - `pszNewString`: the string to add to the list.

  CPLStringList &`AddStringDirectly`(char *pszNewString)

    Add a string to the list.

    This method is similar to AddString(), but ownership of the pszNewString is transferred to the CPLStringList class.

    Parameters

      - `pszNewString`: the string to add to the list.

  CPLStringList *`InsertString`(int nInsertAtLineNo, const char *pszNewLine)

    Insert into the list at identified location.

    This method will insert a string into the list at the identified location. The insertion point must be within or at the end of the list. The following entries are pushed down to make space.

    Parameters

      - `nInsertAtLineNo`: the line to insert at, zero to insert at front.

      - `pszNewLine`: to the line to insert. This string will be copied.

  CPLStringList &`InsertStringDirectly`(int nInsertAtLineNo, char *pszNewLine)

    Insert into the list at identified location.

    This method will insert a string into the list at the identified location. The insertion point must be within or at the end of the list. The following entries are pushed down to make space.

    Parameters

      - `nInsertAtLineNo`: the line to insert at, zero to insert at front.

      - `pszNewLine`: to the line to insert, the ownership of this string will be taken over the by the object. It must have been allocated on the heap.

  int `FindString`(const char *pszTarget) const

    Return index of pszTarget in the list, or -1.

  int `PartialFindString`(const char *pszNeedle) const

    Return index of pszTarget in the list (using partial search), or -1.

  int `FindName`(const char *pszName) const

    Get index of given name/value keyword.

    Note that this search is for a line in the form name=value or name:value. Use FindString() or PartialFindString() for searches not based on name=value pairs.

    Return

      the string list index of this name, or -1 on failure.

    Parameters

      - `pszKey`: the name to search for.

  bool `FetchBool`(const char *pszKey, bool bDefault) const

    Check for boolean key value.

    In a CPLStringList of “Name=Value” pairs, look to see if there is a key with the given name, and if it can be interpreted as being TRUE. If the key appears without any “=Value” portion it will be considered true. If the value is NO, FALSE or 0 it will be considered FALSE otherwise if the key appears in the list it will be considered TRUE. If the key doesn’t appear at all, the indicated default value will be returned.

    Return

      true or false

    Parameters

      - `pszKey`: the key value to look for (case insensitive).

      - `bDefault`: the value to return if the key isn’t found at all.

  int `FetchBoolean`(const char *pszKey, int bDefault) const

    DEPRECATED: Check for boolean key value.

    In a CPLStringList of “Name=Value” pairs, look to see if there is a key with the given name, and if it can be interpreted as being TRUE. If the key appears without any “=Value” portion it will be considered true. If the value is NO, FALSE or 0 it will be considered FALSE otherwise if the key appears in the list it will be considered TRUE. If the key doesn’t appear at all, the indicated default value will be returned.

    Return

      TRUE or FALSE

    Parameters

      - `pszKey`: the key value to look for (case insensitive).

      - `bDefault`: the value to return if the key isn’t found at all.

  const char *`FetchNameValue`(const char *pszKey) const

    Fetch value associated with this key name.

    If this list sorted, a fast binary search is done, otherwise a linear scan is done. Name lookup is case insensitive.

    Return

      the corresponding value or NULL if not found. The returned string should not be modified and points into internal object state that may change on future calls.

    Parameters

      - `pszName`: the key name to search for.

  const char *`FetchNameValueDef`(const char *pszKey, const char *pszDefault) const

    Fetch value associated with this key name.

    If this list sorted, a fast binary search is done, otherwise a linear scan is done. Name lookup is case insensitive.

    Return

      the corresponding value or the passed default if not found.

    Parameters

      - `pszName`: the key name to search for.

      - `pszDefault`: the default value returned if the named entry isn’t found.

  CPLStringList &`AddNameValue`(const char *pszKey, const char *pszValue)

    Add a name=value entry to the list.

    A key=value string is prepared and appended to the list. There is no check for other values for the same key in the list.

    Parameters

      - `pszKey`: the key name to add.

      - `pszValue`: the key value to add.

  CPLStringList &`SetNameValue`(const char *pszKey, const char *pszValue)

    Set name=value entry in the list.

    Similar to AddNameValue(), except if there is already a value for the key in the list it is replaced instead of adding a new entry to the list. If pszValue is NULL any existing key entry is removed.

    Parameters

      - `pszKey`: the key name to add.

      - `pszValue`: the key value to add.

  CPLStringList &`Assign`(char **papszListIn, int bTakeOwnership = TRUE)

    Assign a list of strings.

    Return

      a reference to the CPLStringList on which it was invoked.

    Parameters

      - `papszListIn`: the NULL terminated list of strings to consume.

      - `bTakeOwnership`: TRUE if the CPLStringList should take ownership of the list of strings which implies responsibility to free them.

  CPLStringList &`operator=`(char **papszListIn)

    Assignment operator.

  CPLStringList &`operator=`(const CPLStringList &oOther)

    Assignment operator.

  CPLStringList &`operator=`(CSLConstList papszListIn)

    Assignment operator.

  CPLStringList &`operator=`(CPLStringList &&oOther)

    Move assignment operator.

  char *`operator[]`(int i)

    Return string at specified index.

    Fetch entry “i”.

    Fetches the requested item in the list. Note that the returned string remains owned by the CPLStringList. If “i” is out of range NULL is returned.

    Return

      selected entry in the list.

    Parameters

      - `i`: the index of the list item to return.

  char *`operator[]`(size_t i)

    Return string at specified index.

  const char *`operator[]`(int i) const

    Return string at specified index.

  const char *`operator[]`(size_t i) const

    Return string at specified index.

  const char *`operator[]`(const char *pszKey) const

    Return value corresponding to pszKey, or nullptr.

  char **`List`()

    Return list.

    Ownership remains to the object

  CSLConstList `List`() const

    Return list.

    Ownership remains to the object

  char **`StealList`()

    Seize ownership of underlying string array.

    This method is similar to List(), except that the returned list is now owned by the caller and the CPLStringList is emptied.

    Return

      the C style string list.

  CPLStringList &`Sort`()

    Sort the entries in the list and mark list sorted.

    Note that once put into “sorted” mode, the CPLStringList will attempt to keep things in sorted order through calls to AddString(), AddStringDirectly(), AddNameValue(), SetNameValue(). Complete list assignments (via Assign() and operator= will clear the sorting state. When in sorted order FindName(), FetchNameValue() and FetchNameValueDef() will do a binary search to find the key, substantially improve lookup performance in large lists.

  int `IsSorted`() const

    Returns whether the list is sorted.

  `operator char **`(void)

    Return lists.

  `operator CSLConstList`(void) const

    Return lists.

  Private Functions

  void `MakeOurOwnCopy`()
  void `EnsureAllocation`(int nMaxLength)
  int `FindSortedInsertionPoint`(const char *pszLine)

  Private Members

  char **`papszList` = nullptr
  int `nCount` = 0
  int `nAllocation` = 0
  bool `bOwnList` = false
  bool `bIsSorted` = false

## cpl_time.h

Functions

struct tm *`CPLUnixTimeToYMDHMS`(GIntBig unixTime, struct tm *pRet)

  Converts a time value since the Epoch (aka “unix” time) to a broken-down UTC time.

  This function is similar to gmtime_r(). This function will always set tm_isdst to 0.

  Return

    the structure pointed by pRet filled with a broken-down UTC time.

  Parameters

    - `unixTime`: number of seconds since the Epoch.

    - `pRet`: address of the return structure.

GIntBig `CPLYMDHMSToUnixTime`(const struct tm *brokendowntime)

  Converts a broken-down UTC time into time since the Epoch (aka “unix” time).

  This function is similar to mktime(), but the passed structure is not modified. This function ignores the tm_wday, tm_yday and tm_isdst fields of the passed value. No timezone shift will be applied. This function returns 0 for the 1/1/1970 00:00:00

  Return

    a number of seconds since the Epoch encoded as a value of type GIntBig, or -1 if the time cannot be represented.

  Parameters

    - `brokendowntime`: broken-downtime UTC time.

int `CPLParseRFC822DateTime`(const char *pszRFC822DateTime, int *pnYear, int *pnMonth, int *pnDay, int *pnHour, int *pnMinute, int *pnSecond, int *pnTZFlag, int *pnWeekDay)

  Parse a RFC822 formatted date-time string.

  Such as [Fri,] 28 Dec 2007 05:24[:17] GMT

  Return

    TRUE if parsing is successful

  Since

    GDAL 2.3

  Parameters

    - `pszRFC822DateTime`: formatted string.

    - `pnYear`: pointer to int receiving year (like 1980, 2000, etc…), or NULL

    - `pnMonth`: pointer to int receiving month (between 1 and 12), or NULL

    - `pnDay`: pointer to int receiving day of month (between 1 and 31), or NULL

    - `pnHour`: pointer to int receiving hour of day (between 0 and 23), or NULL

    - `pnMinute`: pointer to int receiving minute (between 0 and 59), or NULL

    - `pnSecond`: pointer to int receiving second (between 0 and 60, or -1 if unknown), or NULL

    - `pnTZFlag`: pointer to int receiving time zone flag (0=unknown, 100=GMT, 101=GMT+15minute, 99=GMT-15minute), or NULL

    - `pnWeekDay`: pointer to int receiving day of week (between 1 and 7, or 0 if invalid/unset), or NULL

## cpl_virtualmem.h

Virtual memory management.

This file provides mechanism to define virtual memory mappings, whose content is allocated transparently and filled on-the-fly. Those virtual memory mappings can be much larger than the available RAM, but only parts of the virtual memory mapping, in the limit of the allowed the cache size, will actually be physically allocated.

This exploits low-level mechanisms of the operating system (virtual memory allocation, page protection and handler of virtual memory exceptions).

It is also possible to create a virtual memory mapping from a file or part of a file.

The current implementation is Linux only.

Typedefs

typedef struct CPLVirtualMem `CPLVirtualMem`

  Opaque type that represents a virtual memory mapping.

typedef void (*`CPLVirtualMemCachePageCbk`)(CPLVirtualMem *ctxt, size_t nOffset, void *pPageToFill, size_t nToFill, void *pUserData)

  Callback triggered when a still unmapped page of virtual memory is accessed.

  The callback has the responsibility of filling the page with relevant values

  Parameters

    - `ctxt`: virtual memory handle.

    - `nOffset`: offset of the page in the memory mapping.

    - `pPageToFill`: address of the page to fill. Note that the address might be a temporary location, and not at CPLVirtualMemGetAddr() + nOffset.

    - `nToFill`: number of bytes of the page.

    - `pUserData`: user data that was passed to CPLVirtualMemNew().

typedef void (*`CPLVirtualMemUnCachePageCbk`)(CPLVirtualMem *ctxt, size_t nOffset, const void *pPageToBeEvicted, size_t nToBeEvicted, void *pUserData)

  Callback triggered when a dirty mapped page is going to be freed.

  (saturation of cache, or termination of the virtual memory mapping).

  Parameters

    - `ctxt`: virtual memory handle.

    - `nOffset`: offset of the page in the memory mapping.

    - `pPageToBeEvicted`: address of the page that will be flushed. Note that the address might be a temporary location, and not at CPLVirtualMemGetAddr() + nOffset.

    - `nToBeEvicted`: number of bytes of the page.

    - `pUserData`: user data that was passed to CPLVirtualMemNew().

typedef void (*`CPLVirtualMemFreeUserData`)(void *pUserData)

  Callback triggered when a virtual memory mapping is destroyed.

  Parameters

    - `pUserData`: user data that was passed to CPLVirtualMemNew().

Enums

enum `CPLVirtualMemAccessMode`

  Access mode of a virtual memory mapping.

  Values:

  `VIRTUALMEM_READONLY`

    The mapping is meant at being read-only, but writes will not be prevented. Note that any content written will be lost.

  `VIRTUALMEM_READONLY_ENFORCED`

    The mapping is meant at being read-only, and this will be enforced through the operating system page protection mechanism.

  `VIRTUALMEM_READWRITE`

    The mapping is meant at being read-write, and modified pages can be saved thanks to the pfnUnCachePage callback

Functions

size_t `CPLGetPageSize`(void)

  Return the size of a page of virtual memory.

  Return

    the page size.

  Since

    GDAL 1.11

CPLVirtualMem *`CPLVirtualMemNew`(size_t nSize, size_t nCacheSize, size_t nPageSizeHint, int bSingleThreadUsage, CPLVirtualMemAccessMode eAccessMode, CPLVirtualMemCachePageCbk pfnCachePage, CPLVirtualMemUnCachePageCbk pfnUnCachePage, CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData)

  Create a new virtual memory mapping.

  This will reserve an area of virtual memory of size nSize, whose size might be potentially much larger than the physical memory available. Initially, no physical memory will be allocated. As soon as memory pages will be accessed, they will be allocated transparently and filled with the pfnCachePage callback. When the allowed cache size is reached, the least recently used pages will be unallocated.

  On Linux AMD64 platforms, the maximum value for nSize is 128 TB. On Linux x86 platforms, the maximum value for nSize is 2 GB.

  Only supported on Linux for now.

  Note that on Linux, this function will install a SIGSEGV handler. The original handler will be restored by CPLVirtualMemManagerTerminate().

  Return

    a virtual memory object that must be freed by CPLVirtualMemFree(), or NULL in case of failure.

  Since

    GDAL 1.11

  Parameters

    - `nSize`: size in bytes of the virtual memory mapping.

    - `nCacheSize`: size in bytes of the maximum memory that will be really allocated (must ideally fit into RAM).

    - `nPageSizeHint`: hint for the page size. Must be a multiple of the system page size, returned by CPLGetPageSize(). Minimum value is generally 4096. Might be set to 0 to let the function determine a default page size.

    - `bSingleThreadUsage`: set to TRUE if there will be no concurrent threads that will access the virtual memory mapping. This can optimize performance a bit.

    - `eAccessMode`: permission to use for the virtual memory mapping.

    - `pfnCachePage`: callback triggered when a still unmapped page of virtual memory is accessed. The callback has the responsibility of filling the page with relevant values.

    - `pfnUnCachePage`: callback triggered when a dirty mapped page is going to be freed (saturation of cache, or termination of the virtual memory mapping). Might be NULL.

    - `pfnFreeUserData`: callback that can be used to free pCbkUserData. Might be NULL

    - `pCbkUserData`: user data passed to pfnCachePage and pfnUnCachePage.

int `CPLIsVirtualMemFileMapAvailable`(void)

  Return if virtual memory mapping of a file is available.

  Return

    TRUE if virtual memory mapping of a file is available.

  Since

    GDAL 1.11

CPLVirtualMem *`CPLVirtualMemFileMapNew`(VSILFILE *fp, vsi_l_offset nOffset, vsi_l_offset nLength, CPLVirtualMemAccessMode eAccessMode, CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData)

  Create a new virtual memory mapping from a file.

  The file must be a “real” file recognized by the operating system, and not a VSI extended virtual file.

  In VIRTUALMEM_READWRITE mode, updates to the memory mapping will be written in the file.

  On Linux AMD64 platforms, the maximum value for nLength is 128 TB. On Linux x86 platforms, the maximum value for nLength is 2 GB.

  Supported on Linux only in GDAL <= 2.0, and all POSIX systems supporting mmap() in GDAL >= 2.1

  Return

    a virtual memory object that must be freed by CPLVirtualMemFree(), or NULL in case of failure.

  Since

    GDAL 1.11

  Parameters

    - `fp`: Virtual file handle.

    - `nOffset`: Offset in the file to start the mapping from.

    - `nLength`: Length of the portion of the file to map into memory.

    - `eAccessMode`: Permission to use for the virtual memory mapping. This must be consistent with how the file has been opened.

    - `pfnFreeUserData`: callback that is called when the object is destroyed.

    - `pCbkUserData`: user data passed to pfnFreeUserData.

CPLVirtualMem *`CPLVirtualMemDerivedNew`(CPLVirtualMem *pVMemBase, vsi_l_offset nOffset, vsi_l_offset nSize, CPLVirtualMemFreeUserData pfnFreeUserData, void *pCbkUserData)

  Create a new virtual memory mapping derived from an other virtual memory mapping.

  This may be useful in case of creating mapping for pixel interleaved data.

  The new mapping takes a reference on the base mapping.

  Return

    a virtual memory object that must be freed by CPLVirtualMemFree(), or NULL in case of failure.

  Since

    GDAL 1.11

  Parameters

    - `pVMemBase`: Base virtual memory mapping

    - `nOffset`: Offset in the base virtual memory mapping from which to start the new mapping.

    - `nSize`: Size of the base virtual memory mapping to expose in the the new mapping.

    - `pfnFreeUserData`: callback that is called when the object is destroyed.

    - `pCbkUserData`: user data passed to pfnFreeUserData.

void `CPLVirtualMemFree`(CPLVirtualMem *ctxt)

  Free a virtual memory mapping.

  The pointer returned by CPLVirtualMemGetAddr() will no longer be valid. If the virtual memory mapping was created with read/write permissions and that they are dirty (i.e. modified) pages, they will be flushed through the pfnUnCachePage callback before being freed.

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

void *`CPLVirtualMemGetAddr`(CPLVirtualMem *ctxt)

  Return the pointer to the start of a virtual memory mapping.

  The bytes in the range [p:p+CPLVirtualMemGetSize()-1] where p is the pointer returned by this function will be valid, until CPLVirtualMemFree() is called.

  Note that if a range of bytes used as an argument of a system call (such as read() or write()) contains pages that have not been “realized”, the system call will fail with EFAULT. CPLVirtualMemPin() can be used to work around this issue.

  Return

    the pointer to the start of a virtual memory mapping.

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

size_t `CPLVirtualMemGetSize`(CPLVirtualMem *ctxt)

  Return the size of the virtual memory mapping.

  Return

    the size of the virtual memory mapping.

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

int `CPLVirtualMemIsFileMapping`(CPLVirtualMem *ctxt)

  Return if the virtual memory mapping is a direct file mapping.

  Return

    TRUE if the virtual memory mapping is a direct file mapping.

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

CPLVirtualMemAccessMode `CPLVirtualMemGetAccessMode`(CPLVirtualMem *ctxt)

  Return the access mode of the virtual memory mapping.

  Return

    the access mode of the virtual memory mapping.

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

size_t `CPLVirtualMemGetPageSize`(CPLVirtualMem *ctxt)

  Return the page size associated to a virtual memory mapping.

  The value returned will be at least CPLGetPageSize(), but potentially larger.

  Return

    the page size

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

int `CPLVirtualMemIsAccessThreadSafe`(CPLVirtualMem *ctxt)

  Return TRUE if this memory mapping can be accessed safely from concurrent threads.

  The situation that can cause problems is when several threads try to access a page of the mapping that is not yet mapped.

  The return value of this function depends on whether bSingleThreadUsage has been set of not in CPLVirtualMemNew() and/or the implementation.

  On Linux, this will always return TRUE if bSingleThreadUsage = FALSE.

  Return

    TRUE if this memory mapping can be accessed safely from concurrent threads.

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

void `CPLVirtualMemDeclareThread`(CPLVirtualMem *ctxt)

  Declare that a thread will access a virtual memory mapping.

  This function must be called by a thread that wants to access the content of a virtual memory mapping, except if the virtual memory mapping has been created with bSingleThreadUsage = TRUE.

  This function must be paired with CPLVirtualMemUnDeclareThread().

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

void `CPLVirtualMemUnDeclareThread`(CPLVirtualMem *ctxt)

  Declare that a thread will stop accessing a virtual memory mapping.

  This function must be called by a thread that will no longer access the content of a virtual memory mapping, except if the virtual memory mapping has been created with bSingleThreadUsage = TRUE.

  This function must be paired with CPLVirtualMemDeclareThread().

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

void `CPLVirtualMemPin`(CPLVirtualMem *ctxt, void *pAddr, size_t nSize, int bWriteOp)

  Make sure that a region of virtual memory will be realized.

  Calling this function is not required, but might be useful when debugging a process with tools like gdb or valgrind that do not naturally like segmentation fault signals.

  It is also needed when wanting to provide part of virtual memory mapping to a system call such as read() or write(). If read() or write() is called on a memory region not yet realized, the call will fail with EFAULT.

  Since

    GDAL 1.11

  Parameters

    - `ctxt`: context returned by CPLVirtualMemNew().

    - `pAddr`: the memory region to pin.

    - `nSize`: the size of the memory region.

    - `bWriteOp`: set to TRUE if the memory are will be accessed in write mode.

void `CPLVirtualMemManagerTerminate`(void)

  Cleanup any resource and handlers related to virtual memory.

  This function must be called after the last CPLVirtualMem object has been freed.

  Since

    GDAL 2.0

## cpl_vsi_error.h

Defines

`VSIE_None`

`VSIE_FileError`

`VSIE_HttpError`

`VSIE_AWSError`

`VSIE_AWSAccessDenied`

`VSIE_AWSBucketNotFound`

`VSIE_AWSObjectNotFound`

`VSIE_AWSInvalidCredentials`

`VSIE_AWSSignatureDoesNotMatch`

Typedefs

typedef int `VSIErrorNum`

Functions

void `VSIError`(VSIErrorNum err_no, const char *fmt, ...)

  Report an VSI filesystem error.

  This function records an error in the filesystem that may or may not be used in the future, for example converted into a CPLError. This allows filesystem errors to be available to error handling functionality, but reported only when necessary.

  Parameters

    - `err_no`: the error number (VSIE_*) from cpl_vsi_error.h.

    - `fmt`: a printf() style format string. Any additional arguments will be treated as arguments to fill in this format in a manner similar to printf().

void `VSIErrorReset`(void)

  Erase any traces of previous errors.

  This is used to clear out the latest file system error when it is either translated into a CPLError call or when it is determined to be ignorable.

VSIErrorNum `VSIGetLastErrorNo`(void)

  Fetch the last error number.

  Fetches the last error number posted with VSIError(), that hasn’t been cleared by VSIErrorReset(). This is the error number, not the error class.

  Return

    the error number of the last error to occur, or VSIE_None (0) if there are no posted errors.

const char *`VSIGetLastErrorMsg`(void)

  Get the last error message.

  Fetches the last error message posted with VSIError(), that hasn’t been cleared by VSIErrorReset(). The returned pointer is to an internal string that should not be altered or freed.

  Return

    the last error message, or NULL if there is no posted error message.

int `VSIToCPLError`(CPLErr eErrClass, CPLErrorNum eDefaultErrorNo)

  Translate the VSI error into a CPLError call.

  If there is a VSIError that is set, translate it to a CPLError call with the given CPLErr error class, and either an appropriate CPLErrorNum given the VSIErrorNum, or the given default CPLErrorNum.

  Return

    TRUE if a CPLError was issued, or FALSE if not.

## cpl_vsi.h

Standard C Covers.

The VSI functions are intended to be hookable aliases for Standard C I/O, memory allocation and other system functions. They are intended to allow virtualization of disk I/O so that non file data sources can be made to appear as files, and so that additional error trapping and reporting can be interested. The memory access API is aliased so that special application memory management services can be used.

It is intended that each of these functions retains exactly the same calling pattern as the original Standard C functions they relate to. This means we don’t have to provide custom documentation, and also means that the default implementation is very simple.

Defines

`VSI_ISLNK`(x)

  Test if the file is a symbolic link.

`VSI_ISREG`(x)

  Test if the file is a regular file.

`VSI_ISDIR`(x)

  Test if the file is a directory.

`VSI_L_OFFSET_MAX`

  Maximum value for a file offset.

`VSI_STAT_EXISTS_FLAG`

  Flag provided to VSIStatExL() to test if the file exists.

`VSI_STAT_NATURE_FLAG`

  Flag provided to VSIStatExL() to query the nature (file/dir) of the file.

`VSI_STAT_SIZE_FLAG`

  Flag provided to VSIStatExL() to query the file size.

`VSI_STAT_SET_ERROR_FLAG`

  Flag provided to VSIStatExL() to issue a VSIError in case of failure.

`VSI_MALLOC_ALIGNED_AUTO_VERBOSE`(size)

  VSIMallocAlignedAutoVerbose() with FILE and LINE reporting.

`VSI_MALLOC_VERBOSE`(size)

  VSI_MALLOC_VERBOSE.

`VSI_MALLOC2_VERBOSE`(nSize1, nSize2)

  VSI_MALLOC2_VERBOSE.

`VSI_MALLOC3_VERBOSE`(nSize1, nSize2, nSize3)

  VSI_MALLOC3_VERBOSE.

`VSI_CALLOC_VERBOSE`(nCount, nSize)

  VSI_CALLOC_VERBOSE.

`VSI_REALLOC_VERBOSE`(pOldPtr, nNewSize)

  VSI_REALLOC_VERBOSE.

`VSI_STRDUP_VERBOSE`(pszStr)

  VSI_STRDUP_VERBOSE.

`CPLReadDir`

  Alias of VSIReadDir()

Typedefs

typedef GUIntBig `vsi_l_offset`

  Type for a file offset.

typedef FILE `VSILFILE`

  Opaque type for a FILE that implements the VSIVirtualHandle API.

typedef struct VSI_STAT64_T `VSIStatBufL`

  Type for VSIStatL()

typedef struct VSIDIR `VSIDIR`

  Opaque type for a directory iterator.

typedef size_t (*`VSIWriteFunction`)(const void *ptr, size_t size, size_t nmemb, FILE *stream)

  Callback used by VSIStdoutSetRedirection()

typedef int (*`VSIFilesystemPluginStatCallback`)(void *pUserData, const char *pszFilename, VSIStatBufL *pStatBuf, int nFlags)

  Return information about a handle.

  Optional (driver dependent)

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginUnlinkCallback`)(void *pUserData, const char *pszFilename)

  Remove handle by name.

  Optional

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginRenameCallback`)(void *pUserData, const char *oldpath, const char *newpath)

  Rename handle.

  Optional

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginMkdirCallback`)(void *pUserData, const char *pszDirname, long nMode)

  Create Directory.

  Optional

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginRmdirCallback`)(void *pUserData, const char *pszDirname)

  Delete Directory.

  Optional

  Since

    GDAL 3.0

typedef char **(*`VSIFilesystemPluginReadDirCallback`)(void *pUserData, const char *pszDirname, int nMaxFiles)

  List directory content.

  Optional

  Since

    GDAL 3.0

typedef void *(*`VSIFilesystemPluginOpenCallback`)(void *pUserData, const char *pszFilename, const char *pszAccess)

  Open a handle.

  Mandatory. Returns an opaque pointer that will be used in subsequent file I/O calls. Should return null and/or set errno if the handle does not exist or the access mode is incorrect.

  Since

    GDAL 3.0

typedef vsi_l_offset (*`VSIFilesystemPluginTellCallback`)(void *pFile)

  Return current position in handle.

  Mandatory

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginSeekCallback`)(void *pFile, vsi_l_offset nOffset, int nWhence)

  Seek to position in handle.

  Mandatory except for write only handles

  Since

    GDAL 3.0

typedef size_t (*`VSIFilesystemPluginReadCallback`)(void *pFile, void *pBuffer, size_t nSize, size_t nCount)

  Read data from current position, returns the number of blocks correctly read.

  Mandatory except for write only handles

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginReadMultiRangeCallback`)(void *pFile, int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes)

  Read from multiple offsets.

  Optional, will be replaced by multiple calls to Read() if not provided

  Since

    GDAL 3.0

typedef VSIRangeStatus (*`VSIFilesystemPluginGetRangeStatusCallback`)(void *pFile, vsi_l_offset nOffset, vsi_l_offset nLength)

  Get empty ranges.

  Optional

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginEofCallback`)(void *pFile)

  Has end of file been reached.

  Mandatory? for read handles.

  Since

    GDAL 3.0

typedef size_t (*`VSIFilesystemPluginWriteCallback`)(void *pFile, const void *pBuffer, size_t nSize, size_t nCount)

  Write bytes at current offset.

  Mandatory for writable handles

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginFlushCallback`)(void *pFile)

  Sync written bytes.

  Optional

  Since

    GDAL 3.0

typedef int (*`VSIFilesystemPluginTruncateCallback`)(void *pFile, vsi_l_offset nNewSize)

  Truncate handle.

  Mandatory (driver dependent?) for write handles

typedef int (*`VSIFilesystemPluginCloseCallback`)(void *pFile)

  Close file handle.

  Optional

  Since

    GDAL 3.0

Enums

enum `VSIRangeStatus`

  Range status.

  Values:

  `VSI_RANGE_STATUS_UNKNOWN`

    Unknown.

  `VSI_RANGE_STATUS_DATA`

    Data present.

  `VSI_RANGE_STATUS_HOLE`

    Hole.

Functions

VSILFILE *`VSIFOpenL`(const char *pszFilename, const char *pszAccess)

  Open file.

  This function opens a file with the desired access. Large files (larger than 2GB) should be supported. Binary access is always implied and the “b” does not need to be included in the pszAccess string.

  Note that the “VSILFILE *” returned since GDAL 1.8.0 by this function is NOT a standard C library FILE *, and cannot be used with any functions other than the “VSI*L” family of functions. They aren’t “real” FILE objects.

  On windows it is possible to define the configuration option GDAL_FILE_IS_UTF8 to have pszFilename treated as being in the local encoding instead of UTF-8, restoring the pre-1.8.0 behavior of VSIFOpenL().

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX fopen() function.

  Return

    NULL on failure, or the file handle.

  Parameters

    - `pszFilename`: the file to open. UTF-8 encoded.

    - `pszAccess`: access requested (i.e. “r”, “r+”, “w”)

VSILFILE *`VSIFOpenExL`(const char *pszFilename, const char *pszAccess, int bSetError)

  Open file.

  This function opens a file with the desired access. Large files (larger than 2GB) should be supported. Binary access is always implied and the “b” does not need to be included in the pszAccess string.

  Note that the “VSILFILE *” returned by this function is NOT a standard C library FILE *, and cannot be used with any functions other than the “VSI*L” family of functions. They aren’t “real” FILE objects.

  On windows it is possible to define the configuration option GDAL_FILE_IS_UTF8 to have pszFilename treated as being in the local encoding instead of UTF-8, restoring the pre-1.8.0 behavior of VSIFOpenL().

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX fopen() function.

  Return

    NULL on failure, or the file handle.

  Since

    GDAL 2.1

  Parameters

    - `pszFilename`: the file to open. UTF-8 encoded.

    - `pszAccess`: access requested (i.e. “r”, “r+”, “w”)

    - `bSetError`: flag determining whether or not this open call should set VSIErrors on failure.

int `VSIFCloseL`(VSILFILE *fp)

  Close file.

  This function closes the indicated file.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX fclose() function.

  Return

    0 on success or -1 on failure.

  Parameters

    - `fp`: file handle opened with VSIFOpenL(). Passing a nullptr produces undefined behavior.

int `VSIFSeekL`(VSILFILE *fp, vsi_l_offset nOffset, int nWhence)

  Seek to requested offset.

  Seek to the desired offset (nOffset) in the indicated file.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX fseek() call.

  Caution: vsi_l_offset is a unsigned type, so SEEK_CUR can only be used for positive seek. If negative seek is needed, use VSIFSeekL( fp, VSIFTellL(fp) + negative_offset, SEEK_SET ).

  Return

    0 on success or -1 one failure.

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

    - `nOffset`: offset in bytes.

    - `nWhence`: one of SEEK_SET, SEEK_CUR or SEEK_END.

vsi_l_offset `VSIFTellL`(VSILFILE *fp)

  Tell current file offset.

  Returns the current file read/write offset in bytes from the beginning of the file.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX ftell() call.

  Return

    file offset in bytes.

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

void `VSIRewindL`(VSILFILE *fp)

  Rewind the file pointer to the beginning of the file.

  This is equivalent to VSIFSeekL( fp, 0, SEEK_SET )

  Analog of the POSIX rewind() call.

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

size_t `VSIFReadL`(void *pBuffer, size_t nSize, size_t nCount, VSILFILE *fp)

  Read bytes from file.

  Reads nCount objects of nSize bytes from the indicated file at the current offset into the indicated buffer.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX fread() call.

  Return

    number of objects successfully read.

  Parameters

    - `pBuffer`: the buffer into which the data should be read (at least nCount * nSize bytes in size.

    - `nSize`: size of objects to read in bytes.

    - `nCount`: number of objects to read.

    - `fp`: file handle opened with VSIFOpenL().

int `VSIFReadMultiRangeL`(int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes, VSILFILE *fp)

  Read several ranges of bytes from file.

  Reads nRanges objects of panSizes[i] bytes from the indicated file at the offset panOffsets[i] into the buffer ppData[i].

  Ranges must be sorted in ascending start offset, and must not overlap each other.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory or /vsicurl/.

  Return

    0 in case of success, -1 otherwise.

  Since

    GDAL 1.9.0

  Parameters

    - `nRanges`: number of ranges to read.

    - `ppData`: array of nRanges buffer into which the data should be read (ppData[i] must be at list panSizes[i] bytes).

    - `panOffsets`: array of nRanges offsets at which the data should be read.

    - `panSizes`: array of nRanges sizes of objects to read (in bytes).

    - `fp`: file handle opened with VSIFOpenL().

size_t `VSIFWriteL`(const void *pBuffer, size_t nSize, size_t nCount, VSILFILE *fp)

  Write bytes to file.

  Writess nCount objects of nSize bytes to the indicated file at the current offset into the indicated buffer.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX fwrite() call.

  Return

    number of objects successfully written.

  Parameters

    - `pBuffer`: the buffer from which the data should be written (at least nCount * nSize bytes in size.

    - `nSize`: size of objects to read in bytes.

    - `nCount`: number of objects to read.

    - `fp`: file handle opened with VSIFOpenL().

int `VSIFEofL`(VSILFILE *fp)

  Test for end of file.

  Returns TRUE (non-zero) if an end-of-file condition occurred during the previous read operation. The end-of-file flag is cleared by a successful VSIFSeekL() call.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX feof() call.

  Return

    TRUE if at EOF else FALSE.

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

int `VSIFTruncateL`(VSILFILE *fp, vsi_l_offset nNewSize)

  Truncate/expand the file to the specified size.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX ftruncate() call.

  Return

    0 on success

  Since

    GDAL 1.9.0

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

    - `nNewSize`: new size in bytes.

int `VSIFFlushL`(VSILFILE *fp)

  Flush pending writes to disk.

  For files in write or update mode and on filesystem types where it is applicable, all pending output on the file is flushed to the physical disk.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX fflush() call.

  Return

    0 on success or -1 on error.

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

int `VSIFPrintfL`(VSILFILE *fp, const char *pszFormat, ...)

  Formatted write to file.

  Provides fprintf() style formatted output to a VSI*L file. This formats an internal buffer which is written using VSIFWriteL().

  Analog of the POSIX fprintf() call.

  Return

    the number of bytes written or -1 on an error.

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

    - `pszFormat`: the printf() style format string.

int `VSIFPutcL`(int nChar, VSILFILE *fp)

  Write a single byte to the file.

  Writes the character nChar, cast to an unsigned char, to file.

  Almost an analog of the POSIX fputc() call, except that it returns the number of character written (1 or 0), and not the (cast) character itself or EOF.

  Return

    1 in case of success, 0 on error.

  Parameters

    - `nChar`: character to write.

    - `fp`: file handle opened with VSIFOpenL().

VSIRangeStatus `VSIFGetRangeStatusL`(VSILFILE *fp, vsi_l_offset nStart, vsi_l_offset nLength)

  Return if a given file range contains data or holes filled with zeroes.

  This uses the filesystem capabilities of querying which regions of a sparse file are allocated or not. This is currently only implemented for Linux (and no other Unix derivatives) and Windows.

  Note: A return of VSI_RANGE_STATUS_DATA doesn’t exclude that the extent is filled with zeroes! It must be interpreted as “may

  contain non-zero data”.

  Return

    extent status: VSI_RANGE_STATUS_UNKNOWN, VSI_RANGE_STATUS_DATA or VSI_RANGE_STATUS_HOLE

  Since

    GDAL 2.2

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

    - `nOffset`: offset of the start of the extent.

    - `nLength`: extent length.

int `VSIIngestFile`(VSILFILE *fp, const char *pszFilename, GByte **ppabyRet, vsi_l_offset *pnSize, GIntBig nMaxSize)

  Ingest a file into memory.

  Read the whole content of a file into a memory buffer.

  Either fp or pszFilename can be NULL, but not both at the same time.

  If fp is passed non-NULL, it is the responsibility of the caller to close it.

  If non-NULL, the returned buffer is guaranteed to be NUL-terminated.

  Return

    TRUE in case of success.

  Since

    GDAL 1.11

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

    - `pszFilename`: filename.

    - `ppabyRet`: pointer to the target buffer. *ppabyRet must be freed with VSIFree()

    - `pnSize`: pointer to variable to store the file size. May be NULL.

    - `nMaxSize`: maximum size of file allowed. If no limit, set to a negative value.

int `VSIOverwriteFile`(VSILFILE *fpTarget, const char *pszSourceFilename)

  Overwrite an existing file with content from another one.

  Return

    TRUE in case of success.

  Since

    GDAL 3.1

  Parameters

    - `fpTarget`: file handle opened with VSIFOpenL() with “rb+” flag.

    - `pszSourceFilename`: source filename

int `VSIStatL`(const char *pszFilename, VSIStatBufL *psStatBuf)

  Get filesystem object info.

  Fetches status information about a filesystem object (file, directory, etc). The returned information is placed in the VSIStatBufL structure. For portability, only use the st_size (size in bytes) and st_mode (file type). This method is similar to VSIStat(), but will work on large files on systems where this requires special calls.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX stat() function.

  Return

    0 on success or -1 on an error.

  Parameters

    - `pszFilename`: the path of the filesystem object to be queried. UTF-8 encoded.

    - `psStatBuf`: the structure to load with information.

int `VSIStatExL`(const char *pszFilename, VSIStatBufL *psStatBuf, int nFlags)

  Get filesystem object info.

  Fetches status information about a filesystem object (file, directory, etc). The returned information is placed in the VSIStatBufL structure. For portability, only use the st_size (size in bytes) and st_mode (file type). This method is similar to VSIStat(), but will work on large files on systems where this requires special calls.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX stat() function, with an extra parameter to specify which information is needed, which offers a potential for speed optimizations on specialized and potentially slow virtual filesystem objects (/vsigzip/, /vsicurl/)

  Return

    0 on success or -1 on an error.

  Since

    GDAL 1.8.0

  Parameters

    - `pszFilename`: the path of the filesystem object to be queried. UTF-8 encoded.

    - `psStatBuf`: the structure to load with information.

    - `nFlags`: 0 to get all information, or VSI_STAT_EXISTS_FLAG, VSI_STAT_NATURE_FLAG or VSI_STAT_SIZE_FLAG, or a combination of those to get partial info.

int `VSIIsCaseSensitiveFS`(const char *pszFilename)

  Returns if the filenames of the filesystem are case sensitive.

  This method retrieves to which filesystem belongs the passed filename and return TRUE if the filenames of that filesystem are case sensitive.

  Currently, this will return FALSE only for Windows real filenames. Other VSI virtual filesystems are case sensitive.

  This methods avoid ugly #ifndef WIN32 / #endif code, that is wrong when dealing with virtual filenames.

  Return

    TRUE if the filenames of the filesystem are case sensitive.

  Since

    GDAL 1.8.0

  Parameters

    - `pszFilename`: the path of the filesystem object to be tested. UTF-8 encoded.

int `VSISupportsSparseFiles`(const char *pszPath)

  Returns if the filesystem supports sparse files.

  Only supported on Linux (and no other Unix derivatives) and Windows. On Linux, the answer depends on a few hardcoded signatures for common filesystems. Other filesystems will be considered as not supporting sparse files.

  Return

    TRUE if the file system is known to support sparse files. FALSE may be returned both in cases where it is known to not support them, or when it is unknown.

  Since

    GDAL 2.2

  Parameters

    - `pszPath`: the path of the filesystem object to be tested. UTF-8 encoded.

int `VSIHasOptimizedReadMultiRange`(const char *pszPath)

  Returns if the filesystem supports efficient multi-range reading.

  Currently only returns TRUE for /vsicurl/ and derived file systems.

  Return

    TRUE if the file system is known to have an efficient multi-range reading.

  Since

    GDAL 2.3

  Parameters

    - `pszPath`: the path of the filesystem object to be tested. UTF-8 encoded.

const char *`VSIGetActualURL`(const char *pszFilename)

  Returns the actual URL of a supplied filename.

  Currently only returns a non-NULL value for network-based virtual file systems. For example “/vsis3/bucket/filename” will be expanded as “https://bucket.s3.amazon.com/filename”

  Note that the lifetime of the returned string, is short, and may be invalidated by any following GDAL functions.

  Return

    the actual URL corresponding to the supplied filename, or NULL. Should not be freed.

  Since

    GDAL 2.3

  Parameters

    - `pszFilename`: the path of the filesystem object. UTF-8 encoded.

char *`VSIGetSignedURL`(const char *pszFilename, CSLConstList papszOptions)

  Returns a signed URL of a supplied filename.

  Currently only returns a non-NULL value for /vsis3/, /vsigs/, /vsiaz/ and /vsioss/ For example “/vsis3/bucket/filename” will be expanded as “https://bucket.s3.amazon.com/filename?X-Amz-Algorithm=AWS4-HMAC-SHA256…” Configuration options that apply for file opening (typically to provide credentials), and are returned by VSIGetFileSystemOptions(), are also valid in that context.

  /vsiaz/ supports additional options:

  - SIGNEDIDENTIFIER=value: to relate the given shared access signature to a corresponding stored access policy.

  - SIGNEDPERMISSIONS=r|w: permissions associated with the shared access signature. Normally deduced from VERB.

  Parameters

    - `pszFilename`: the path of the filesystem object. UTF-8 encoded.

    - `papszOptions`: list of options, or NULL. Depend on file system handler. For /vsis3/, /vsigs/, /vsiaz/ and /vsioss/, the following options are supported:

      - START_DATE=YYMMDDTHHMMSSZ: date and time in UTC following ISO 8601 standard, corresponding to the start of validity of the URL. If not specified, current date time.

      - EXPIRATION_DELAY=number_of_seconds: number between 1 and 604800 (seven days) for the validity of the signed URL. Defaults to 3600 (one hour)

      - VERB=GET/HEAD/DELETE/PUT/POST: HTTP VERB for which the request will be used. Default to GET.

  Return

    a signed URL, or NULL. Should be freed with CPLFree().

  Since

    GDAL 2.3

const char *`VSIGetFileSystemOptions`(const char *pszFilename)

  Return the list of options associated with a virtual file system handler as a serialized XML string.

  Those options may be set as configuration options with CPLSetConfigOption().

  Return

    a string, which must not be freed, or NULL if no options is declared.

  Since

    GDAL 2.3

  Parameters

    - `pszFilename`: a filename, or prefix of a virtual file system handler.

char **`VSIGetFileSystemsPrefixes`(void)

  Return the list of prefixes for virtual file system handlers currently registered.

  Typically: “”, “/vsimem/”, “/vsicurl/”, etc

  Return

    a NULL terminated list of prefixes. Must be freed with CSLDestroy()

  Since

    GDAL 2.3

void *`VSIFGetNativeFileDescriptorL`(VSILFILE *fp)

  Returns the “native” file descriptor for the virtual handle.

  This will only return a non-NULL value for “real” files handled by the operating system (to be opposed to GDAL virtual file systems).

  On POSIX systems, this will be a integer value (“fd”) cast as a void*. On Windows systems, this will be the HANDLE.

  Return

    the native file descriptor, or NULL.

  Parameters

    - `fp`: file handle opened with VSIFOpenL().

char **`VSIGetFileMetadata`(const char *pszFilename, const char *pszDomain, CSLConstList papszOptions)

  Get metadata on files.

  Implemented currently only for network-like filesystems.

  Return

    a NULL-terminated list of key=value strings, to be freed with CSLDestroy() or NULL in case of error / empty list.

  Since

    GDAL 3.1.0

  Parameters

    - `pszFilename`: the path of the filesystem object to be queried. UTF-8 encoded.

    - `pszDomain`: Metadata domain to query. Depends on the file system. The following are supported:

      - HEADERS: to get HTTP headers for network-like filesystems (/vsicurl/, /vsis3/, etc)

      - TAGS: specific to /vsis3/: to get S3 Object tagging information

    - `papszOptions`: Unused. Should be set to NULL.

int `VSISetFileMetadata`(const char *pszFilename, CSLConstList papszMetadata, const char *pszDomain, CSLConstList papszOptions)

  Set metadata on files.

  Implemented currently only for /vsis3/

  Return

    TRUE in case of success.

  Since

    GDAL 3.1.0

  Parameters

    - `pszFilename`: the path of the filesystem object to be queried. UTF-8 encoded.

    - `papszMetadata`: NULL-terminated list of key=value strings.

    - `pszDomain`: Metadata domain to set. Depends on the file system. The following are supported:

      - HEADERS: to set HTTP header

      - TAGS: to set S3 Object tagging information

    - `papszOptions`: Unused. Should be set to NULL.

void *`VSICalloc`(size_t nCount, size_t nSize)

  Analog of calloc().

  Use VSIFree() to free

void *`VSIMalloc`(size_t nSize)

  Analog of malloc().

  Use VSIFree() to free

void `VSIFree`(void *)

  Analog of free() for data allocated with VSIMalloc(), VSICalloc(), VSIRealloc()

void *`VSIRealloc`(void *pData, size_t nNewSize)

  Analog of realloc().

  Use VSIFree() to free

char *`VSIStrdup`(const char *pszString)

  Analog of strdup().

  Use VSIFree() to free

void *`VSIMallocAligned`(size_t nAlignment, size_t nSize)

  Allocates a buffer with an alignment constraint.

  The return value must be freed with VSIFreeAligned().

  Return

    a buffer aligned on nAlignment and of size nSize, or NULL

  Since

    GDAL 2.2

  Parameters

    - `nAlignment`: Must be a power of 2, multiple of sizeof(void*), and lesser than 256.

    - `nSize`: Size of the buffer to allocate.

void *`VSIMallocAlignedAuto`(size_t nSize)

  Allocates a buffer with an alignment constraint such that it can be used by the most demanding vector instruction set on that platform.

  The return value must be freed with VSIFreeAligned().

  Return

    an aligned buffer of size nSize, or NULL

  Since

    GDAL 2.2

  Parameters

    - `nSize`: Size of the buffer to allocate.

void `VSIFreeAligned`(void *ptr)

  Free a buffer allocated with VSIMallocAligned().

  Since

    GDAL 2.2

  Parameters

    - `ptr`: Buffer to free.

void *`VSIMallocAlignedAutoVerbose`(size_t nSize, const char *pszFile, int nLine)

  See VSIMallocAlignedAuto()

void *`VSIMalloc2`(size_t nSize1, size_t nSize2)

  VSIMalloc2 allocates (nSize1 * nSize2) bytes.

  In case of overflow of the multiplication, or if memory allocation fails, a NULL pointer is returned and a CE_Failure error is raised with CPLError(). If nSize1 == 0 || nSize2 == 0, a NULL pointer will also be returned. CPLFree() or VSIFree() can be used to free memory allocated by this function.

void *`VSIMalloc3`(size_t nSize1, size_t nSize2, size_t nSize3)

  VSIMalloc3 allocates (nSize1 * nSize2 * nSize3) bytes.

  In case of overflow of the multiplication, or if memory allocation fails, a NULL pointer is returned and a CE_Failure error is raised with CPLError(). If nSize1 == 0 || nSize2 == 0 || nSize3 == 0, a NULL pointer will also be returned. CPLFree() or VSIFree() can be used to free memory allocated by this function.

void *`VSIMallocVerbose`(size_t nSize, const char *pszFile, int nLine)

  VSIMallocVerbose.

void *`VSIMalloc2Verbose`(size_t nSize1, size_t nSize2, const char *pszFile, int nLine)

  VSIMalloc2Verbose.

void *`VSIMalloc3Verbose`(size_t nSize1, size_t nSize2, size_t nSize3, const char *pszFile, int nLine)

  VSIMalloc3Verbose.

void *`VSICallocVerbose`(size_t nCount, size_t nSize, const char *pszFile, int nLine)

  VSICallocVerbose.

void *`VSIReallocVerbose`(void *pOldPtr, size_t nNewSize, const char *pszFile, int nLine)

  VSIReallocVerbose.

char *`VSIStrdupVerbose`(const char *pszStr, const char *pszFile, int nLine)

  VSIStrdupVerbose.

GIntBig `CPLGetPhysicalRAM`(void)

  Return the total physical RAM in bytes.

  In the context of a container using cgroups (typically Docker), this will take into account that limitation (starting with GDAL 2.4.0)

  You should generally use CPLGetUsablePhysicalRAM() instead.

  Return

    the total physical RAM in bytes (or 0 in case of failure).

  Since

    GDAL 2.0

GIntBig `CPLGetUsablePhysicalRAM`(void)

  Return the total physical RAM, usable by a process, in bytes.

  This is the same as CPLGetPhysicalRAM() except it will limit to 2 GB for 32 bit processes.

  Starting with GDAL 2.4.0, it will also take account resource limits on Posix systems.

  Note: This memory may already be partly used by other processes.

  Return

    the total physical RAM, usable by a process, in bytes (or 0 in case of failure).

  Since

    GDAL 2.0

char **`VSIReadDir`(const char *pszPath)

  Read names in a directory.

  This function abstracts access to directory contains. It returns a list of strings containing the names of files, and directories in this directory. The resulting string list becomes the responsibility of the application and should be freed with CSLDestroy() when no longer needed.

  Note that no error is issued via CPLError() if the directory path is invalid, though NULL is returned.

  This function used to be known as CPLReadDir(), but the old name is now deprecated.

  Return

    The list of entries in the directory, or NULL if the directory doesn’t exist. Filenames are returned in UTF-8 encoding.

  Parameters

    - `pszPath`: the relative, or absolute path of a directory to read. UTF-8 encoded.

char **`VSIReadDirRecursive`(const char *pszPath)

  Read names in a directory recursively.

  This function abstracts access to directory contents and subdirectories. It returns a list of strings containing the names of files and directories in this directory and all subdirectories. The resulting string list becomes the responsibility of the application and should be freed with CSLDestroy() when no longer needed.

  Note that no error is issued via CPLError() if the directory path is invalid, though NULL is returned.

  Return

    The list of entries in the directory and subdirectories or NULL if the directory doesn’t exist. Filenames are returned in UTF-8 encoding.

  Since

    GDAL 1.10.0

  Parameters

    - `pszPathIn`: the relative, or absolute path of a directory to read. UTF-8 encoded.

char **`VSIReadDirEx`(const char *pszPath, int nMaxFiles)

  Read names in a directory.

  This function abstracts access to directory contains. It returns a list of strings containing the names of files, and directories in this directory. The resulting string list becomes the responsibility of the application and should be freed with CSLDestroy() when no longer needed.

  Note that no error is issued via CPLError() if the directory path is invalid, though NULL is returned.

  If nMaxFiles is set to a positive number, directory listing will stop after that limit has been reached. Note that to indicate truncate, at least one element more than the nMaxFiles limit will be returned. If CSLCount() on the result is lesser or equal to nMaxFiles, then no truncation occurred.

  Return

    The list of entries in the directory, or NULL if the directory doesn’t exist. Filenames are returned in UTF-8 encoding.

  Since

    GDAL 2.1

  Parameters

    - `pszPath`: the relative, or absolute path of a directory to read. UTF-8 encoded.

    - `nMaxFiles`: maximum number of files after which to stop, or 0 for no limit.

VSIDIR *`VSIOpenDir`(const char *pszPath, int nRecurseDepth, const char *const *papszOptions)

  Open a directory to read its entries.

  This function is close to the POSIX opendir() function.

  For /vsis3/, /vsigs/, /vsioss/ and /vsiaz/, this function has an efficient implementation, minimizing the number of network requests, when invoked with nRecurseDepth <= 0.

  Entries are read by calling VSIGetNextDirEntry() on the handled returned by that function, until it returns NULL. VSICloseDir() must be called once done with the returned directory handle.

  Return

    a handle, or NULL in case of error

  Since

    GDAL 2.4

  Parameters

    - `pszPath`: the relative, or absolute path of a directory to read. UTF-8 encoded.

    - `nRecurseDepth`: 0 means do not recurse in subdirectories, 1 means recurse only in the first level of subdirectories, etc. -1 means unlimited recursion level

    - `papszOptions`: NULL terminated list of options, or NULL.

const VSIDIREntry *`VSIGetNextDirEntry`(VSIDIR *dir)

  Return the next entry of the directory.

  This function is close to the POSIX readdir() function. It actually returns more information (file size, last modification time), which on ‘real’ file systems involve one ‘stat’ call per file.

  For filesystems that can have both a regular file and a directory name of the same name (typically /vsis3/), when this situation of duplicate happens, the directory name will be suffixed by a slash character. Otherwise directory names are not suffixed by slash.

  The returned entry remains valid until the next call to VSINextDirEntry() or VSICloseDir() with the same handle.

  Return

    a entry, or NULL if there is no more entry in the directory. This return value must not be freed.

  Since

    GDAL 2.4

  Parameters

    - `dir`: Directory handled returned by VSIOpenDir(). Must not be NULL.

void `VSICloseDir`(VSIDIR *dir)

  Close a directory.

  This function is close to the POSIX closedir() function.

  Since

    GDAL 2.4

  Parameters

    - `dir`: Directory handled returned by VSIOpenDir().

int `VSIMkdir`(const char *pszPathname, long mode)

  Create a directory.

  Create a new directory with the indicated mode. The mode is ignored on some platforms. A reasonable default mode value would be 0666. This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX mkdir() function.

  Return

    0 on success or -1 on an error.

  Parameters

    - `pszPathname`: the path to the directory to create. UTF-8 encoded.

    - `mode`: the permissions mode.

int `VSIMkdirRecursive`(const char *pszPathname, long mode)

  Create a directory and all its ancestors.

  Return

    0 on success or -1 on an error.

  Since

    GDAL 2.3

  Parameters

    - `pszPathname`: the path to the directory to create. UTF-8 encoded.

    - `mode`: the permissions mode.

int `VSIRmdir`(const char *pszDirname)

  Delete a directory.

  Deletes a directory object from the file system. On some systems the directory must be empty before it can be deleted.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX rmdir() function.

  Return

    0 on success or -1 on an error.

  Parameters

    - `pszDirname`: the path of the directory to be deleted. UTF-8 encoded.

int `VSIRmdirRecursive`(const char *pszDirname)

  Delete a directory recursively.

  Deletes a directory object and its content from the file system.

  Starting with GDAL 3.1, /vsis3/ has an efficient implementation of this function.

  Return

    0 on success or -1 on an error.

  Since

    GDAL 2.3

int `VSIUnlink`(const char *pszFilename)

  Delete a file.

  Deletes a file object from the file system.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX unlink() function.

  Return

    0 on success or -1 on an error.

  Parameters

    - `pszFilename`: the path of the file to be deleted. UTF-8 encoded.

int *`VSIUnlinkBatch`(CSLConstList papszFiles)

  Delete several files, possibly in a batch.

  All files should belong to the same file system handler.

  Return

    an array of size CSLCount(papszFiles), whose values are TRUE or FALSE depending on the success of deletion of the corresponding file. The array should be freed with VSIFree(). NULL might be return in case of a more general error (for example, files belonging to different file system handlers)

  Since

    GDAL 3.1

  Parameters

    - `papszFiles`: NULL terminated list of files. UTF-8 encoded.

int `VSIRename`(const char *oldpath, const char *newpath)

  Rename a file.

  Renames a file object in the file system. It should be possible to rename a file onto a new filesystem, but it is safest if this function is only used to rename files that remain in the same directory.

  This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

  Analog of the POSIX rename() function.

  Return

    0 on success or -1 on an error.

  Parameters

    - `oldpath`: the name of the file to be renamed. UTF-8 encoded.

    - `newpath`: the name the file should be given. UTF-8 encoded.

int `VSISync`(const char *pszSource, const char *pszTarget, const char *const *papszOptions, GDALProgressFunc pProgressFunc, void *pProgressData, char ***ppapszOutputs)

  Synchronize a source file/directory with a target file/directory.

  This is a analog of the ‘rsync’ utility. In the current implementation, rsync would be more efficient for local file copying, but VSISync() main interest is when the source or target is a remote file system like /vsis3/ or /vsigs/, in which case it can take into account the timestamps of the files (or optionally the ETag/MD5Sum) to avoid unneeded copy operations.

  This is only implemented efficiently for:

  - local filesystem <> remote filesystem.

  - remote filesystem <> remote filesystem (starting with GDAL 3.1). Where the source and target remote filesystems are the same and one of /vsis3/, /vsigs/ or /vsiaz/

  Similarly to rsync behaviour, if the source filename ends with a slash, it means that the content of the directory must be copied, but not the directory name. For example, assuming “/home/even/foo” contains a file “bar”, VSISync(“/home/even/foo/”, “/mnt/media”, …) will create a “/mnt/media/bar” file. Whereas VSISync(“/home/even/foo”, “/mnt/media”, …) will create a “/mnt/media/foo” directory which contains a bar file.

  Return

    TRUE on success or FALSE on an error.

  Since

    GDAL 2.4

  Parameters

    - `pszSource`: Source file or directory. UTF-8 encoded.

    - `pszTarget`: Target file or direcotry. UTF-8 encoded.

    - `papszOptions`: Null terminated list of options, or NULL. Currently accepted options are:

      - RECURSIVE=NO (the default is YES)

      - SYNC_STRATEGY=TIMESTAMP/ETAG. Determines which criterion is used to determine if a target file must be replaced when it already exists and has the same file size as the source. Only applies for a source or target being a network filesystem.

        The default is TIMESTAMP (similarly to how ‘aws s3 sync’ works), that is to say that for an upload operation, a remote file is replaced if it has a different size or if it is older than the source. For a download operation, a local file is replaced if it has a different size or if it is newer than the remote file.

        The ETAG strategy assumes that the ETag metadata of the remote file is the MD5Sum of the file content, which is only true in the case of /vsis3/ for files not using KMS server side encryption and uploaded in a single PUT operation (so smaller than 50 MB given the default used by GDAL). Only to be used for /vsis3/, /vsigs/ or other filesystems using a MD5Sum as ETAG.

      - NUM_THREADS=integer. Number of threads to use for parallel file copying. Only use for when /vsis3/, /vsigs/ or /vsiaz/ is in source or target. Since GDAL 3.1

      - CHUNK_SIZE=integer. Maximum size of chunk (in bytes) to use to split large objects when downloading them from /vsis3/, /vsigs/ or /vsiaz/ to local file system, or for upload to /vsis3/ from local file system. Only used if NUM_THREADS > 1. For upload to /vsis3/, this chunk size will be set at least to 5 MB. Since GDAL 3.1

    - `pProgressFunc`: Progress callback, or NULL.

    - `pProgressData`: User data of progress callback, or NULL.

    - `ppapszOutputs`: Unused. Should be set to NULL for now.

char *`VSIStrerror`(int nErrno)

  Return the error string corresponding to the error number.

  Do not free it

GIntBig `VSIGetDiskFreeSpace`(const char *pszDirname)

  Return free disk space available on the filesystem.

  This function returns the free disk space available on the filesystem.

  Return

    The free space in bytes. Or -1 in case of error.

  Since

    GDAL 2.1

  Parameters

    - `pszDirname`: a directory of the filesystem to query.

void `VSIInstallMemFileHandler`(void)

  Install “memory” file system handler.

  A special file handler is installed that allows block of memory to be treated as files. All portions of the file system underneath the base path “/vsimem/” will be handled by this driver.

  Normal VSI*L functions can be used freely to create and destroy memory arrays treating them as if they were real file system objects. Some additional methods exist to efficient create memory file system objects without duplicating original copies of the data or to “steal” the block of memory associated with a memory file.

  Directory related functions are supported.

  This code example demonstrates using GDAL to translate from one memory buffer to another.

      GByte *ConvertBufferFormat( GByte *pabyInData, vsi_l_offset nInDataLength,
                                  vsi_l_offset *pnOutDataLength )
      {
          // create memory file system object from buffer.
          VSIFCloseL( VSIFileFromMemBuffer( "/vsimem/work.dat", pabyInData,
                                            nInDataLength, FALSE ) );

          // Open memory buffer for read.
          GDALDatasetH hDS = GDALOpen( "/vsimem/work.dat", GA_ReadOnly );

          // Get output format driver.
          GDALDriverH hDriver = GDALGetDriverByName( "GTiff" );
          GDALDatasetH hOutDS;

          hOutDS = GDALCreateCopy( hDriver, "/vsimem/out.tif", hDS, TRUE, NULL,
                                   NULL, NULL );

          // close source file, and "unlink" it.
          GDALClose( hDS );
          VSIUnlink( "/vsimem/work.dat" );

          // seize the buffer associated with the output file.

          return VSIGetMemFileBuffer( "/vsimem/out.tif", pnOutDataLength, TRUE );
      }

void `VSIInstallSubFileHandler`(void)

  Install /vsisubfile/ virtual file handler.

  See

    /vsisubfile/ documentation

void `VSIInstallCurlFileHandler`(void)

  Install /vsicurl/ HTTP/FTP file system handler (requires libcurl)

  See

    /vsicurl/ documentation

  Since

    GDAL 1.8.0

void `VSICurlClearCache`(void)

  Clean local cache associated with /vsicurl/ (and related file systems)

  /vsicurl (and related file systems like /vsis3/, /vsigs/, /vsiaz/, /vsioss/, /vsiswift/) cache a number of metadata and data for faster execution in read-only scenarios. But when the content on the server-side may change during the same process, those mechanisms can prevent opening new files, or give an outdated version of them.

  Since

    GDAL 2.2.1

void `VSICurlPartialClearCache`(const char *pszFilenamePrefix)

  Clean local cache associated with /vsicurl/ (and related file systems) for a given filename (and its subfiles and subdirectories if it is a directory)

  /vsicurl (and related file systems like /vsis3/, /vsigs/, /vsiaz/, /vsioss/, /vsiswift/) cache a number of metadata and data for faster execution in read-only scenarios. But when the content on the server-side may change during the same process, those mechanisms can prevent opening new files, or give an outdated version of them.

  Since

    GDAL 2.4.0

  Parameters

    - `pszFilenamePrefix`: Filename prefix

void `VSIInstallCurlStreamingFileHandler`(void)

  Install /vsicurl_streaming/ HTTP/FTP file system handler (requires libcurl).

  See

    /vsicurl_streaming/ documentation

  Since

    GDAL 1.10

void `VSIInstallS3FileHandler`(void)

  Install /vsis3/ Amazon S3 file system handler (requires libcurl)

  See

    /vsis3/ documentation

  Since

    GDAL 2.1

void `VSIInstallS3StreamingFileHandler`(void)

  Install /vsis3_streaming/ Amazon S3 file system handler (requires libcurl).

  See

    /vsis3_streaming/ documentation

  Since

    GDAL 2.1

void `VSIInstallGSFileHandler`(void)

  Install /vsigs/ Google Cloud Storage file system handler (requires libcurl)

  See

    /vsigs/ documentation

  Since

    GDAL 2.2

void `VSIInstallGSStreamingFileHandler`(void)

  Install /vsigs_streaming/ Google Cloud Storage file system handler (requires libcurl)

  See

    /vsigs_streaming/ documentation

  Since

    GDAL 2.2

void `VSIInstallAzureFileHandler`(void)

  Install /vsiaz/ Microsoft Azure Blob file system handler (requires libcurl)

  See

    /vsiaz/ documentation

  Since

    GDAL 2.3

void `VSIInstallAzureStreamingFileHandler`(void)

  Install /vsiaz_streaming/ Microsoft Azure Blob file system handler (requires libcurl)

  See

    /vsiaz_streaming/ documentation1

  Since

    GDAL 2.3

void `VSIInstallOSSFileHandler`(void)

  Install /vsioss/ Alibaba Cloud Object Storage Service (OSS) file system handler (requires libcurl)

  See

    /vsioss/ documentation

  Since

    GDAL 2.3

void `VSIInstallOSSStreamingFileHandler`(void)

  Install /vsioss_streaming/ Alibaba Cloud Object Storage Service (OSS) file system handler (requires libcurl)

  See

    /vsioss_streaming/ documentation

  Since

    GDAL 2.3

void `VSIInstallSwiftFileHandler`(void)

  Install /vsiswift/ OpenStack Swif Object Storage (Swift) file system handler (requires libcurl)

  See

    /vsiswift/ documentation

  Since

    GDAL 2.3

void `VSIInstallSwiftStreamingFileHandler`(void)

  Install /vsiswift_streamin/ OpenStack Swif Object Storage (Swift) file system handler (requires libcurl)

  See

    /vsiswift_streaming/ documentation

  Since

    GDAL 2.3

void `VSIInstallGZipFileHandler`(void)

  Install GZip file system handler.

  A special file handler is installed that allows reading on-the-fly and writing in GZip (.gz) files.

  All portions of the file system underneath the base path “/vsigzip/” will be handled by this driver.

  Additional documentation is to be found at: http://trac.osgeo.org/gdal/wiki/UserDocs/ReadInZip

  Since

    GDAL 1.6.0

void `VSIInstallZipFileHandler`(void)

  Install ZIP file system handler.

  A special file handler is installed that allows reading on-the-fly in ZIP (.zip) archives.

  All portions of the file system underneath the base path “/vsizip/” will be handled by this driver.

  The syntax to open a file inside a zip file is /vsizip/path/to/the/file.zip/path/inside/the/zip/file where path/to/the/file.zip is relative or absolute and path/inside/the/zip/file is the relative path to the file inside the archive.

  Starting with GDAL 2.2, an alternate syntax is available so as to enable chaining and not being dependent on .zip extension : /vsizip/{/path/to/the/archive}/path/inside/the/zip/file. Note that /path/to/the/archive may also itself use this alternate syntax.

  If the path is absolute, it should begin with a / on a Unix-like OS (or C:\ on Windows), so the line looks like /vsizip//home/gdal/… For example gdalinfo /vsizip/myarchive.zip/subdir1/file1.tif

  Syntactic sugar : if the .zip file contains only one file located at its root, just mentioning “/vsizip/path/to/the/file.zip” will work

  VSIStatL() will return the uncompressed size in st_size member and file nature- file or directory - in st_mode member.

  Directory listing is available through VSIReadDir().

  Since GDAL 1.8.0, write capabilities are available. They allow creating a new zip file and adding new files to an already existing (or just created) zip file. Read and write operations cannot be interleaved : the new zip must be closed before being re-opened for read.

  Additional documentation is to be found at http://trac.osgeo.org/gdal/wiki/UserDocs/ReadInZip

  Since

    GDAL 1.6.0

void `VSIInstallStdinHandler`(void)

  Install /vsistdin/ file system handler.

  A special file handler is installed that allows reading from the standard input stream.

  The file operations available are of course limited to Read() and forward Seek() (full seek in the first MB of a file).

  Since

    GDAL 1.8.0

void `VSIInstallHdfsHandler`(void)

  Install /vsihdfs/ file system handler (requires JVM and HDFS support)

  Since

    GDAL 2.4.0

void `VSIInstallWebHdfsHandler`(void)

  Install /vsiwebhdfs/ WebHDFS (Hadoop File System) REST API file system handler (requires libcurl)

  See

    /vsiwebhdfs/ documentation

  Since

    GDAL 2.4

void `VSIInstallStdoutHandler`(void)

  Install /vsistdout/ file system handler.

  A special file handler is installed that allows writing to the standard output stream.

  The file operations available are of course limited to Write().

  A variation of this file system exists as the /vsistdout_redirect/ file system handler, where the output function can be defined with VSIStdoutSetRedirection().

  Since

    GDAL 1.8.0

void `VSIInstallSparseFileHandler`(void)

  Install /vsisparse/ virtual file handler.

  See

    /vsisparse/ documentation

void `VSIInstallTarFileHandler`(void)

  Install /vsitar/ file system handler.

  A special file handler is installed that allows reading on-the-fly in TAR (regular .tar, or compressed .tar.gz/.tgz) archives.

  All portions of the file system underneath the base path “/vsitar/” will be handled by this driver.

  The syntax to open a file inside a tar file is /vsitar/path/to/the/file.tar/path/inside/the/tar/file were path/to/the/file.tar is relative or absolute and path/inside/the/tar/file is the relative path to the file inside the archive.

  Starting with GDAL 2.2, an alternate syntax is available so as to enable chaining and not being dependent on .tar extension : /vsitar/{/path/to/the/archive}/path/inside/the/tar/file. Note that /path/to/the/archive may also itself this alternate syntax.

  If the path is absolute, it should begin with a / on a Unix-like OS (or C:\ on Windows), so the line looks like /vsitar//home/gdal/… For example gdalinfo /vsitar/myarchive.tar/subdir1/file1.tif

  Syntactic sugar : if the tar archive contains only one file located at its root, just mentionning “/vsitar/path/to/the/file.tar” will work

  VSIStatL() will return the uncompressed size in st_size member and file nature- file or directory - in st_mode member.

  Directory listing is available through VSIReadDir().

  Since

    GDAL 1.8.0

void `VSIInstallCryptFileHandler`(void)

  Install /vsicrypt/ encrypted file system handler (requires libcrypto++)

  A special file handler is installed that allows reading/creating/update encrypted files on the fly, with random access capabilities.

  The cryptographic algorithms used are block ciphers, with symmetric key.

  In their simplest form, recognized filenames are of the form /vsicrypt//absolute_path/to/file, /vsicrypt/c:/absolute_path/to/file or /vsicrypt/relative/path/to/file.

  Options can also be used with the following format : /vsicrypt/option1=val1,option2=val2,…,file=/path/to/file

  They can also be passed as configuration option/environment variable, because in some use cases, the syntax with option in the filename might not properly work with some drivers.

  In all modes, the encryption key must be provided. There are several ways of doing so :

  - By adding a key= parameter to the filename, like /vsicrypt/key=my_secret_key,file=/path/to/file. Note that this restricts the key to be in text format, whereas at its full power, it can be binary content.

  - By adding a key_b64= parameter to the filename, to specify a binary key expressed in Base64 encoding, like /vsicrypt/key_b64=th1sl00kslikebase64=,file=/path/to/file.

  - By setting the VSICRYPT_KEY configuration option. The key should be in text format.

  - By setting the VSICRYPT_KEY_B64 configuration option. The key should be encoded in Base64.

  - By using the VSISetCryptKey() C function.

  When creating a file, if key=GENERATE_IT or VSICRYPT_KEY=GENERATE_IT is passed, the encryption key will be generated from the pseudo-random number generator of the operating system. The key will be displayed on the standard error stream in a Base64 form (unless the VSICRYPT_DISPLAY_GENERATED_KEY configuration option is set to OFF), and the VSICRYPT_KEY_B64 configuration option will also be set with the Base64 form of the key (so that CPLGetConfigOption(“VSICRYPT_KEY_B64”, NULL) can be used to get it back).

  The available options are :

  - alg=AES/Blowfish/Camellia/CAST256/DES_EDE2/DES_EDE3/MARS/IDEA/RC5/RC6/Serpent/SHACAL2/SKIPJACK/Twofish/XTEA: to specify the block cipher algorithm. The default is AES. Only used on creation. Ignored otherwise. Note: depending on how GDAL is build, if linked against the DLL version of libcrypto++, only a subset of those algorithms will be available, namely AES, DES_EDE2, DES_EDE3 and SKIPJACK. Also available as VSICRYPT_ALG configuration option.

  - mode=CBC/CFB/OFB/CTR/CBC_CTS: to specify the block cipher mode of operation. The default is CBC. Only used on creation. Ignored otherwise. Also available as VSICRYPT_MODE configuration option.

  - key=text_key: see above.

  - key_b64=base64_encoded_key: see above.

  - freetext=some_text: to specify a text content that will be written unencrypted in the file header, for informational purposes. Default to empty. Only used on creation. Ignored otherwise. Also available as VSICRYPT_FREETEXT configuration option.

  - sector_size=int_value: to specify the size of the “sector”, which is the unit chunk of information that is encrypted/decrypted. Default to 512 bytes. The valid values depend on the algorithm and block cipher mode of operation. Only used on creation. Ignored otherwise. Also available as VSICRYPT_SECTOR_SIZE configuration option.

  - iv=initial_vector_as_text: to specify the Initial Vector. This is an advanced option that should generally NOT be used. It is only useful to get completely deterministic output given the plaintext, key and other parameters, which in general NOT what you want to do. By default, a random initial vector of the appropriate size will be generated for each new file created. Only used on creation. Ignored otherwise. Also available as VSICRYPT_IV configuration option.

  - add_key_check=YES/NO: whether a special value should be encrypted in the header, so as to be quickly able to determine if the decryption key is correct. Defaults to NO. Only used on creation. Ignored otherwise. Also available as VSICRYPT_ADD_KEY_CHECK configuration option.

  - file=filename. To specify the filename. This must be the last option put in the option list (so as to make it possible to use filenames with comma in them. )

  This special file handler can be combined with other virtual filesystems handlers, such as /vsizip. For example, /vsicrypt//vsicurl/path/to/remote/encrypted/file.tif

  Implementation details:

  The structure of encrypted files is the following: a header, immediately followed by the encrypted payload (by sectors, i.e. chunks of sector_size bytes).

  The header structure is the following :

  1. 8 bytes. Signature. Fixed value: VSICRYPT.

  2. UINT16_LE. Header size (including previous signature bytes).

  3. UINT8. Format major version. Current value: 1.

  4. UINT8. Format minor version. Current value: 0.

  5. UINT16. Sector size.

  6. UINT8. Cipher algorithm. Valid values are: 0 = AES (Rijndael), 1 = Blowfish, 2 = Camellia, 3 = CAST256, 4 = DES_EDE2, 5 = DES_EDE3, 6 = MARS, 7 = IDEA, 8 = RC5, 9 = RC6, 10 = Serpent, 11 = SHACAL2, 12 = SKIPJACK, 13 = Twofish, 14 = XTEA.

  7. UINT8. Block cipher mode of operation. Valid values are: 0 = CBC, 1 = CFB, 2 = OFB, 3 = CTR, 4 = CBC_CTS.

  8. UINT8. Size in bytes of the Initial Vector.

  9. N bytes with the content of the Initial Vector, where N is the value of the previous field.

  10. UINT16_LE. Size in bytes of the free text.

  11. N bytes with the content of the free text, where N is the value of the previous field.

  12. UINT8. Size in bytes of encrypted content (key check), or 0 if key check is absent.

  13. N bytes with encrypted content (key check), where N is the value of the previous field.

  14. UINT64_LE. Size of the unencrypted file, in bytes.

  15. UINT16_LE. Size in bytes of extra content (of unspecified semantics). For v1.0, fixed value of 0

  16. N bytes with extra content (of unspecified semantics), where N is the value of the previous field.

  This design does not provide any means of authentication or integrity check.

  Each sector is encrypted/decrypted independently of other sectors. For that, the Initial Vector contained in the header is XOR’ed with the file offset (relative to plain text file) of the start of the sector being processed, as a 8-byte integer. More precisely, the first byte of the main IV is XOR’ed with the 8 least-significant bits of the sector offset, the second byte of the main IV is XOR’ed with the following 8 bits of the sector offset, etc… until the 8th byte.

  This design could potentially be prone to chosen-plaintext attack, for example if the attacker managed to get (part of) an existing encrypted file to be encrypted from plaintext he might have selected.

  Note: if “hostile” code can explore process content, or attach to it with a debugger, it might be relatively easy to retrieve the encryption key. A GDAL plugin could for example get the content of configuration options, or list opened datasets and see the key/key_b64 values, so disabling plugin loading might be a first step, as well as linking statically GDAL to application code. If plugin loading is enabled or GDAL dynamically linked, using VSISetCryptKey() to set the key might make it a bit more complicated to spy the key. But, as said initially, this is in no way a perfect protection.

  Since

    GDAL 2.1.0

void `VSISetCryptKey`(const GByte *pabyKey, int nKeySize)

  Installs the encryption/decryption key.

  By passing a NULL key, the previously installed key will be cleared. Note, however, that it is not guaranteed that there won’t be trace of it in other places in memory or in on-disk temporary file.

  See

    VSIInstallCryptFileHandler() for documentation on /vsicrypt/

  Parameters

    - `pabyKey`: key. Might be NULL to clear previously set key.

    - `nKeySize`: length of the key in bytes. Might be 0 to clear previously set key.

VSILFILE *`VSIFileFromMemBuffer`(const char *pszFilename, GByte *pabyData, vsi_l_offset nDataLength, int bTakeOwnership)

  Create memory “file” from a buffer.

  A virtual memory file is created from the passed buffer with the indicated filename. Under normal conditions the filename would need to be absolute and within the /vsimem/ portion of the filesystem.

  If bTakeOwnership is TRUE, then the memory file system handler will take ownership of the buffer, freeing it when the file is deleted. Otherwise it remains the responsibility of the caller, but should not be freed as long as it might be accessed as a file. In no circumstances does this function take a copy of the pabyData contents.

  Return

    open file handle on created file (see VSIFOpenL()).

  Parameters

    - `pszFilename`: the filename to be created.

    - `pabyData`: the data buffer for the file.

    - `nDataLength`: the length of buffer in bytes.

    - `bTakeOwnership`: TRUE to transfer “ownership” of buffer or FALSE.

GByte *`VSIGetMemFileBuffer`(const char *pszFilename, vsi_l_offset *pnDataLength, int bUnlinkAndSeize)

  Fetch buffer underlying memory file.

  This function returns a pointer to the memory buffer underlying a virtual “in memory” file. If bUnlinkAndSeize is TRUE the filesystem object will be deleted, and ownership of the buffer will pass to the caller otherwise the underlying file will remain in existence.

  Return

    pointer to memory buffer or NULL on failure.

  Parameters

    - `pszFilename`: the name of the file to grab the buffer of.

    - `pnDataLength`: (file) length returned in this variable.

    - `bUnlinkAndSeize`: TRUE to remove the file, or FALSE to leave unaltered.

void `VSIStdoutSetRedirection`(VSIWriteFunction pFct, FILE *stream)

  Set an alternative write function and output file handle instead of fwrite() / stdout.

  Since

    GDAL 2.0

  Parameters

    - `pFct`: Function with same signature as fwrite()

    - `stream`: File handle on which to output. Passed to pFct.

VSIFilesystemPluginCallbacksStruct *`VSIAllocFilesystemPluginCallbacksStruct`(void)

  return a VSIFilesystemPluginCallbacksStruct to be populated at runtime with handler callbacks

  Since

    GDAL 3.0

void `VSIFreeFilesystemPluginCallbacksStruct`(VSIFilesystemPluginCallbacksStruct *poCb)

  free resources allocated by VSIAllocFilesystemPluginCallbacksStruct

  Since

    GDAL 3.0

int `VSIInstallPluginHandler`(const char *pszPrefix, const VSIFilesystemPluginCallbacksStruct *poCb)

  register a handler on the given prefix.

  All IO on datasets opened with the filename /prefix/xxxxxx will go through these callbacks. pszPrefix must begin and end with a ‘/’

  Since

    GDAL 3.0

struct `VSIDIREntry`
  #include <cpl_vsi.h>

  Directory entry.

  Public Members

  char *`pszName`

    Filename.

  int `nMode`

    File mode.

    See VSI_ISREG() / VSI_ISDIR()

  vsi_l_offset `nSize`

    File size.

  GIntBig `nMTime`

    Last modification time (seconds since 1970/01/01)

  char `bModeKnown`

    Whether nMode is known: 0 = unknown, 1 = known.

  char `bSizeKnown`

    Whether nSize is known: 0 = unknown, 1 = known.

  char `bMTimeKnown`

    Whether nMTime is known: 0 = unknown, 1 = known.

  char **`papszExtra`

    NULL-terminated list of extra properties.

struct `VSIFilesystemPluginCallbacksStruct`
  #include <cpl_vsi.h>

  struct containing callbacks to used by the handler.

  (rw), (r), (w) or () at the end indicate wether the given callback is mandatory for reading and or writing handlers. A (?) indicates that the callback might be mandatory for certain drivers only.

  Since

    GDAL 3.0

  Public Members

  void *`pUserData`

    Optional opaque pointer passed back to filemanager callbacks (e.g.

    open, stat, rmdir)

  VSIFilesystemPluginStatCallback `stat`

    stat handle by name (rw)

  VSIFilesystemPluginUnlinkCallback `unlink`

    unlink handle by name ()

  VSIFilesystemPluginRenameCallback `rename`

    rename handle ()

  VSIFilesystemPluginMkdirCallback `mkdir`

    make directory ()

  VSIFilesystemPluginRmdirCallback `rmdir`

    remove directory ()

  VSIFilesystemPluginReadDirCallback `read_dir`

    list directory content (r?)

  VSIFilesystemPluginOpenCallback `open`

    open handle by name (rw)

  VSIFilesystemPluginTellCallback `tell`

    get current position of handle (rw)

  VSIFilesystemPluginSeekCallback `seek`

    set current position of handle (rw)

  VSIFilesystemPluginReadCallback `read`

    read from current position (r)

  VSIFilesystemPluginReadMultiRangeCallback `read_multi_range`

    read multiple blocks ()

  VSIFilesystemPluginGetRangeStatusCallback `get_range_status`

    get range status ()

  VSIFilesystemPluginEofCallback `eof`

    has end of file been reached (r?)

  VSIFilesystemPluginWriteCallback `write`

    write bytes to current position (w)

  VSIFilesystemPluginFlushCallback `flush`

    sync bytes (w)

  VSIFilesystemPluginTruncateCallback `truncate`

    truncate handle (w?)

  VSIFilesystemPluginCloseCallback `close`

    close handle (rw)

## cpl_vsi_virtual.h

Functions

VSIVirtualHandle *`VSICreateBufferedReaderHandle`(VSIVirtualHandle *poBaseHandle)

VSIVirtualHandle *`VSICreateBufferedReaderHandle`(VSIVirtualHandle *poBaseHandle, const GByte *pabyBeginningContent, vsi_l_offset nCheatFileSize)

VSIVirtualHandle *`VSICreateCachedFile`(VSIVirtualHandle *poBaseHandle, size_t nChunkSize = 32768, size_t nCacheSize = 0)

VSIVirtualHandle *`VSICreateGZipWritable`(VSIVirtualHandle *poBaseHandle, int nDeflateType, int bAutoCloseBaseHandle)

Variables

const int `CPL_DEFLATE_TYPE_GZIP` = 0

const int `CPL_DEFLATE_TYPE_ZLIB` = 1

const int `CPL_DEFLATE_TYPE_RAW_DEFLATE` = 2

class `VSIVirtualHandle`
  #include <cpl_vsi_virtual.h>

  Virtual file handle.

  Subclassed by VSISparseFileHandle, VSISubFileHandle

  Public Functions

  int `Seek`(vsi_l_offset nOffset, int nWhence) = 0

    Seek to requested offset.

    Seek to the desired offset (nOffset) in the indicated file.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

    Analog of the POSIX fseek() call.

    Caution: vsi_l_offset is a unsigned type, so SEEK_CUR can only be used for positive seek. If negative seek is needed, use handle->Seek( handle->Tell() + negative_offset, SEEK_SET ).

    Return

      0 on success or -1 one failure.

    Parameters

      - `nOffset`: offset in bytes.

      - `nWhence`: one of SEEK_SET, SEEK_CUR or SEEK_END.

  `Tell`() = 0

    Tell current file offset.

    Returns the current file read/write offset in bytes from the beginning of the file.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

    Analog of the POSIX ftell() call.

    Return

      file offset in bytes.

  `Read`(void *pBuffer, size_t nSize, size_t nCount) = 0

    Read bytes from file.

    Reads nCount objects of nSize bytes from the indicated file at the current offset into the indicated buffer.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

    Analog of the POSIX fread() call.

    Return

      number of objects successfully read.

    Parameters

      - `pBuffer`: the buffer into which the data should be read (at least nCount * nSize bytes in size.

      - `nSize`: size of objects to read in bytes.

      - `nCount`: number of objects to read.

  `ReadMultiRange`(int nRanges, void **ppData, const vsi_l_offset *panOffsets, const size_t *panSizes)

    Read several ranges of bytes from file.

    Reads nRanges objects of panSizes[i] bytes from the indicated file at the offset panOffsets[i] into the buffer ppData[i].

    Ranges must be sorted in ascending start offset, and must not overlap each other.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory or /vsicurl/.

    Return

      0 in case of success, -1 otherwise.

    Since

      GDAL 1.9.0

    Parameters

      - `nRanges`: number of ranges to read.

      - `ppData`: array of nRanges buffer into which the data should be read (ppData[i] must be at list panSizes[i] bytes).

      - `panOffsets`: array of nRanges offsets at which the data should be read.

      - `panSizes`: array of nRanges sizes of objects to read (in bytes).

  `Write`(const void *pBuffer, size_t nSize, size_t nCount) = 0

    Write bytes to file.

    Writess nCount objects of nSize bytes to the indicated file at the current offset into the indicated buffer.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

    Analog of the POSIX fwrite() call.

    Return

      number of objects successfully written.

    Parameters

      - `pBuffer`: the buffer from which the data should be written (at least nCount * nSize bytes in size.

      - `nSize`: size of objects to read in bytes.

      - `nCount`: number of objects to read.

  `Eof`() = 0

    Test for end of file.

    Returns TRUE (non-zero) if an end-of-file condition occurred during the previous read operation. The end-of-file flag is cleared by a successful VSIFSeekL() call.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

    Analog of the POSIX feof() call.

    Return

      TRUE if at EOF else FALSE.

  `Flush`()

    Flush pending writes to disk.

    For files in write or update mode and on filesystem types where it is applicable, all pending output on the file is flushed to the physical disk.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

    Analog of the POSIX fflush() call.

    Return

      0 on success or -1 on error.

  `Close`() = 0

    Close file.

    This function closes the indicated file.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

    Analog of the POSIX fclose() function.

    Return

      0 on success or -1 on failure.

  `Truncate`(vsi_l_offset nNewSize)

    Truncate/expand the file to the specified size.

    This method goes through the VSIFileHandler virtualization and may work on unusual filesystems such as in memory.

    Analog of the POSIX ftruncate() call.

    Return

      0 on success

    Since

      GDAL 1.9.0

    Parameters

      - `nNewSize`: new size in bytes.

  `GetNativeFileDescriptor`()

    Returns the “native” file descriptor for the virtual handle.

    This will only return a non-NULL value for “real” files handled by the operating system (to be opposed to GDAL virtual file systems).

    On POSIX systems, this will be a integer value (“fd”) cast as a void*. On Windows systems, this will be the HANDLE.

    Return

      the native file descriptor, or NULL.

  `GetRangeStatus`(vsi_l_offset nOffset, vsi_l_offset nLength)

    Return if a given file range contains data or holes filled with zeroes.

    This uses the filesystem capabilities of querying which regions of a sparse file are allocated or not. This is currently only implemented for Linux (and no other Unix derivatives) and Windows.

    Note: A return of VSI_RANGE_STATUS_DATA doesn’t exclude that the extent is filled with zeroes! It must be interpreted as “may

    contain non-zero data”.

    Return

      extent status: VSI_RANGE_STATUS_UNKNOWN, VSI_RANGE_STATUS_DATA or VSI_RANGE_STATUS_HOLE

    Since

      GDAL 2.2

    Parameters

      - `nOffset`: offset of the start of the extent.

      - `nLength`: extent length.

  virtual `~VSIVirtualHandle`()