FLTK 1.3.7: File names and URI utility functions

FLTK 1.3.7

Macros | Typedefs | Functions
File names and URI utility functions

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

## Macros
#define | fl_dirent_h_cyclic_include
#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
FL_EXPORT void | fl_decode_uri (char *uri)
| Decodes a URL-encoded string. More...
FL_EXPORT int | fl_filename_absolute (char *to, int tolen, const char *from)
| Makes a filename absolute from a relative filename. More...
FL_EXPORT int | fl_filename_expand (char *to, int tolen, const char *from)
| Expands a filename containing shell variables and tilde (~). More...
FL_EXPORT const char * | fl_filename_ext (const char *buf)
| Gets the extensions of a filename. More...
FL_EXPORT void | fl_filename_free_list (struct dirent ***l, int n)
| Free the list of filenames that is generated by fl_filename_list(). More...
FL_EXPORT int | fl_filename_isdir (const char *name)
| Determines if a file exists and is a directory from its filename. More...
FL_EXPORT 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...
FL_EXPORT int | fl_filename_match (const char *name, const char *pattern)
| Checks if a string `s` matches a pattern `p`. More...
FL_EXPORT const char * | fl_filename_name (const char *filename)
| Gets the file name from a path. More...
FL_EXPORT int | fl_filename_relative (char *to, int tolen, const char *from)
| Makes a filename relative to the current working directory. More...
FL_EXPORT char * | fl_filename_setext (char *to, int tolen, const char *ext)
| Replaces the extension in `buf` of max. More...
FL_EXPORT 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()

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

Makes a filename absolute from a relative filename.

#include <FL/filename.H>
[..]
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"
filename.H
File names and URI utility functions.
fl_filename_absolute
FL_EXPORT int fl_filename_absolute(char *to, int tolen, const char *from)
Makes a filename absolute from a relative filename.
Definition: filename_absolute.cxx:56

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

FL_EXPORT 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"
fl_filename_expand
FL_EXPORT int fl_filename_expand(char *to, int tolen, const char *from)
Expands a filename containing shell variables and tilde (~).
Definition: filename_expand.cxx:63

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

FL_EXPORT const char* fl_filename_ext | ( | const char * | buf | ) |

Gets the extensions 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
fl_filename_ext
FL_EXPORT const char * fl_filename_ext(const char *buf)
Gets the extensions of a filename.
Definition: filename_ext.cxx:34

Parameters

  [in] | buf | the filename to be parsed

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

## ◆ fl_filename_free_list()

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

FL_EXPORT 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
fl_filename_isdir
FL_EXPORT int fl_filename_isdir(const char *name)
Determines if a file exists and is a directory from its filename.
Definition: filename_isdir.cxx:52

Parameters

  [in] | n | the filename to parse

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

## ◆ fl_filename_list()

FL_EXPORT 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. An 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 WIN32.

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.

## ◆ fl_filename_match()

FL_EXPORT 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 must be matched exactly.

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

FL_EXPORT 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=".."
fl_filename_name
FL_EXPORT const char * fl_filename_name(const char *filename)
Gets the file name from a path.

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

## ◆ fl_filename_relative()

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

Makes a filename relative to the current working directory.

#include <FL/filename.H>
[..]
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)
FL_PATH_MAX
#define FL_PATH_MAX
all path buffers should use this length
Definition: filename.H:38
fl_filename_relative
FL_EXPORT int fl_filename_relative(char *to, int tolen, const char *from)
Makes a filename relative to the current working directory.
Definition: filename_absolute.cxx:128

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

## ◆ fl_filename_setext()

FL_EXPORT 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"
fl_filename_setext
FL_EXPORT char * fl_filename_setext(char *to, int tolen, const char *ext)
Replaces the extension in buf of max.
Definition: filename_setext.cxx:40

Returns
  buf itself for calling convenience.

## ◆ 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);
}
fl_open_uri
FL_EXPORT int fl_open_uri(const char *uri, char *msg=(char *) 0, int msglen=0)
Opens the specified Uniform Resource Identifier (URI).
Definition: fl_open_uri.cxx:98
fl_alert
void fl_alert(const char *fmt,...)
Shows an alert message dialog box.
Definition: fl_ask.cxx:361

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

- Copyright © 1998-2021 by Bill Spitzak and others.