file_help.h

//                  __  _  _             _            _          _                      //
//                 / _|(_)| |  ___      | |__    ___ | | _ __   | |__                   //
//                | |_ | || | / _ \     | '_ \  / _ \| || '_ \  | '_ \                  //
//                |  _|| || ||  __/     | | | ||  __/| || |_) |_| | | |                 //
//                |_|  |_||_| \___|_____|_| |_| \___||_|| .__/(_)_| |_|                 //
//                                |_____|               |_|                             //
//                                                                                      //
//                         helper utilities for file I/O                                //
//                                                                                      //

/*****************************************************************************

    X11workbench - X11 programmer's 'work bench' application and toolkit
    Copyright (c) 2010-2019 by Bob Frazier (aka 'Big Bad Bombastic Bob')


  DISCLAIMER:  The X11workbench application and toolkit software are supplied
               'as-is', with no warranties, either implied or explicit.
               Any claims to alleged functionality or features should be
               considered 'preliminary', and might not function as advertised.

  MIT-like license:

  There is no restriction as to what you can do with this software, so long
  as you include the above copyright notice and DISCLAIMER for any distributed
  work that is equal to or derived from this one, along with this paragraph
  that explains the terms of the license if the source is also being made
  available.  A "derived work" describes a work that uses a significant portion
  of the source files or algorithms that are included with this one.
  Specifically excluded from this are files that were generated by the software,
  or anything that is included with the software that is part of another package
  (such as files that were created or added during the 'configure' process).
  Specifically included is the use of part or all of any of the X11 workbench
  toolkit source or header files in your distributed application.  If you do not
  ship the source, the above copyright statement is still required to be placed
  in a reasonably prominent place, such as documentation, splash screens, and/or
  'about the application' dialog boxes.

  Use and distribution are in accordance with GPL, LGPL, and/or the above
  MIT-like license.  See COPYING and README files for more information.


  Additional information at http://sourceforge.net/projects/X11workbench

******************************************************************************/


#ifndef _FILE_HELP_H_INCLUDED_
#define _FILE_HELP_H_INCLUDED_

// read a file into a buffer, returning the buffer and its size

#include <limits.h>

// including the global configure script information
#ifdef X11WORKBENCH_PROJECT_BUILD

// Globally include the output of the configure script for GNUC compiles for "the project"
#include "X11workbenchToolkit_config.h" // the 'generated' version'

#else // X11WORKBENCH_PROJECT_BUILD

// This is for the installed version, a subset of the things defined by the configure output script.
// NOTE:  this must be installed in the appropriate package directory along with platform_helper.h
#include "X11workbenchToolkit_install_config.h"

#endif // X11WORKBENCH_PROJECT_BUILD


#ifdef __cplusplus
extern "C" {
#endif // __cplusplus


// use NAME_MAX to determine max buffer sizes for things that use a file name
// maximum path name limits are OS dependent.

#ifdef WIN32
#ifndef NAME_MAX
#define NAME_MAX MAX_PATH
#endif // NAME_MAX
#else // !WIN32
// POSIX systems normally define NAME_MAX in limits.h (or something it includes)
#ifndef NAME_MAX
#ifdef MAXNAMLEN
#define NAME_MAX MAXNAMLEN /* BSD defines MAXNAMLEN */
#else
#define NAME_MAX 255 /* standard value for BSD and Linux */
#endif // MAXNAMLEN
#endif // NAME_MAX
#endif // WIN32, !WIN32


// sub-groups for documentation

typedef struct tag_file_help_buf
{
  struct tag_file_help_buf *pPrev; 
  struct tag_file_help_buf *pNext; 
  long lBufferSize;                
  long lBufferCount;               
  long lLineCount;                 
  long lLineBufSize;               
  int  iFlags;                     
  char **ppLineBuf;                
  char cData[sizeof(char *)];      
} file_help_buf_t;

enum tag_file_help_buf_flags
{
  file_help_buf_dirty      = 1,    
  file_help_buf_reserved01 = 2,    
  file_help_buf_reserved02 = 4,    
  file_help_buf_reserved03 = 8,    
  file_help_buf_reserved04 = 16,   
  file_help_buf_reserved05 = 32,   
  file_help_buf_reserved06 = 64,   
  file_help_buf_reserved07 = 128,  
  file_help_buf_reserved08 = 256,  

  file_help_buf_last       = 0x80000000L
};

static __inline__ int FBIsFileBufDirty(const file_help_buf_t *pBuf)
{
  return pBuf && (pBuf->iFlags & file_help_buf_dirty);
}

file_help_buf_t *FBGetFileBufViaHandle(int iHandle);

file_help_buf_t *FBGetFileBufFromBuffer(const char *pBuf, long cbBuf);

file_help_buf_t *FBGetFileBuf(const char *szFileName);


void FBDestroyFileBuf(file_help_buf_t *pFB);


int FBParseFileBuf(file_help_buf_t *pFB);
  // parses or re-parses buffer, populating ppLineBuf

int FBWriteFileBuf(const char *szFileName, const file_help_buf_t *pFB);

int FBWriteFileBufHandle(int iHandle, const file_help_buf_t *pFB);


void FBInsertIntoFileBuf(file_help_buf_t **ppBuf, long cbOffset, const void *pData, long cbData);

void FBDeleteFromFileBuf(file_help_buf_t *pBuf, long cbOffset, long cbDelFrom);


void FBInsertLineIntoFileBuf(file_help_buf_t **ppBuf, long lLineNum, const char *szLine);


void FBDeleteLineFromFileBuf(file_help_buf_t *pBuf, long lLineNum);


void FBReplaceLineInFileBuf(file_help_buf_t **ppBuf, long lLineNum, const char *szLine);


static __inline__ int FBWriteFileFromBuffer(const char *szFileName, const char *pBuf, unsigned int cbBuf)
{
int iRval;
file_help_buf_t *pFB;


  pFB = FBGetFileBufFromBuffer(pBuf, cbBuf);

  if(!pFB)
  {
//    WB_ERROR_PRINT("ERROR - %s - unable to create file buf\n", __FUNCTION__);
    return -1;
  }

  iRval = FBWriteFileBuf(szFileName, pFB);

  FBDestroyFileBuf(pFB);

//  if(iRval < 0)
//  {
//    WB_ERROR_PRINT("ERROR - %s - unable to create file \"%s\" from file buf\n", __FUNCTION__, szFileName);
//  }

  return iRval;
}



size_t WBReadFileIntoBuffer(const char *szFileName, char **ppBuf);

int WBWriteFileFromBuffer(const char *szFileName, const char *pBuf, size_t cbBuf);


// SYSTEM INDEPENDENT FILE STATUS, LISTINGS, AND INFORMATION

int WBReplicateFilePermissions(const char *szProto, const char *szTarget);

char *WBGetCurrentDirectory(void);

int WBIsDirectory(const char *szName);

char *WBGetCanonicalPath(const char *szFileName);

void *WBAllocDirectoryList(const char *szDirSpec);

void WBDestroyDirectoryList(void *pDirectoryList);

int WBNextDirectoryEntry(void *pDirectoryList, char *szNameReturn,
                         int cbNameReturn, unsigned long *pdwModeAttrReturn);

char *WBGetDirectoryListFileFullPath(const void *pDirectoryList, const char *szFileName);

char *WBGetSymLinkTarget(const char *szFileName);

char *WBGetDirectoryListSymLinkTarget(const void *pDirectoryList, const char *szFileName);

int WBStat(const char *szFileName, unsigned long *pdwModeAttrReturn);

int WBGetDirectoryListFileStat(const void *pDirectoryList, const char *szFileName,
                               unsigned long *pdwModeAttrReturn);


#if defined(HAVE_LONGLONG) || defined(__DOXYGEN__)

unsigned long long WBGetFileModDateTime(const char *szFileName);                // return file mod date/time as time_t (seconds since epoch)


int WBCheckFileModDateTime(const char *szFileName, unsigned long long tVal);    // check time_t value against file mod date/time, return comparison

#else  // defined(HAVE_LONGLONG) || defined(__DOXYGEN__)

// use a 32-bit integer or whatever 'long' is defined as
unsigned long WBGetFileModDateTime(const char *szFileName);
int WBCheckFileModDateTime(const char *szFileName, unsigned long tVal);

#endif // defined(HAVE_LONGLONG) || defined(__DOXYGEN__)


#ifdef __cplusplus
};
#endif // __cplusplus


#endif // _FILE_HELP_H_INCLUDED_