Various convenience functions for CPL. More...

#include "cpl_port.h"
#include "cpl_vsi.h"
#include "cpl_error.h"

Classes
struct	CPLSharedFileInfo
	Information on a shared file. More...

Macros
#define	CPLFree VSIFree
	Alias of VSIFree()

Typedefs
typedef void(*	CPLSetConfigOptionSubscriber) (const char pszKey, const char pszValue, bool bThreadLocal, void *pUserData)
	Callback for CPLSubscribeToSetConfigOption()

typedef char const (	CPLFileFinder) (const char , const char )
	Callback for CPLPushFileFinder.

Functions
const char *	CPLGetConfigOption (const char , const char )
	Get the value of a configuration option. More...

const char *	CPLGetThreadLocalConfigOption (const char , const char )
	Same as CPLGetConfigOption() but only with options set with CPLSetThreadLocalConfigOption()

const char *	CPLGetGlobalConfigOption (const char , const char )
	Same as CPLGetConfigOption() but excludes environment variables and options set with CPLSetThreadLocalConfigOption(). More...

void	CPLSetConfigOption (const char , const char )
	Set a configuration option for GDAL/OGR use. More...

void	CPLSetThreadLocalConfigOption (const char pszKey, const char pszValue)
	Set a configuration option for GDAL/OGR use. More...

int	CPLSubscribeToSetConfigOption (CPLSetConfigOptionSubscriber pfnCallback, void *pUserData)
	Install a callback that will be notified of calls to CPLSetConfigOption()/ CPLSetThreadLocalConfigOption() More...

void	CPLUnsubscribeToSetConfigOption (int nSubscriberId)
	Remove a subscriber installed with CPLSubscribeToSetConfigOption() More...

char **	CPLGetConfigOptions (void)
	Return the list of configuration options as KEY=VALUE pairs. More...

void	CPLSetConfigOptions (const char const papszConfigOptions)
	Replace the full list of configuration options with the passed list of KEY=VALUE pairs. More...

char **	CPLGetThreadLocalConfigOptions (void)
	Return the list of thread local configuration options as KEY=VALUE pairs. More...

void	CPLSetThreadLocalConfigOptions (const char const papszConfigOptions)
	Replace the full list of thread local configuration options with the passed list of KEY=VALUE pairs. More...

void	CPLLoadConfigOptionsFromFile (const char *pszFilename, int bOverrideEnvVars)
	Load configuration from a given configuration file. More...

void	CPLLoadConfigOptionsFromPredefinedFiles (void)
	Load configuration from a set of predefined files. More...

void *	CPLMalloc (size_t)
	Safe version of malloc(). More...

void *	CPLCalloc (size_t, size_t)
	Safe version of calloc(). More...

void *	CPLRealloc (void *, size_t)
	Safe version of realloc(). More...

char *	CPLStrdup (const char *)
	Safe version of strdup() function. More...

char *	CPLStrlwr (char *)
	Convert each characters of the string to lower case. More...

char *	CPLFGets (char , int, FILE )
	Reads in at most one less than nBufferSize characters from the fp stream and stores them into the buffer pointed to by pszBuffer. More...

const char *	CPLReadLine (FILE *)
	Simplified line reading from text file. More...

const char *	CPLReadLineL (VSILFILE *)
	Simplified line reading from text file. More...

const char *	CPLReadLine2L (VSILFILE *, int, CSLConstList)
	Simplified line reading from text file. More...

const char *	CPLReadLine3L (VSILFILE , int, int , CSLConstList)
	Simplified line reading from text file. More...

double	CPLAtof (const char *)
	Converts ASCII string to floating point number. More...

double	CPLAtofDelim (const char *, char)
	Converts ASCII string to floating point number. More...

double	CPLStrtod (const char , char *)
	Converts ASCII string to floating point number. More...

double	CPLStrtodM (const char , char *)
	Converts ASCII string to floating point number. More...

double	CPLStrtodDelim (const char , char *, char)
	Converts ASCII string to floating point number using specified delimiter. More...

float	CPLStrtof (const char , char *)
	Converts ASCII string to floating point number. More...

float	CPLStrtofDelim (const char , char *, char)
	Converts ASCII string to floating point number using specified delimiter. More...

double	CPLAtofM (const char *)
	Converts ASCII string to floating point number using any numeric locale. More...

char *	CPLScanString (const char *, int, int, int)
	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. More...

double	CPLScanDouble (const char *, int)
	Extract double from string. More...

long	CPLScanLong (const char *, int)
	Scan up to a maximum number of characters from a string and convert the result to a long. More...

unsigned long	CPLScanULong (const char *, int)
	Scan up to a maximum number of characters from a string and convert the result to a unsigned long. More...

GUIntBig	CPLScanUIntBig (const char *, int)
	Extract big integer from string. More...

GIntBig	CPLAtoGIntBig (const char *pszString)
	Convert a string to a 64 bit signed integer. More...

GIntBig	CPLAtoGIntBigEx (const char pszString, int bWarn, int pbOverflow)
	Convert a string to a 64 bit signed integer. More...

void *	CPLScanPointer (const char *, int)
	Extract pointer from string. More...

int	CPLPrintString (char , const char , int)
	Copy the string pointed to by pszSrc, NOT including the terminating ‘\0’ character, to the array pointed to by pszDest. More...

int	CPLPrintStringFill (char , const char , int)
	Copy the string pointed to by pszSrc, NOT including the terminating ‘\0’ character, to the array pointed to by pszDest. More...

int	CPLPrintInt32 (char *, GInt32, int)
	Print GInt32 value into specified string buffer. More...

int	CPLPrintUIntBig (char *, GUIntBig, int)
	Print GUIntBig value into specified string buffer. More...

int	CPLPrintDouble (char , const char , double, const char *)
	Print double value into specified string buffer. More...

int	CPLPrintTime (char , int, const char , const struct tm , const char )
	Print specified time value accordingly to the format options and specified locale name. More...

int	CPLPrintPointer (char , void , int)
	Print pointer value into specified string buffer. More...

void *	CPLGetSymbol (const char , const char )
	Fetch a function pointer from a shared library / DLL. More...

int	CPLGetExecPath (char *pszPathBuf, int nMaxLength)
	Fetch path of executable. More...

const char *	CPLGetPath (const char *)
	Extract directory path portion of filename. More...

const char *	CPLGetDirname (const char *)
	Extract directory path portion of filename. More...

const char *	CPLGetFilename (const char *)
	Extract non-directory portion of filename. More...

const char *	CPLGetBasename (const char *)
	Extract basename (non-directory, non-extension) portion of filename. More...

const char *	CPLGetExtension (const char *)
	Extract filename extension from full filename. More...

char *	CPLGetCurrentDir (void)
	Get the current working directory name. More...

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. More...

const char *	CPLFormCIFilename (const char pszPath, const char pszBasename, const char *pszExtension)
	Case insensitive file searching, returning full path. More...

const char *	CPLResetExtension (const char , const char )
	Replace the extension with the provided one. More...

const char *	CPLProjectRelativeFilename (const char pszProjectDir, const char pszSecondaryFilename)
	Find a file relative to a project file. More...

int	CPLIsFilenameRelative (const char *pszFilename)
	Is filename relative or absolute? More...

const char *	CPLExtractRelativePath (const char , const char , int *)
	Get relative path from directory to target file. More...

const char *	CPLCleanTrailingSlash (const char *)
	Remove trailing forward/backward slash from the path for UNIX/Windows resp. More...

char **	CPLCorrespondingPaths (const char pszOldFilename, const char pszNewFilename, char **papszFileList)
	Identify corresponding paths. More...

int	CPLCheckForFile (char pszFilename, char *papszSiblingList)
	Check for file existence. More...

const char *	CPLGenerateTempFilename (const char *pszStem)
	Generate temporary file name. More...

const char *	CPLExpandTilde (const char *pszFilename)
	Expands ~/ at start of filename. More...

const char *	CPLGetHomeDir (void)
	Return the path to the home directory. More...

const char *	CPLLaunderForFilename (const char pszName, const char pszOutputPath)
	Launder a string to be compatible of a filename. More...

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 , VSIStatBuf )
	Same as VSIStat() except it works on "C:" as if it were "C:\".

FILE *	CPLOpenShared (const char , const char , int)
	Open a shared file handle. More...

void	CPLCloseShared (FILE *)
	Close shared file. More...

CPLSharedFileInfo *	CPLGetSharedList (int *)
	Fetch list of open shared files. More...

void	CPLDumpSharedList (FILE *)
	Report open shared files. More...

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)
	Convert a packed DMS value (DDDMMMSSS.SS) into decimal degrees. More...

double	CPLDecToPackedDMS (double dfDec)
	Convert decimal degrees into packed DMS value (DDDMMMSSS.SS). More...

void	CPLStringToComplex (const char pszString, double pdfReal, double *pdfImag)
	Fetch the real and imaginary part of a serialized complex number.

int	CPLUnlinkTree (const char *)
	Recursively unlink a directory. More...

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	CPLAddFileInZip (void hZip, const char pszArchiveFilename, const char pszInputFilename, VSILFILE fpInput, CSLConstList papszOptions, GDALProgressFunc pProgressFunc, void *pProgressData)
	Add a file inside a ZIP file opened/created with CPLCreateZip(). More...

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 compression. More...

void *	CPLZLibInflate (const void ptr, size_t nBytes, void outptr, size_t nOutAvailableBytes, size_t *pnOutBytes)
	Uncompress a buffer compressed with ZLib compression. More...

void *	CPLZLibInflateEx (const void ptr, size_t nBytes, void outptr, size_t nOutAvailableBytes, bool bAllowResizeOutptr, size_t *pnOutBytes)
	Uncompress a buffer compressed with ZLib compression. More...

int	CPLValidateXML (const char pszXMLFilename, const char pszXSDFilename, CSLConstList papszOptions)
	Validate a XML file against a XML schema. More...

char *	CPLsetlocale (int category, const char *locale)
	Prevents parallel executions of setlocale(). More...

int	CPLIsPowerOfTwo (unsigned int i)

template<typename To , typename From >
To	cpl::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. More...

Detailed Description

Various convenience functions for CPL.

Function Documentation

◆ CPLAddFileInZip()

CPLErr CPLAddFileInZip	(	void *	hZip,
		const char *	pszArchiveFilename,
		const char *	pszInputFilename,
		VSILFILE *	fpInput,
		CSLConstList	papszOptions,
		GDALProgressFunc	pProgressFunc,
		void *	pProgressData
	)

Add a file inside a ZIP file opened/created with CPLCreateZip().

This combines calls sto CPLCreateFileInZip(), CPLWriteFileInZip(), and CPLCloseFileInZip() in a more convenient and powerful way.

In particular, this enables to add a compressed file using the seek optimization extension.

Supported options are:

SOZIP_ENABLED=AUTO/YES/NO: whether to generate a SOZip index for the file. The default can be changed with the CPL_SOZIP_ENABLED configuration option.
SOZIP_CHUNK_SIZE: chunk size to use for SOZip generation. Defaults to 32768.
SOZIP_MIN_FILE_SIZE: minimum file size to consider to enable SOZip index generation in SOZIP_ENABLED=AUTO mode. Defaults to 1 MB.
NUM_THREADS: number of threads used for SOZip generation. Defaults to ALL_CPUS.
TIMESTAMP=AUTO/NOW/timestamp_as_epoch_since_jan_1_1970: in AUTO mode, the timestamp of pszInputFilename will be used (if available), otherwise it will fallback to NOW.
CONTENT_TYPE=string: Content-Type value for the file. This is stored as a key-value pair in the extra field extension 'KV' (0x564b) dedicated to storing key-value pair metadata.

Parameters

hZip	ZIP file handle
pszArchiveFilename	Filename (in UTF-8) stored in the archive.
pszInputFilename	Filename of the file to add. If NULL, fpInput must not be NULL
fpInput	File handle opened on the file to add. May be NULL if pszInputFilename is provided.
papszOptions	Options.
pProgressFunc	Progress callback, or NULL.
pProgressData	User data of progress callback, or NULL.

Returns: CE_None in case of success.

Since: GDAL 3.7

◆ CPLAtof()

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 behavior 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.

Parameters

nptr	Pointer to string to convert.

Returns: Converted value, if any.

◆ CPLAtofDelim()

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 behavior 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.

Parameters

nptr	Pointer to string to convert.
point	Decimal delimiter.

Returns: Converted value, if any.

◆ CPLAtofM()

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.

Parameters

nptr	The string to convert.

Returns: Converted value, if any. Zero on failure.

◆ CPLAtoGIntBig()

GIntBig CPLAtoGIntBig ( const char * pszString )

Convert a string to a 64 bit signed integer.

Parameters

pszString String containing 64 bit signed integer.

Returns: 64 bit signed integer.

Since: GDAL 2.0

◆ CPLAtoGIntBigEx()

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

Convert a string to a 64 bit signed integer.

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

Returns: 64 bit signed integer.

Since: GDAL 2.0

◆ CPLCalloc()

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().

Parameters

nCount	number of objects to allocate.
nSize	size (in bytes) of object to allocate.

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

◆ CPLCheckForFile()

int CPLCheckForFile	(	char *	pszFilename,
		char **	papszSiblingFiles
	)

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.

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.

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

◆ CPLCleanTrailingSlash()

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).

CPLCleanTrailingSlash( "abc/def/" ) == "abc/def"
CPLCleanTrailingSlash( "abc/def" ) == "abc/def"
CPLCleanTrailingSlash( "c:\\abc\\def\\" ) == "c:\abc\def"
CPLCleanTrailingSlash( "c:\abc\def" ) == "c:\abc\def"
CPLCleanTrailingSlash( "abc" ) == "abc"

Parameters

pszPath the path to be cleaned up

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

◆ CPLCloseShared()

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.

◆ CPLCorrespondingPaths()

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().

Parameters

pszOldFilename	path to old prototype file.
pszNewFilename	path to new prototype file.
papszFileList	list of other files associated with pszOldFilename to rename similarly.

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

◆ CPLDecToPackedDMS()

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

◆ CPLDumpSharedList()

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.

◆ CPLExpandTilde()

const char * CPLExpandTilde ( const char * pszFilename )

Expands ~/ at start of filename.

Assumes that the HOME configuration option is defined.

Parameters

pszFilename filename potentially starting with ~/

Returns: an expanded filename.

Since: GDAL 2.2

◆ CPLExtractRelativePath()

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.

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.

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

◆ CPLFGets()

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.

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.

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

◆ CPLFormCIFilename()

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).

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.

Returns: 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.

◆ CPLFormFilename()

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.

CPLFormFilename("abc/xyz", "def", ".dat" ) == "abc/xyz/def.dat"
CPLFormFilename(NULL,"def", NULL ) == "def"
CPLFormFilename(NULL, "abc/def.dat", NULL ) == "abc/def.dat"
CPLFormFilename("/abc/xyz/", "def.dat", NULL ) == "/abc/xyz/def.dat"

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.

Returns: 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.

◆ CPLGenerateTempFilename()

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.

Parameters

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

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

◆ CPLGetBasename()

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.

CPLGetBasename( "abc/def.xyz" ) == "def"
CPLGetBasename( "abc/def" ) == "def"
CPLGetBasename( "abc/def/" ) == ""

Parameters

pszFullFilename the full filename potentially including a path.

Returns: 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.

◆ CPLGetConfigOption()

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 :

    // backup old value
    const char* pszOldValTmp = CPLGetConfigOption(pszKey, NULL);
    char* pszOldVal = pszOldValTmp ? CPLStrdup(pszOldValTmp) : NULL;
    // override with new value
    CPLSetConfigOption(pszKey, pszNewVal);
    // do something useful
    // restore old value
    CPLSetConfigOption(pszKey, pszOldVal);
    CPLFree(pszOldVal);

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)

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

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

◆ CPLGetConfigOptions()

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.

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

Since: GDAL 2.2

◆ CPLGetCurrentDir()

char * CPLGetCurrentDir ( void )

Get the current working directory name.

Returns: 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.

◆ CPLGetDirname()

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().

CPLGetDirname( "abc/def.xyz" ) == "abc"
CPLGetDirname( "/abc/def/" ) == "/abc/def"
CPLGetDirname( "/" ) == "/"
CPLGetDirname( "/abc/def" ) == "/abc"
CPLGetDirname( "abc" ) == "."

Parameters

pszFilename the filename potentially including a path.

Returns: 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.

◆ CPLGetExecPath()

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 Windows, Linux, MacOS and FreeBSD platforms. The returned path is UTF-8 encoded, and will be nul-terminated if success is reported.

Parameters

pszPathBuf	the buffer into which the path is placed.
nMaxLength	the buffer size (including the nul-terminating character). MAX_PATH+1 is suggested.

Returns: FALSE on failure or TRUE on success.

◆ CPLGetExtension()

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.

CPLGetExtension( "abc/def.xyz" ) == "xyz"
CPLGetExtension( "abc/def" ) == ""

Parameters

pszFullFilename the full filename potentially including a path.

Returns: 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.

◆ CPLGetFilename()

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.

CPLGetFilename( "abc/def.xyz" ) == "def.xyz"
CPLGetFilename( "/abc/def/" ) == ""
CPLGetFilename( "abc/def" ) == "def"

Parameters

pszFullFilename the full filename potentially including a path.

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

◆ CPLGetGlobalConfigOption()

const char * CPLGetGlobalConfigOption	(	const char *	pszKey,
		const char *	pszDefault
	)

Same as CPLGetConfigOption() but excludes environment variables and options set with CPLSetThreadLocalConfigOption().

This function should generally not be used by applications, which should use CPLGetConfigOption() instead.

Since: 3.8

◆ CPLGetHomeDir()

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.

Returns: the home directory, or NULL.

Since: GDAL 2.3

◆ CPLGetPath()

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).

CPLGetPath( "abc/def.xyz" ) == "abc"
CPLGetPath( "/abc/def/" ) == "/abc/def"
CPLGetPath( "/" ) == "/"
CPLGetPath( "/abc/def" ) == "/abc"
CPLGetPath( "abc" ) == ""

Parameters

pszFilename the filename potentially including a path.

Returns: 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.

◆ CPLGetSharedList()

CPLSharedFileInfo * CPLGetSharedList ( int * pnCount )

Fetch list of open shared files.

Parameters

pnCount place to put the count of entries.

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

◆ CPLGetSymbol()

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.

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.

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

◆ CPLGetThreadLocalConfigOptions()

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.

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

Since: GDAL 2.2

◆ CPLIsFilenameRelative()

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.

Parameters

pszFilename the filename with path to test.

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

◆ CPLIsPowerOfTwo()

int CPLIsPowerOfTwo ( unsigned int i )

CPLIsPowerOfTwo()

Parameters

i	- tested number

Returns: TRUE if i is power of two otherwise return FALSE

◆ CPLLaunderForFilename()

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

Launder a string to be compatible of a filename.

Parameters

pszName	The input string to launder.
pszOutputPath	The directory where the file would be created. Unused for now. May be NULL.

Returns: the laundered name.

Since: GDAL 3.1

◆ CPLLoadConfigOptionsFromFile()

void CPLLoadConfigOptionsFromFile	(	const char *	pszFilename,
		int	bOverrideEnvVars
	)

Load configuration from a given configuration file.

A configuration file is a text file in a .ini style format, that lists configuration options and their values. Lines starting with # are comment lines.

Example:

[configoptions]
# set BAR as the value of configuration option FOO
FOO=BAR

Starting with GDAL 3.5, a configuration file can also contain credentials (or more generally options related to a virtual file system) for a given path prefix, that can also be set with VSISetPathSpecificOption(). Credentials should be put under a [credentials] section, and for each path prefix, under a relative subsection whose name starts with "[." (e.g. "[.some_arbitrary_name]"), and whose first key is "path".

Example:

[credentials]

[.private_bucket]
path=/vsis3/my_private_bucket
AWS_SECRET_ACCESS_KEY=...
AWS_ACCESS_KEY_ID=...

[.sentinel_s2_l1c]
path=/vsis3/sentinel-s2-l1c
AWS_REQUEST_PAYER=requester

Starting with GDAL 3.6, a leading [directives] section might be added with a "ignore-env-vars=yes" setting to indicate that, starting with that point, all environment variables should be ignored, and only configuration options defined in the [configoptions] sections or through the CPLSetConfigOption() / CPLSetThreadLocalConfigOption() functions should be taken into account.

This function is typically called by CPLLoadConfigOptionsFromPredefinedFiles()

Parameters

pszFilename	File where to load configuration from.
bOverrideEnvVars	Whether configuration options from the configuration file should override environment variables.

Since: GDAL 3.3

◆ CPLLoadConfigOptionsFromPredefinedFiles()

void CPLLoadConfigOptionsFromPredefinedFiles ( void )

Load configuration from a set of predefined files.

If the environment variable (or configuration option) GDAL_CONFIG_FILE is set, then CPLLoadConfigOptionsFromFile() will be called with the value of this configuration option as the file location.

Otherwise, for Unix builds, CPLLoadConfigOptionsFromFile() will be called with ${sysconfdir}/gdal/gdalrc first where ${sysconfdir} evaluates to ${prefix}/etc, unless the –sysconfdir switch of configure has been invoked.

Then CPLLoadConfigOptionsFromFile() will be called with /github/home/.gdal/gdalrc on Unix builds (potentially overriding what was loaded with the sysconfdir) or /.gdal/gdalrc on Windows builds.

CPLLoadConfigOptionsFromFile() will be called with bOverrideEnvVars = false, that is the value of environment variables previously set will be used instead of the value set in the configuration files (unless the configuration file contains a leading [directives] section with a "ignore-env-vars=yes" setting).

This function is automatically called by GDALDriverManager() constructor

Since: GDAL 3.3

◆ CPLMalloc()

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().

Parameters

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

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

◆ CPLOpenShared()

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.

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().

Returns: a file handle or NULL if opening fails.

◆ CPLPackedDMSToDec()

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:

The absolute value of the angle is used.
The degrees are separated out: deg = angle/1000000 (fractional portion truncated)
The minutes are separated out: min = (angle - deg * 1000000) / 1000 (fractional portion truncated)
The seconds are then computed: sec = angle - deg * 1000000 - min * 1000
The total angle in seconds is computed: sec = deg * 3600.0 + min * 60.0 + sec
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.

Parameters

dfPacked Angle in packed DMS format.

Returns: Angle in decimal degrees.

◆ CPLPrintDouble()

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.

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.

Returns: Number of characters printed.

◆ CPLPrintInt32()

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

Print GInt32 value into specified string buffer.

This string will not be NULL-terminated.

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.

Returns: Number of characters printed.

◆ CPLPrintPointer()

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

Print pointer value into specified string buffer.

This string will not be NULL-terminated.

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.

Returns: Number of characters printed.

◆ CPLPrintString()

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.

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.

Returns: Number of characters printed.

◆ CPLPrintStringFill()

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().

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.

Returns: Number of characters printed.

◆ CPLPrintTime()

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.

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.

Returns: Number of characters printed.

◆ CPLPrintUIntBig()

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

Print GUIntBig value into specified string buffer.

This string will not be NULL-terminated.

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.

Returns: Number of characters printed.

◆ CPLProjectRelativeFilename()

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:

CPLProjectRelativeFilename("abc/def", "tmp/abc.gif") == "abc/def/tmp/abc.gif"
CPLProjectRelativeFilename("abc/def", "/tmp/abc.gif") == "/tmp/abc.gif"
CPLProjectRelativeFilename("/xy", "abc.gif") == "/xy/abc.gif"
CPLProjectRelativeFilename("/abc/def", "../abc.gif") == "/abc/def/../abc.gif"
CPLProjectRelativeFilename("C:\WIN", "abc.gif") == "C:\WIN\abc.gif"

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.

Returns: 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.

◆ CPLReadLine()

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.

Parameters

fp	file pointer opened with VSIFOpen().

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

◆ CPLReadLine2L()

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.

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.

Returns: 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

◆ CPLReadLine3L()

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.

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)

Returns: 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

◆ CPLReadLineL()

const char * CPLReadLineL ( VSILFILE * fp )

Simplified line reading from text file.

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

Parameters

fp	file pointer opened with VSIFOpenL().

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

◆ CPLRealloc()

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.

Parameters

pData	existing memory block which should be copied to the new block.
nNewSize	new size (in bytes) of memory block to allocate.

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

◆ CPLResetExtension()

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

Replace the extension with the provided one.

Parameters

pszPath	the input path, this string is not altered.
pszExt	the new extension to apply to the given path.

Returns: 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.

◆ CPLScanDouble()

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.

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.

Returns: Double value, converted from its ASCII form.

◆ CPLScanLong()

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.

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.

Returns: Long value, converted from its ASCII form.

◆ CPLScanPointer()

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.

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.

Returns: pointer value, converted from its ASCII form.

◆ CPLScanString()

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.

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.

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

◆ CPLScanUIntBig()

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.

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.

Returns: GUIntBig value, converted from its ASCII form.

◆ CPLScanULong()

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.

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.

Returns: Unsigned long value, converted from its ASCII form.

◆ CPLSetConfigOption()

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()).

Parameters

pszKey	the key of the option
pszValue	the value of the option, or NULL to clear a setting.

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

◆ CPLSetConfigOptions()

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.

Parameters

papszConfigOptions the new list (or NULL).

Since: GDAL 2.2

◆ CPLsetlocale()

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().

Parameters

category	See your compiler's documentation on setlocale.
locale	See your compiler's documentation on setlocale.

Returns: See your compiler's documentation on setlocale.

◆ CPLSetThreadLocalConfigOption()

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.

◆ CPLSetThreadLocalConfigOptions()

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.

Parameters

papszConfigOptions the new list (or NULL).

Since: GDAL 2.2

◆ CPLStrdup()

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).

Parameters

pszString input string to be duplicated. May be NULL.

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

◆ CPLStrlwr()

char * CPLStrlwr ( char * pszString )

Convert each characters of the string to lower case.

For example, "ABcdE" will be converted to "abcde". Starting with GDAL 3.9, this function is no longer locale dependent.

Parameters

pszString input string to be converted.

Returns: pointer to the same string, pszString.

◆ CPLStrtod()

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.

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.

Returns: Converted value, if any.

◆ CPLStrtodDelim()

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.

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.

Returns: Converted value, if any.

◆ CPLStrtodM()

double CPLStrtodM	(	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 function accepts '.' (decimal point) or ',' (comma) as decimal delimiter.

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.

Returns: Converted value, if any.

Since: GDAL 3.9

◆ CPLStrtof()

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.

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.

Returns: Converted value, if any.

◆ CPLStrtofDelim()

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.

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.

Returns: Converted value, if any.

◆ CPLSubscribeToSetConfigOption()

int CPLSubscribeToSetConfigOption	(	CPLSetConfigOptionSubscriber	pfnCallback,
		void *	pUserData
	)

Install a callback that will be notified of calls to CPLSetConfigOption()/ CPLSetThreadLocalConfigOption()

Parameters

pfnCallback	Callback. Must not be NULL
pUserData	Callback user data. May be NULL.

Returns: subscriber ID that can be used with CPLUnsubscribeToSetConfigOption()

Since: GDAL 3.7

◆ CPLUnlinkTree()

int CPLUnlinkTree ( const char * pszPath )

Recursively unlink a directory.

Returns: 0 on successful completion, -1 if function fails.

◆ CPLUnsubscribeToSetConfigOption()

void CPLUnsubscribeToSetConfigOption ( int nId )

Remove a subscriber installed with CPLSubscribeToSetConfigOption()

Parameters

nId	Subscriber id returned by CPLSubscribeToSetConfigOption()

Since: GDAL 3.7

◆ CPLValidateXML()

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

Validate a XML file against a XML schema.

Parameters

pszXMLFilename	the filename of the XML file to validate.
pszXSDFilename	the filename of the XSD schema.
papszOptions	unused for now. Set to NULL.

Returns: TRUE if the XML file validates against the XML schema.

Since: GDAL 1.10.0

◆ CPLZLibDeflate()

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

Compress a buffer with ZLib compression.

Parameters

ptr	input buffer.
nBytes	size of input buffer in bytes.
nLevel	ZLib compression level (-1 for default).
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.

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

Since: GDAL 1.10.0

◆ CPLZLibInflate()

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

Uncompress a buffer compressed with ZLib compression.

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.

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

Since: GDAL 1.10.0

◆ CPLZLibInflateEx()

void * CPLZLibInflateEx	(	const void *	ptr,
		size_t	nBytes,
		void *	outptr,
		size_t	nOutAvailableBytes,
		bool	bAllowResizeOutptr,
		size_t *	pnOutBytes
	)

Uncompress a buffer compressed with ZLib compression.

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.
bAllowResizeOutptr	whether the function is allowed to grow outptr (using VSIRealloc) if its initial capacity provided by nOutAvailableBytes is not large enough. Ignored if outptr is NULL.
pnOutBytes	pointer to a size_t, where to store the size of the output buffer.

Returns: the output buffer (to be freed with VSIFree() if not provided) or NULL in case of error. If bAllowResizeOutptr is set to true, only the returned pointer should be freed by the caller, as outptr might have been reallocated or freed.

Since: GDAL 3.9.0

◆ down_cast()

template<typename To , typename From >

To cpl::down_cast ( From * f )

inline

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.

Parameters

f	pointer to a base class

Returns: pointer to a derived class

Classes

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ CPLAddFileInZip()

◆ CPLAtof()

◆ CPLAtofDelim()

◆ CPLAtofM()

◆ CPLAtoGIntBig()

◆ CPLAtoGIntBigEx()

◆ CPLCalloc()

◆ CPLCheckForFile()

◆ CPLCleanTrailingSlash()

◆ CPLCloseShared()

◆ CPLCorrespondingPaths()

◆ CPLDecToPackedDMS()

◆ CPLDumpSharedList()

◆ CPLExpandTilde()

◆ CPLExtractRelativePath()

◆ CPLFGets()

◆ CPLFormCIFilename()

◆ CPLFormFilename()

◆ CPLGenerateTempFilename()

◆ CPLGetBasename()

◆ CPLGetConfigOption()

◆ CPLGetConfigOptions()

◆ CPLGetCurrentDir()

◆ CPLGetDirname()

◆ CPLGetExecPath()

◆ CPLGetExtension()

◆ CPLGetFilename()

◆ CPLGetGlobalConfigOption()

◆ CPLGetHomeDir()

◆ CPLGetPath()

◆ CPLGetSharedList()

◆ CPLGetSymbol()

◆ CPLGetThreadLocalConfigOptions()

◆ CPLIsFilenameRelative()

◆ CPLIsPowerOfTwo()

◆ CPLLaunderForFilename()

◆ CPLLoadConfigOptionsFromFile()

◆ CPLLoadConfigOptionsFromPredefinedFiles()

◆ CPLMalloc()

◆ CPLOpenShared()

◆ CPLPackedDMSToDec()

◆ CPLPrintDouble()

◆ CPLPrintInt32()

◆ CPLPrintPointer()

◆ CPLPrintString()

◆ CPLPrintStringFill()

◆ CPLPrintTime()

◆ CPLPrintUIntBig()

◆ CPLProjectRelativeFilename()

◆ CPLReadLine()

◆ CPLReadLine2L()

◆ CPLReadLine3L()

◆ CPLReadLineL()

◆ CPLRealloc()

◆ CPLResetExtension()

◆ CPLScanDouble()

◆ CPLScanLong()

◆ CPLScanPointer()

◆ CPLScanString()

◆ CPLScanUIntBig()

◆ CPLScanULong()

◆ CPLSetConfigOption()

◆ CPLSetConfigOptions()

◆ CPLsetlocale()

◆ CPLSetThreadLocalConfigOption()

◆ CPLSetThreadLocalConfigOptions()

◆ CPLStrdup()

◆ CPLStrlwr()

◆ CPLStrtod()

◆ CPLStrtodDelim()

◆ CPLStrtodM()

◆ CPLStrtof()

◆ CPLStrtofDelim()

◆ CPLSubscribeToSetConfigOption()