X11workbench Toolkit  1.0
file_help.h
1 // __ _ _ _ _ _ //
3 // / _|(_)| | ___ | |__ ___ | | _ __ | |__ //
4 // | |_ | || | / _ \ | '_ \ / _ \| || '_ \ | '_ \ //
5 // | _|| || || __/ | | | || __/| || |_) |_| | | | //
6 // |_| |_||_| \___|_____|_| |_| \___||_|| .__/(_)_| |_| //
7 // |_____| |_| //
8 // //
9 // helper utilities for file I/O //
10 // //
12 
13 /*****************************************************************************
14 
15  X11workbench - X11 programmer's 'work bench' application and toolkit
16  Copyright (c) 2010-2018 by Bob Frazier (aka 'Big Bad Bombastic Bob')
17  all rights reserved
18 
19  DISCLAIMER: The X11workbench application and toolkit software are supplied
20  'as-is', with no warranties, either implied or explicit.
21  Any claims to alleged functionality or features should be
22  considered 'preliminary', and might not function as advertised.
23 
24  BSD-like license:
25 
26  There is no restriction as to what you can do with this software, so long
27  as you include the above copyright notice and DISCLAIMER for any distributed
28  work that is equal to or derived from this one, along with this paragraph
29  that explains the terms of the license if the source is also being made
30  available. A "derived work" describes a work that uses a significant portion
31  of the source files or algorithms that are included with this one.
32  Specifically excluded from this are files that were generated by the software,
33  or anything that is included with the software that is part of another package
34  (such as files that were created or added during the 'configure' process).
35  Specifically included is the use of part or all of any of the X11 workbench
36  toolkit source or header files in your distributed application. If you do not
37  ship the source, the above copyright statement is still required to be placed
38  in a reasonably prominent place, such as documentation, splash screens, and/or
39  'about the application' dialog boxes.
40 
41  Use and distribution are in accordance with GPL, LGPL, and/or the above
42  BSD-like license. See COPYING and README files for more information.
43 
44 
45  Additional information at http://sourceforge.net/projects/X11workbench
46 
47 ******************************************************************************/
48 
49 
50 #ifndef _FILE_HELP_H_INCLUDED_
51 #define _FILE_HELP_H_INCLUDED_
52 
53 // read a file into a buffer, returning the buffer and its size
54 
55 #include <limits.h>
56 
57 // including the global configure script information
58 #ifdef X11WORKBENCH_PROJECT_BUILD
59 
60 // Globally include the output of the configure script for GNUC compiles for "the project"
61 #include "X11workbenchToolkit_config.h" // the 'generated' version'
62 
63 #else // X11WORKBENCH_PROJECT_BUILD
64 
65 // This is for the installed version, a subset of the things defined by the configure output script.
66 // NOTE: this must be installed in the appropriate package directory along with platform_helper.h
67 #include "X11workbenchToolkit_install_config.h"
68 
69 #endif // X11WORKBENCH_PROJECT_BUILD
70 
71 
72 #ifdef __cplusplus
73 extern "C" {
74 #endif // __cplusplus
75 
76 
77 // use NAME_MAX to determine max buffer sizes for things that use a file name
78 // maximum path name limits are OS dependent.
79 
80 #ifdef WIN32
81 #ifndef NAME_MAX
82 #define NAME_MAX MAX_PATH
83 #endif // NAME_MAX
84 #else // !WIN32
85 // POSIX systems normally define NAME_MAX in limits.h (or something it includes)
86 #ifndef NAME_MAX
87 #ifdef MAXNAMLEN
88 #define NAME_MAX MAXNAMLEN /* BSD defines MAXNAMLEN */
89 #else
90 #define NAME_MAX 255 /* standard value for BSD and Linux */
91 #endif // MAXNAMLEN
92 #endif // NAME_MAX
93 #endif // WIN32, !WIN32
94 
95 
96 // sub-groups for documentation
97 
162 typedef struct __file_help_buf__
163 {
166  long lBufferSize;
168  long lLineCount;
170  int iFlags;
171  char **ppLineBuf;
172  char cData[sizeof(char *)];
174 
185 {
186  file_help_buf_dirty = 1,
187  file_help_buf_reserved01 = 2,
188  file_help_buf_reserved02 = 4,
189  file_help_buf_reserved03 = 8,
190  file_help_buf_reserved04 = 16,
191  file_help_buf_reserved05 = 32,
192  file_help_buf_reserved06 = 64,
193  file_help_buf_reserved07 = 128,
194  file_help_buf_reserved08 = 256,
195 
196  file_help_buf_last = 0x80000000L
197 };
198 
210 static __inline__ int FBIsFileBufDirty(const file_help_buf_t *pBuf)
211 {
212  return pBuf && (pBuf->iFlags & file_help_buf_dirty);
213 }
214 
228 file_help_buf_t *FBGetFileBufViaHandle(int iHandle);
229 
245 file_help_buf_t *FBGetFileBufFromBuffer(const char *pBuf, long cbBuf);
246 
260 file_help_buf_t *FBGetFileBuf(const char *szFileName);
261 
262 
274 void FBDestroyFileBuf(file_help_buf_t *pFB);
275 
276 
290 int FBParseFileBuf(file_help_buf_t *pFB);
291  // parses or re-parses buffer, populating ppLineBuf
292 
306 int FBWriteFileBuf(const char *szFileName, const file_help_buf_t *pFB);
307 
321 int FBWriteFileBufHandle(int iHandle, const file_help_buf_t *pFB);
322 
323 
339 void FBInsertIntoFileBuf(file_help_buf_t **ppBuf, long cbOffset, const void *pData, long cbData);
340 
354 void FBDeleteFromFileBuf(file_help_buf_t *pBuf, long cbOffset, long cbDelFrom);
355 
356 
373 void FBInsertLineIntoFileBuf(file_help_buf_t **ppBuf, long lLineNum, const char *szLine);
374 
375 
390 void FBDeleteLineFromFileBuf(file_help_buf_t *pBuf, long lLineNum);
391 
392 
410 void FBReplaceLineInFileBuf(file_help_buf_t **ppBuf, long lLineNum, const char *szLine);
411 
412 
423 static __inline__ int FBWriteFileFromBuffer(const char *szFileName, const char *pBuf, unsigned int cbBuf)
424 {
425 int iRval;
426 file_help_buf_t *pFB;
427 
428 
429  pFB = FBGetFileBufFromBuffer(pBuf, cbBuf);
430 
431  if(!pFB)
432  {
433 // WB_ERROR_PRINT("ERROR - %s - unable to create file buf\n", __FUNCTION__);
434  return -1;
435  }
436 
437  iRval = FBWriteFileBuf(szFileName, pFB);
438 
439  FBDestroyFileBuf(pFB);
440 
441 // if(iRval < 0)
442 // {
443 // WB_ERROR_PRINT("ERROR - %s - unable to create file \"%s\" from file buf\n", __FUNCTION__, szFileName);
444 // }
445 
446  return iRval;
447 }
448 
449 
450 
463 size_t WBReadFileIntoBuffer(const char *szFileName, char **ppBuf);
464 
478 int WBWriteFileFromBuffer(const char *szFileName, const char *pBuf, size_t cbBuf);
479 
480 
481 // SYSTEM INDEPENDENT FILE STATUS, LISTINGS, AND INFORMATION
482 
497 int WBReplicateFilePermissions(const char *szProto, const char *szTarget);
498 
509 char *WBGetCurrentDirectory(void);
510 
522 int WBIsDirectory(const char *szName);
523 
539 char *WBGetCanonicalPath(const char *szFileName);
540 
561 void *WBAllocDirectoryList(const char *szDirSpec);
562 
572 void WBDestroyDirectoryList(void *pDirectoryList);
573 
588 int WBNextDirectoryEntry(void *pDirectoryList, char *szNameReturn,
589  int cbNameReturn, unsigned long *pdwModeAttrReturn);
590 
604 char *WBGetDirectoryListFileFullPath(const void *pDirectoryList, const char *szFileName);
605 
619 char *WBGetSymLinkTarget(const char *szFileName);
620 
636 char *WBGetDirectoryListSymLinkTarget(const void *pDirectoryList, const char *szFileName);
637 
649 int WBStat(const char *szFileName, unsigned long *pdwModeAttrReturn);
650 
664 int WBGetDirectoryListFileStat(const void *pDirectoryList, const char *szFileName,
665  unsigned long *pdwModeAttrReturn);
666 
667 
668 #if defined(HAVE_LONGLONG) || defined(__DOXYGEN__)
669 
681 unsigned long long WBGetFileModDateTime(const char *szFileName); // return file mod date/time as time_t (seconds since epoch)
682 
683 
698 int WBCheckFileModDateTime(const char *szFileName, unsigned long long tVal); // check time_t value against file mod date/time, return comparison
699 
700 #else // defined(HAVE_LONGLONG) || defined(__DOXYGEN__)
701 
702 // use a 32-bit integer or whatever 'long' is defined as
703 unsigned long WBGetFileModDateTime(const char *szFileName);
704 int WBCheckFileModDateTime(const char *szFileName, unsigned long tVal);
705 
706 #endif // defined(HAVE_LONGLONG) || defined(__DOXYGEN__)
707 
708 
709 #ifdef __cplusplus
710 };
711 #endif // __cplusplus
712 
713 
714 #endif // _FILE_HELP_H_INCLUDED_
715 
basic &#39;buffered I/O&#39; object structure for &#39;FileBuf&#39; APIs
Definition: file_help.h:162
int iFlags
various bit flags
Definition: file_help.h:170
__file_help_buf_flags__
bit flags for file_help_buf_t &#39;iFlags&#39; member
Definition: file_help.h:184
int FBWriteFileBufHandle(int iHandle, const file_help_buf_t *pFB)
Write the file_help_buf_t object&#39;s text data to a file using an open file handle. ...
Definition: file_help.c:303
struct __file_help_buf__ * pPrev
pointer to &#39;previous&#39; item in linked list (NULL for owner object)
Definition: file_help.h:164
file_help_buf_t * FBGetFileBuf(const char *szFileName)
Construct a file_help_buf_t from a file.
Definition: file_help.c:106
void FBInsertLineIntoFileBuf(file_help_buf_t **ppBuf, long lLineNum, const char *szLine)
Insert a line of text into a file_help_buf_t object at a specific line index.
Definition: file_help.c:461
void * WBAllocDirectoryList(const char *szDirSpec)
Allocate a &#39;Directory List&#39; object for a specified directory spec.
Definition: file_help.c:1187
char ** ppLineBuf
array of pointers to beginning of each line (WBAlloc&#39;d TODO: make it part of &#39;cData&#39;?)
Definition: file_help.h:171
unsigned long long WBGetFileModDateTime(const char *szFileName)
Obtain the &#39;time_t&#39; value for a file&#39;s modification date/time (unix time, seconds since the epoch) ...
Definition: file_help.c:1609
int WBWriteFileFromBuffer(const char *szFileName, const char *pBuf, size_t cbBuf)
read a file&#39;s contents into a buffer, returning the length of the buffer
Definition: file_help.c:653
void FBDestroyFileBuf(file_help_buf_t *pFB)
Destroy a file_help_buf_t object.
Definition: file_help.c:186
struct __file_help_buf__ file_help_buf_t
basic &#39;buffered I/O&#39; object structure for &#39;FileBuf&#39; APIs
void FBDeleteLineFromFileBuf(file_help_buf_t *pBuf, long lLineNum)
Delete a line of text from a file_help_buf_t object at a specific line index.
Definition: file_help.c:525
long lLineCount
number of lines in &#39;cData&#39; when ppLineBuf not NULL
Definition: file_help.h:168
int WBCheckFileModDateTime(const char *szFileName, unsigned long long tVal)
Compare a 64-bit unsigned integer value against a file&#39;s modification date/time (unix time...
Definition: file_help.c:1635
char cData[sizeof(char *)]
the data itself (aligned to size of a pointer)
Definition: file_help.h:172
long lBufferCount
number of bytes of valid data
Definition: file_help.h:167
int WBStat(const char *szFileName, unsigned long *pdwModeAttrReturn)
Obtain the &#39;stat&#39; flags for a file name, resolving links as needed.
Definition: file_help.c:1574
int WBGetDirectoryListFileStat(const void *pDirectoryList, const char *szFileName, unsigned long *pdwModeAttrReturn)
Obtain the &#39;stat&#39; flags for a file name, resolving links as needed, with respect to a &#39;Directory List...
Definition: file_help.c:1589
size_t WBReadFileIntoBuffer(const char *szFileName, char **ppBuf)
read a file&#39;s contents into a buffer, returning the length of the buffer
Definition: file_help.c:572
struct __file_help_buf__ * pNext
pointer to &#39;next&#39; item in linked list (NULL for last object)
Definition: file_help.h:165
int WBIsDirectory(const char *szName)
Return whether a file is a directory or a symlink to a directory.
Definition: file_help.c:776
int FBParseFileBuf(file_help_buf_t *pFB)
Parse or Re-Parse the data for a file_help_buf_t object.
Definition: file_help.c:209
void FBInsertIntoFileBuf(file_help_buf_t **ppBuf, long cbOffset, const void *pData, long cbData)
Insert text into a file_help_buf_t object at a specific byte offset.
Definition: file_help.c:406
int WBNextDirectoryEntry(void *pDirectoryList, char *szNameReturn, int cbNameReturn, unsigned long *pdwModeAttrReturn)
Obtain information about the next entry in a &#39;Directory List&#39;.
Definition: file_help.c:1390
char * WBGetDirectoryListFileFullPath(const void *pDirectoryList, const char *szFileName)
Construct a fully qualified canonical path from a &#39;Directory List&#39; object and a file name...
Definition: file_help.c:1491
int FBWriteFileBuf(const char *szFileName, const file_help_buf_t *pFB)
Write the file_help_buf_t object&#39;s text data to a file using a filename.
Definition: file_help.c:281
char * WBGetDirectoryListSymLinkTarget(const void *pDirectoryList, const char *szFileName)
Obtain the target of a symbolic link file name with respect to a &#39;Directory List&#39; object...
Definition: file_help.c:1557
int WBReplicateFilePermissions(const char *szProto, const char *szTarget)
replicate permissions on a target file based on another file&#39;s permissions
Definition: file_help.c:713
void FBReplaceLineInFileBuf(file_help_buf_t **ppBuf, long lLineNum, const char *szLine)
Insert a line of text into a file_help_buf_t object at a specific line index.
Definition: file_help.c:561
static __inline__ int FBIsFileBufDirty(const file_help_buf_t *pBuf)
Inline function, returns TRUE if file_help_buf_t is &#39;dirty&#39;.
Definition: file_help.h:210
static __inline__ int FBWriteFileFromBuffer(const char *szFileName, const char *pBuf, unsigned int cbBuf)
Write a file from a regular buffer using a file name.
Definition: file_help.h:423
char * WBGetCanonicalPath(const char *szFileName)
Return the canonical path for a file name (similar to POSIX &#39;realpath()&#39; funtion) ...
Definition: file_help.c:803
char * WBGetCurrentDirectory(void)
Return allocated string containing the current working directory.
Definition: file_help.c:746
file_help_buf_t * FBGetFileBufFromBuffer(const char *pBuf, long cbBuf)
Construct a file_help_buf_t from a buffer.
Definition: file_help.c:159
char * WBGetSymLinkTarget(const char *szFileName)
Obtain the target of a symbolic link.
Definition: file_help.c:1538
void WBDestroyDirectoryList(void *pDirectoryList)
Destroy a &#39;Directory List&#39; object allocated by WBAllocDirectoryList()
Definition: file_help.c:1362
file_help_buf_t * FBGetFileBufViaHandle(int iHandle)
Construct a file_help_buf_t from a file handle.
Definition: file_help.c:123
void FBDeleteFromFileBuf(file_help_buf_t *pBuf, long cbOffset, long cbDelFrom)
Delete text from a file_help_buf_t object at a specific byte offset.
Definition: file_help.c:434
long lLineBufSize
size of memory block pointed to by &#39;ppLineBuf&#39;
Definition: file_help.h:169
long lBufferSize
size of entire buffer
Definition: file_help.h:166