/*
 * ============================================================================
 *  FILE_UTIL:      File-related Utility Functions
 *
 *  Author:         J. Zbiciak
 *  Last Revision:  8/29/98
 * ============================================================================
 *
 *  Exported functionality declared in this file:
 *
 *  F_ESCAPE_STR    -- escapes non-filename-safe characters within a string.
 *  F_UNESCAPE_STR  -- unescapes non-filename-safe characters within a string.
 *  F_FILE_EXISTS   -- Determines if a given file exists.
 *  F_DIR_EXISTS    -- Determines if a given file exists and is a directory.
 *  F_CREATE_DIR    -- Creates a directory, removing any file that might
 *                     exist, but only if the overwrite flag is set.
 *
 * ============================================================================
 */

#ifndef _FILE_UTIL_H
#define _FILE_UTIL_H

/*
 * ============================================================================
 * ============================================================================
 *  EXPORTED FUNCTION DEFINITIONS
 * ============================================================================
 * ============================================================================
 */

/*
 * ============================================================================
 *  F_ESCAPE_STR    -- escapes non-filename-safe characters within a string.
 *
 *  This routine accepts a pointer to the string to be escaped, and a pointer
 *  to the buffer where the escaped string is to be written.
 *
 *  In addition to control characters and characters above ASCII 126, the 
 *  following characters are escaped out of filenames using the HTML-esqe 
 *  "%xx" style escape sequence.
 *
 *       % * ? / \ < > & - + ~ ` ' " | { } [ ] ( ) @ # $ ! [SPACE]
 *
 *  Additionally, periods are escaped out when they appear as the first 
 *  character of a filename.
 *
 *  To avoid buffer overflow, the output string buffer must be able to hold
 *  an output string that is three times larger than the input string, since
 *  the most a given string will expand is 3:1.
 *
 *  Return values: 
 *       0  -- string successfully escaped.
 *      -1  -- invalid arguments passed to f_escape_string().
 * ============================================================================
 */
int 
f_escape_string
(
    const char  *s1,                /* String to escape                 */
    char        *s2                 /* Escaped string                   */
);

/*
 * ============================================================================
 *  F_UNESCAPE_STR  -- unescapes non-filename-safe characters within a string.
 *
 *  This routine accepts a pointer to an escaped string, and returns the 
 *  non-escaped version of the string.  Aside from being ASCII-specific,
 *  this code is not nearly as complex as f_escape_str(), because all escape
 *  sequences are un-escaped.
 *
 *  Notes:
 *  -- Escape sequences must be of the form %XX where XX is the uppercase
 *     hex code for the ASCII value of the character being escaped.  
 *
 *  -- Invalid and incomplete escape sequences will cause the unescape 
 *     process to abort with an error.
 *
 *  Return values: 
 *       0  -- string successfully unescaped.
 *      -1  -- invalid arguments, or invalid escape sequence encountered.
 * ============================================================================
 */
int 
f_unescape_string
(
    const char  *s1,                /* String to unescape               */
    char        *s2                 /* Unescaped string                 */
);


/*
 * ============================================================================
 *  F_FILE_EXISTS   -- Determines if a given file exists.
 * ============================================================================
 */

int 
f_file_exists
(
    const char *pathname
);

/*
 * ============================================================================
 *  F_DIR_EXISTS    -- Determines if a given file exists and is a directory.
 * ============================================================================
 */
int 
f_dir_exists
(
    const char *pathname
);

/*
 * ============================================================================
 *  F_CREATE_DIR    -- Creates a directory, removing any file that might
 *                     exist, but only if the overwrite flag is set.
 * ============================================================================
 */
int 
f_create_dir
(
    const char *pathname, 
    int overwrite
);


#endif

/*
 * ============================================================================
 *                      Copyright (c) 1998, Joseph Zbiciak.
 * ============================================================================
 */