File names and URI utility functions

File names and URI functions defined in <FL/filename.H> More...

Macros
#define	FL_PATH_MAX   2048
	all path buffers should use this length

Typedefs
typedef int()	Fl_File_Sort_F(struct dirent **, struct dirent **)
	File sorting function. More...

Functions
void	fl_decode_uri (char *uri)
	Decodes a URL-encoded string. More...
int	fl_filename_absolute (char *to, int tolen, const char *from)
	Makes a filename absolute from a relative filename to the current working directory. More...
int	fl_filename_absolute (char *to, int tolen, const char *from, const char *cwd)
	Concatenate the absolute path base with from to form the new absolute path in to. More...
std::string	fl_filename_absolute_str (const std::string &from)
	Makes a filename absolute from a filename relative to the current working directory. More...
std::string	fl_filename_absolute_str (const std::string &from, const std::string &base)
	Append the relative filename from to the absolute filename base to form the new absolute path. More...
int	fl_filename_expand (char *to, int tolen, const char *from)
	Expands a filename containing shell variables and tilde (~). More...
std::string	fl_filename_expand_str (const std::string &from)
	Expands a filename containing shell variables and tilde (~). More...
const char *	fl_filename_ext (const char *buf)
	Gets the extension of a filename. More...
std::string	fl_filename_ext_str (const std::string &filename)
	Return a new string that contains the filename extension. More...
void	fl_filename_free_list (struct dirent ***l, int n)
	Free the list of filenames that is generated by fl_filename_list(). More...
int	fl_filename_isdir (const char *name)
	Determines if a file exists and is a directory from its filename. More...
int	fl_filename_list (const char *d, struct dirent ***l, Fl_File_Sort_F *s=fl_numericsort)
	Portable and const-correct wrapper for the scandir() function. More...
int	fl_filename_match (const char *name, const char *pattern)
	Checks if a string s matches a pattern p. More...
const char *	fl_filename_name (const char *filename)
	Gets the file name from a path. More...
std::string	fl_filename_name_str (const std::string &filename)
	Return a new string that contains the name part of the filename. More...
std::string	fl_filename_path_str (const std::string &filename)
	Return a new string that contains the path part of the filename. More...
int	fl_filename_relative (char *to, int tolen, const char *from)
	Makes a filename relative to the current working directory. More...
int	fl_filename_relative (char *to, int tolen, const char *from, const char *cwd)
	Makes a filename relative to any other directory. More...
std::string	fl_filename_relative_str (const std::string &from)
	Makes a filename relative to the current working directory. More...
std::string	fl_filename_relative_str (const std::string &from, const std::string &base)
	Makes a filename relative to any directory. More...
char *	fl_filename_setext (char *to, int tolen, const char *ext)
	Replaces the extension in buf of max. More...
std::string	fl_filename_setext_str (const std::string &filename, const std::string &new_extension)
	Return a copy of the old filename with the new extension. More...
std::string	fl_getcwd_str ()
	Cross-platform function to get the current working directory as a UTF-8 encoded value in an std::string. More...
int	fl_open_uri (const char *uri, char *msg, int msglen)
	Opens the specified Uniform Resource Identifier (URI). More...

Detailed Description

File names and URI functions defined in <FL/filename.H>

Typedef Documentation

Fl_File_Sort_F

typedef int() Fl_File_Sort_F(struct dirent **, struct dirent **)

File sorting function.

See also

fl_filename_list()

Function Documentation

fl_decode_uri()

void fl_decode_uri

(

char *

uri

)

Decodes a URL-encoded string.

In a Uniform Resource Identifier (URI), all non-ASCII bytes and several others (e.g., '<', '', ' ') are URL-encoded using 3 bytes by "%XY" where XY is the hexadecimal value of the byte. This function decodes the URI restoring its original UTF-8 encoded content. Decoding is done in-place.

fl_filename_absolute() [1/2]

int fl_filename_absolute	(	char *	to,
		int	tolen,
		const char *	from
	)

Makes a filename absolute from a relative filename to the current working directory.

#include <FL/filename.H>
[..]
fl_chdir("/var/tmp");
fl_filename_absolute(out, sizeof(out), "foo.txt");         // out="/var/tmp/foo.txt"
fl_filename_absolute(out, sizeof(out), "./foo.txt");       // out="/var/tmp/foo.txt"
fl_filename_absolute(out, sizeof(out), "../log/messages"); // out="/var/log/messages"

Parameters

[out]	to	resulting absolute filename
[in]	tolen	size of the absolute filename buffer
[in]	from	relative filename

Returns

0 if no change, non zero otherwise

fl_filename_absolute() [2/2]

int fl_filename_absolute	(	char *	to,
		int	tolen,
		const char *	from,
		const char *	base
	)

Concatenate the absolute path base with from to form the new absolute path in to.

#include <FL/filename.H>
char out[FL_PATH_MAX];
fl_filename_absolute(out, sizeof(out), "../foo.txt", "/var/tmp");   // out="/var/foo.txt"
fl_filename_absolute(out, sizeof(out), "../local/bin", "/usr/bin");  // out="/usr/local/bin"

Parameters

[out]	to	resulting absolute filename
[in]	tolen	size of the absolute filename buffer
[in]	from	relative filename
[in]	base	from is relative to this absolute file path

Returns

0 if no change, non zero otherwise

fl_filename_absolute_str() [1/2]

std::string fl_filename_absolute_str

(

const std::string &

from

)

Makes a filename absolute from a filename relative to the current working directory.

Parameters

[in]

from

relative filename

Returns

the new, absolute filename

See also

fl_filename_absolute(char *to, int tolen, const char *from)

fl_filename_absolute_str() [2/2]

std::string fl_filename_absolute_str	(	const std::string &	from,
		const std::string &	base
	)

Append the relative filename from to the absolute filename base to form the new absolute path.

Parameters

[in]	from	relative filename
[in]	base	from is relative to this absolute file path

Returns

the new, absolute filename

See also

fl_filename_absolute(char *to, int tolen, const char *from, const char *base)

fl_filename_expand()

int fl_filename_expand	(	char *	to,
		int	tolen,
		const char *	from
	)

Expands a filename containing shell variables and tilde (~).

Currently handles these variants:

"~username"               // if 'username' does not exist, result will be unchanged
"~/file"
"$VARNAME"                // does NOT handle ${VARNAME}

Examples:

#include <FL/filename.H>
[..]
putenv("TMPDIR=/var/tmp");
fl_filename_expand(out, sizeof(out), "~fred/.cshrc");     // out="/usr/fred/.cshrc"
fl_filename_expand(out, sizeof(out), "~/.cshrc");         // out="/usr/<yourname>/.cshrc"
fl_filename_expand(out, sizeof(out), "$TMPDIR/foo.txt");  // out="/var/tmp/foo.txt"

Parameters

[out]	to	resulting expanded filename
[in]	tolen	size of the expanded filename buffer
[in]	from	filename containing shell variables

Returns

0 if no change, non zero otherwise

fl_filename_expand_str()

std::string fl_filename_expand_str

(

const std::string &

from

)

Expands a filename containing shell variables and tilde (~).

Parameters

[in]

from

file path and name

Returns

the new, expanded filename

See also

fl_filename_expand(char *to, int tolen, const char *from)

fl_filename_ext()

const char * fl_filename_ext

(

const char *

buf

)

Gets the extension of a filename.

#include <FL/filename.H>
[..]
const char *out;
out = fl_filename_ext("/some/path/foo.txt");        // result: ".txt"
out = fl_filename_ext("/some/path/foo");            // result: NULL

Parameters

[in]

buf

the filename to be parsed

Returns

a pointer to the extension (including '.') if any or NULL otherwise

fl_filename_ext_str()

std::string fl_filename_ext_str

(

const std::string &

filename

)

Return a new string that contains the filename extension.

Parameters

[in]

filename

file path and name

Returns

the filename extension including the prepending '.', or an empty string if the filename has no extension

See also

fl_filename_ext(const char *buf)

fl_filename_free_list()

void fl_filename_free_list	(	struct dirent ***	list,
		int	n
	)

Free the list of filenames that is generated by fl_filename_list().

Free everything that was allocated by a previous call to fl_filename_list(). Use the return values as parameters for this function.

Parameters

[in,out]	list	table containing the resulting directory listing
[in]	n	number of entries in the list

fl_filename_isdir()

int fl_filename_isdir

(

const char *

n

)

Determines if a file exists and is a directory from its filename.

#include <FL/filename.H>
[..]
fl_filename_isdir("/etc");           // returns non-zero
fl_filename_isdir("/etc/hosts");     // returns 0

Parameters

[in]

n

the filename to parse

Returns

non zero if file exists and is a directory, zero otherwise

fl_filename_list()

int fl_filename_list	(	const char *	d,
		dirent ***	list,
		Fl_File_Sort_F *	sort
	)

Portable and const-correct wrapper for the scandir() function.

For each file in that directory a "dirent" structure is created. The only portable thing about a dirent is that dirent.d_name is the nul-terminated file name. A pointers array to these dirent's is created and a pointer to the array is returned in *list. The number of entries is given as a return value. If there is an error reading the directory a number less than zero is returned, and errno has the reason; errno does not work under Windows.

Include:

#include <FL/filename.H>

Parameters

[in]	d	the name of the directory to list. It does not matter if it has a trailing slash.
[out]	list	table containing the resulting directory listing
[in]	sort	sorting functor: fl_alphasort: The files are sorted in ascending alphabetical order; upper and lowercase letters are compared according to their ASCII ordering uppercase before lowercase. fl_casealphasort: The files are sorted in ascending alphabetical order; upper and lowercase letters are compared equally case is not significant. fl_casenumericsort: The files are sorted in ascending "alphanumeric" order, where an attempt is made to put unpadded numbers in consecutive order; upper and lowercase letters are compared equally case is not significant. fl_numericsort: The files are sorted in ascending "alphanumeric" order, where an attempt is made to put unpadded numbers in consecutive order; upper and lowercase letters are compared according to their ASCII ordering - uppercase before lowercase.

Returns

the number of entries if no error, a negative value otherwise.

Todo:

should support returning OS error messages

fl_filename_match()

int fl_filename_match	(	const char *	s,
		const char *	p
	)

Checks if a string s matches a pattern p.

The following syntax is used for the pattern:

• * matches any sequence of 0 or more characters.
• ? matches any single character.
• [set] matches any character in the set. Set can contain any single characters, or a-z to represent a range. To match ] or - they must be the first characters. To match ^ or ! they must not be the first characters.
• [^set] or [!set] matches any character not in the set.
• {X|Y|Z} or {X,Y,Z} matches any one of the subexpressions literally.
• \x quotes the character x so it has no special meaning.
• x all other characters are matched "exactly" on a case-insensitive basis.

Notes:

• s and p are matched on a char/byte basis, not as UCS codepoints or UTF-8 sequences.
• [set] ranges must run from low to high, i.e. [a-z] and not [z-a]
• [set] comparison is case-sensitive, i.e. [a-z] won't match "A".
• \x only applies to the fl_filename_match special characters * ? [ {
• \x needs a double \ or the compiler will complain about non-standard escape sequences.

Include:

#include <FL/filename.H>

Parameters

[in]	s	the string to check for a match
[in]	p	the string pattern

Returns

non zero if the string matches the pattern

fl_filename_name()

const char * fl_filename_name

(

const char *

filename

)

Gets the file name from a path.

Similar to basename(3), exceptions shown below.

#include <FL/filename.H>
[..]
const char *out;
out = fl_filename_name("/usr/lib");     // out="lib"
out = fl_filename_name("/usr/");        // out=""      (basename(3) returns "usr" instead)
out = fl_filename_name("/usr");         // out="usr"
out = fl_filename_name("/");            // out=""      (basename(3) returns "/" instead)
out = fl_filename_name(".");            // out="."
out = fl_filename_name("..");           // out=".."

Returns

a pointer to the char after the last slash, or to filename if there is none.

fl_filename_name_str()

std::string fl_filename_name_str

(

const std::string &

filename

)

Return a new string that contains the name part of the filename.

Parameters

[in]

filename

file path and name

Returns

the name part of a filename

See also

fl_filename_name(const char *filename)

fl_filename_path_str()

std::string fl_filename_path_str

(

const std::string &

filename

)

Return a new string that contains the path part of the filename.

Parameters

[in]

filename

file path and name

Returns

the path part of a filename without the name

See also

fl_filename_name(const char *filename)

fl_filename_relative() [1/2]

int fl_filename_relative	(	char *	to,
		int	tolen,
		const char *	from
	)

Makes a filename relative to the current working directory.

Return the from path made relative to the working directory, similar to C++17 std::filesystem::path::lexically_relative. This function can also be called with a fourth argument for a user supplied base directory path

These conversions are purely lexical. They do not check that the paths exist, do not follow symlinks, and do not access the filesystem at all.

Path arguments must be absolute (start at the root directory) and must not contain . or .. segments, or double separators. A single trailing separator is ok.

On Windows, path arguments must start with a drive name, e.g. c:\. Windows network paths and other special paths starting with a double separator are not supported (\\cloud\drive\path, \\?\, etc.) . Separators can be \ and / and will be preserved. Newly created separators are alway the forward slash /.

On Windows and macOS, the path segment tests are case insensitive.

If the path can not be generated, from path is copied into the to buffer and 0 is returned.

#include <FL/filename.H>
[..]
fl_chdir("/var/tmp/somedir");       // set cwd to /var/tmp/somedir
[..]
char out[FL_PATH_MAX];
fl_filename_relative(out, sizeof(out), "/var/tmp/somedir/foo.txt");  // out="foo.txt",    return=1
fl_filename_relative(out, sizeof(out), "/var/tmp/foo.txt");          // out="../foo.txt", return=1
fl_filename_relative(out, sizeof(out), "foo.txt");                   // out="foo.txt",    return=0 (no change)
fl_filename_relative(out, sizeof(out), "./foo.txt");                 // out="./foo.txt",  return=0 (no change)
fl_filename_relative(out, sizeof(out), "../foo.txt");                // out="../foo.txt", return=0 (no change)

Parameters

[out]	to	resulting relative filename
[in]	tolen	size of the relative filename buffer
[in]	from	absolute filename

Returns

0 if no change, non zero otherwise

See also

fl_filename_relative(char *to, int tolen, const char *from, const char *base)

fl_filename_relative() [2/2]

int fl_filename_relative	(	char *	to,
		int	tolen,
		const char *	from,
		const char *	base
	)

Makes a filename relative to any other directory.

Parameters

[out]	to	resulting relative filepath
[in]	tolen	size of the relative filename buffer
[in]	from	absolute filepath
[in]	base	generate filepath relative to this absolute filepath

Returns

0 if no change, non zero otherwise

See also

fl_filename_relative(char *to, int tolen, const char *from)

fl_filename_relative_str() [1/2]

std::string fl_filename_relative_str

(

const std::string &

from

)

Makes a filename relative to the current working directory.

Parameters

[in]

from

file path and name

Returns

the new, relative filename

See also

fl_filename_relative(char *to, int tolen, const char *from)

fl_filename_relative_str() [2/2]

std::string fl_filename_relative_str	(	const std::string &	from,
		const std::string &	base
	)

Makes a filename relative to any directory.

Parameters

[in]	from	file path and name
[in]	base	relative to this absolute path

Returns

the new, relative filename

See also

fl_filename_relative(char *to, int tolen, const char *from, const char *base)

fl_filename_setext()

char * fl_filename_setext	(	char *	buf,
		int	buflen,
		const char *	ext
	)

Replaces the extension in buf of max.

size buflen with the extension in ext.
If there's no '.' in buf, ext is appended.
If ext is NULL, behaves as if it were an empty string ("").

Example

#include <FL/filename.H>
[..]
char buf[FL_PATH_MAX] = "/path/myfile.cxx";
fl_filename_setext(buf, sizeof(buf), ".txt");      // buf[] becomes "/path/myfile.txt"

Returns

buf itself for calling convenience.

fl_filename_setext_str()

std::string fl_filename_setext_str	(	const std::string &	filename,
		const std::string &	new_extension
	)

Return a copy of the old filename with the new extension.

Parameters

[in]	filename	file path and name
[in]	new_extension	new filename extension, starts with a '.'

Returns

the new filename

See also

fl_filename_setext(char *to, int tolen, const char *ext)

fl_getcwd_str()

std::string fl_getcwd_str

(

)

Cross-platform function to get the current working directory as a UTF-8 encoded value in an std::string.

Returns

the CWD encoded as UTF-8

fl_open_uri()

int fl_open_uri	(	const char *	uri,
		char *	msg,
		int	msglen
	)

Opens the specified Uniform Resource Identifier (URI).

Uses an operating-system dependent program or interface. For URIs using the "ftp", "http", or "https" schemes, the system default web browser is used to open the URI, while "mailto" and "news" URIs are typically opened using the system default mail reader and "file" URIs are opened using the file system navigator.

On success, the (optional) msg buffer is filled with the command that was run to open the URI; on Windows, this will always be "open uri".

On failure, the msg buffer is filled with an English error message.

Note

Platform Specific Issues: Windows
With "file:" based URIs on Windows, you may encounter issues with anchors being ignored. Example: "file:///c:/some/index.html#anchor" may open in the browser without the "#anchor" suffix. The behavior seems to vary across different Windows versions. Workaround: open a link to a separate html file that redirects to the desired "file:" URI.

Example

#include <FL/filename.H>
[..]
char errmsg[512];
if ( !fl_open_uri("http://google.com/", errmsg, sizeof(errmsg)) ) {
    char warnmsg[768];
    sprintf(warnmsg, "Error: %s", errmsg);
    fl_alert(warnmsg);
}

Parameters

uri	The URI to open
msg	Optional buffer which contains the command or error message
msglen	Length of optional buffer

Returns

1 on success, 0 on failure