vlc_charset.h File Reference

Include dependency graph for vlc_charset.h:

Go to the source code of this file.

Defines
#define	VLC_CHARSET_H   1
Functions
void	LocaleFree (const char *)
	Releases (if needed) a localized or uniformized string.
char *	FromLocale (const char *)
	Converts a string from the system locale character encoding to UTF-8.
char *	FromLocaleDup (const char *)
	converts a string from the system locale character encoding to utf-8, the result is always allocated on the heap.
char *	ToLocale (const char *)
	ToLocale: converts an UTF-8 string to local system encoding.
char *	ToLocaleDup (const char *)
	converts a string from UTF-8 to the system locale character encoding, the result is always allocated on the heap.
int	utf8_open (const char *filename, int flags, mode_t mode)
	Opens a system file handle using UTF-8 paths.
FILE *	utf8_fopen (const char *filename, const char *mode)
	Opens a FILE pointer using UTF-8 filenames.
DIR *	utf8_opendir (const char *dirname)
	Opens a DIR pointer using UTF-8 paths.
char *	utf8_readdir (DIR *dir)
	Reads the next file name from an open directory.
int	utf8_loaddir (DIR *dir, char ***namelist, int(*select)(const char *), int(*compar)(const char **, const char **))
	Does the same as utf8_scandir(), but takes an open directory pointer instead of a directory path.
int	utf8_scandir (const char *dirname, char ***namelist, int(*select)(const char *), int(*compar)(const char **, const char **))
	Selects file entries from a directory, as GNU C scandir(), yet using UTF-8 file names.
int	utf8_mkdir (const char *filename, mode_t mode)
	Creates a directory using UTF-8 paths.
int	utf8_unlink (const char *filename)
	Removes a file.
int	utf8_stat (const char *filename, struct stat *buf)
	Finds file/inode informations, as stat().
int	utf8_lstat (const char *filename, struct stat *buf)
	Finds file/inode informations, as lstat().
int	utf8_vfprintf (FILE *stream, const char *fmt, va_list ap)
	Formats an UTF-8 string as vfprintf(), then print it, with appropriate conversion to local encoding.
int	utf8_fprintf (FILE *, const char *,...)
	Formats an UTF-8 string as fprintf(), then print it, with appropriate conversion to local encoding.
char *	EnsureUTF8 (char *)
	Replaces invalid/overlong UTF-8 sequences with question marks.
const char *	IsUTF8 (const char *)
	Checks whether a string is a valid UTF-8 byte sequence.
const char *	GetFallbackEncoding (void)
	GetFallbackEncoding() suggests an encoding to be used for non UTF-8 text files accord to the system's local settings.
double	us_strtod (const char *, char **)
	us_strtod() has the same prototype as ANSI C strtod() but it uses the POSIX/C decimal format, regardless of the current numeric locale.
double	us_atof (const char *)
	us_atof() has the same prototype as ANSI C atof() but it expects a dot as decimal separator, regardless of the system locale.

---

Define Documentation

#define VLC_CHARSET_H   1

---

Function Documentation

char* EnsureUTF8

(

char *

str

)

Replaces invalid/overlong UTF-8 sequences with question marks.

Note that it is not possible to convert from Latin-1 to UTF-8 on the fly, so we don't try that, even though it would be less disruptive.

Returns:

str if it was valid UTF-8, NULL if not.

char* FromLocale

(

const char *

locale

)

Converts a string from the system locale character encoding to UTF-8.

Parameters:

locale

nul-terminated string to convert

Returns:

a nul-terminated UTF-8 string, or NULL in case of error. To avoid memory leak, you have to pass the result to LocaleFree() when it is no longer needed.

char* FromLocaleDup

(

const char *

locale

)

converts a string from the system locale character encoding to utf-8, the result is always allocated on the heap.

Parameters:

locale

nul-terminated string to convert

Returns:

a nul-terminated utf-8 string, or null in case of error. The result must be freed using free() - as with the strdup() function.

const char* GetFallbackEncoding

(

void

)

GetFallbackEncoding() suggests an encoding to be used for non UTF-8 text files accord to the system's local settings.

It is only a best guess.

const char* IsUTF8

(

const char *

str

)

Checks whether a string is a valid UTF-8 byte sequence.

Parameters:

str

nul-terminated string to be checked

Returns:

str if it was valid UTF-8, NULL if not.

void LocaleFree

(

const char *

str

)

Releases (if needed) a localized or uniformized string.

Parameters:

str

non-NULL return value from FromLocale() or ToLocale().

char* ToLocale

(

const char *

utf8

)

ToLocale: converts an UTF-8 string to local system encoding.

Parameters:

utf8

nul-terminated string to be converted

Returns:

a nul-terminated string, or NULL in case of error. To avoid memory leak, you have to pass the result to LocaleFree() when it is no longer needed.

char* ToLocaleDup

(

const char *

utf8

)

converts a string from UTF-8 to the system locale character encoding, the result is always allocated on the heap.

Parameters:

utf8

nul-terminated string to convert

Returns:

a nul-terminated string, or null in case of error. The result must be freed using free() - as with the strdup() function.

double us_atof

(

const char *

)

us_atof() has the same prototype as ANSI C atof() but it expects a dot as decimal separator, regardless of the system locale.

double us_strtod	(	const char *	,
		char **
	)

us_strtod() has the same prototype as ANSI C strtod() but it uses the POSIX/C decimal format, regardless of the current numeric locale.

FILE* utf8_fopen	(	const char *	filename,
		const char *	mode
	)

Opens a FILE pointer using UTF-8 filenames.

Parameters:

	filename	file path, using UTF-8 encoding
	mode	fopen file open mode

Returns:

NULL on error, an open FILE pointer on success.

int utf8_fprintf	(	FILE *	,
		const char *	,
			...
	)

Formats an UTF-8 string as fprintf(), then print it, with appropriate conversion to local encoding.

int utf8_loaddir	(	DIR *	dir,
		char ***	namelist,
		int(*)(const char *)	select,
		int(*)(const char **, const char **)	compar
	)

Does the same as utf8_scandir(), but takes an open directory pointer instead of a directory path.

int utf8_lstat	(	const char *	filename,
		struct stat *	buf
	)

Finds file/inode informations, as lstat().

Consider usign fstat() instead, if possible.

Parameters:

filename

UTF-8 file path

int utf8_mkdir	(	const char *	dirname,
		mode_t	mode
	)

Creates a directory using UTF-8 paths.

Parameters:

	dirname	a UTF-8 string with the name of the directory that you want to create.
	mode	directory permissions

Returns:

0 on success, -1 on error (see errno).

int utf8_open	(	const char *	filename,
		int	flags,
		mode_t	mode
	)

Opens a system file handle using UTF-8 paths.

Parameters:

	filename	file path to open (with UTF-8 encoding)
	flags	open() flags, see the C library open() documentation
	mode	file permissions if creating a new file

Returns:

a file handle on success, -1 on error (see errno).

DIR* utf8_opendir

(

const char *

dirname

)

Opens a DIR pointer using UTF-8 paths.

Parameters:

dirname

UTF-8 representation of the directory name

Returns:

a pointer to the DIR struct, or NULL in case of error. Release with standard closedir().

char* utf8_readdir

(

DIR *

dir

)

Reads the next file name from an open directory.

Parameters:

dir

The directory that is being read

Returns:

a UTF-8 string of the directory entry. Use free() to free this memory.

int utf8_scandir	(	const char *	dirname,
		char ***	namelist,
		int(*)(const char *)	select,
		int(*)(const char **, const char **)	compar
	)

Selects file entries from a directory, as GNU C scandir(), yet using UTF-8 file names.

Parameters:

	dirname	UTF-8 diretory path
	pointer	[OUT] pointer set, on succesful completion, to the address of a table of UTF-8 filenames. All filenames must be freed with free(). The table itself must be freed with free() as well.

Returns:

How many file names were selected (possibly 0), or -1 in case of error.

int utf8_stat	(	const char *	filename,
		struct stat *	buf
	)

Finds file/inode informations, as stat().

Consider usign fstat() instead, if possible.

Parameters:

filename

UTF-8 file path

int utf8_unlink

(

const char *

filename

)

Removes a file.

Parameters:

filename

a UTF-8 string with the name of the file you want to delete.

Returns:

A 0 return value indicates success. A -1 return value indicates an error, and an error code is stored in errno

int utf8_vfprintf	(	FILE *	stream,
		const char *	fmt,
		va_list	ap
	)

Formats an UTF-8 string as vfprintf(), then print it, with appropriate conversion to local encoding.

---