X11 Work Bench 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-2016 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 #ifdef __cplusplus
58 extern "C" {
59 #endif // __cplusplus
60 
61 
62 // use NAME_MAX to determine max buffer sizes for things that use a file name
63 // maximum path name limits are OS dependent.
64 
65 #ifdef WIN32
66 #ifndef NAME_MAX
67 #define NAME_MAX MAX_PATH
68 #endif // NAME_MAX
69 #else // !WIN32
70 // POSIX systems normally define NAME_MAX in limits.h (or something it includes)
71 #ifndef NAME_MAX
72 #ifdef MAXNAMLEN
73 #define NAME_MAX MAXNAMLEN /* BSD defines MAXNAMLEN */
74 #else
75 #define NAME_MAX 255 /* standard value for BSD and Linux */
76 #endif // MAXNAMLEN
77 #endif // NAME_MAX
78 #endif // WIN32, !WIN32
79 
80 
81 // sub-groups for documentation
82 
140 typedef struct __file_help_buf__
141 {
144  long lBufferSize;
146  long lLineCount;
148  int iFlags;
149  char **ppLineBuf;
150  char cData[sizeof(char *)];
152 
161 {
162  file_help_buf_dirty = 1,
163  file_help_buf_reserved01 = 2,
164  file_help_buf_reserved02 = 4,
165  file_help_buf_reserved03 = 8,
166  file_help_buf_reserved04 = 16,
167  file_help_buf_reserved05 = 32,
168  file_help_buf_reserved06 = 64,
169  file_help_buf_reserved07 = 128,
170  file_help_buf_reserved08 = 256,
171 
172  file_help_buf_last = 0x80000000L
173 };
174 
184 static __inline__ int FBIsFileBufDirty(const file_help_buf_t *pBuf)
185 {
186  return pBuf && (pBuf->iFlags & file_help_buf_dirty);
187 }
188 
200 file_help_buf_t *FBGetFileBufViaHandle(int iHandle);
201 
215 file_help_buf_t *FBGetFileBufFromBuffer(const char *pBuf, long cbBuf);
216 
228 file_help_buf_t *FBGetFileBuf(const char *szFileName);
229 
230 
240 void FBDestroyFileBuf(file_help_buf_t *pFB);
241 
242 
254 int FBParseFileBuf(file_help_buf_t *pFB);
255  // parses or re-parses buffer, populating ppLineBuf
256 
268 int FBWriteFileBuf(const char *szFileName, const file_help_buf_t *pFB);
269 
281 int FBWriteFileBufHandle(int iHandle, const file_help_buf_t *pFB);
282 
283 
297 void FBInsertIntoFileBuf(file_help_buf_t **ppBuf, long cbOffset, const void *pData, long cbData);
298 
310 void FBDeleteFromFileBuf(file_help_buf_t *pBuf, long cbOffset, long cbDelFrom);
311 
312 
327 void FBInsertLineIntoFileBuf(file_help_buf_t **ppBuf, long lLineNum, const char *szLine);
328 
329 
342 void FBDeleteLineFromFileBuf(file_help_buf_t *pBuf, long lLineNum);
343 
344 
360 void FBReplaceLineInFileBuf(file_help_buf_t **ppBuf, long lLineNum, const char *szLine);
361 
362 
371 static __inline__ int FBWriteFileFromBuffer(const char *szFileName, const char *pBuf, unsigned int cbBuf)
372 {
373 int iRval;
374 file_help_buf_t *pFB;
375 
376 
377  pFB = FBGetFileBufFromBuffer(pBuf, cbBuf);
378 
379  if(!pFB)
380  {
381 // WB_ERROR_PRINT("ERROR - %s - unable to create file buf\n", __FUNCTION__);
382  return -1;
383  }
384 
385  iRval = FBWriteFileBuf(szFileName, pFB);
386 
387  FBDestroyFileBuf(pFB);
388 
389 // if(iRval < 0)
390 // {
391 // WB_ERROR_PRINT("ERROR - %s - unable to create file \"%s\" from file buf\n", __FUNCTION__, szFileName);
392 // }
393 
394  return iRval;
395 }
396 
397 
398 
409 size_t WBReadFileIntoBuffer(const char *szFileName, char **ppBuf);
410 
422 int WBWriteFileFromBuffer(const char *szFileName, const char *pBuf, size_t cbBuf);
423 
424 
425 // SYSTEM INDEPENDENT FILE STATUS, LISTINGS, AND INFORMATION
426 
439 int WBReplicateFilePermissions(const char *szProto, const char *szTarget);
440 
449 char *WBGetCurrentDirectory(void);
450 
460 int WBIsDirectory(const char *szName);
461 
475 char *WBGetCanonicalPath(const char *szFileName);
476 
495 void *WBAllocDirectoryList(const char *szDirSpec);
496 
504 void WBDestroyDirectoryList(void *pDirectoryList);
505 
518 int WBNextDirectoryEntry(void *pDirectoryList, char *szNameReturn,
519  int cbNameReturn, unsigned long *pdwModeAttrReturn);
520 
532 char *WBGetDirectoryListFileFullPath(const void *pDirectoryList, const char *szFileName);
533 
545 char *WBGetSymLinkTarget(const char *szFileName);
546 
560 char *WBGetDirectoryListSymLinkTarget(const void *pDirectoryList, const char *szFileName);
561 
571 int WBStat(const char *szFileName, unsigned long *pdwModeAttrReturn);
572 
584 int WBGetDirectoryListFileStat(const void *pDirectoryList, const char *szFileName,
585  unsigned long *pdwModeAttrReturn);
586 
587 
588 #ifdef __cplusplus
589 };
590 #endif // __cplusplus
591 
592 
593 #endif // _FILE_HELP_H_INCLUDED_
594 
basic &#39;buffered I/O&#39; object structure for &#39;FileBuf&#39; APIs
Definition: file_help.h:140
int iFlags
various bit flags
Definition: file_help.h:148
__file_help_buf_flags__
bit flags for file_help_buf_t &#39;iFlags&#39; member
Definition: file_help.h:160
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:142
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:1191
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:149
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:657
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:146
char cData[sizeof(char *)]
the data itself (aligned to size of a pointer)
Definition: file_help.h:150
long lBufferCount
number of bytes of valid data
Definition: file_help.h:145
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:1578
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:1593
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:143
int WBIsDirectory(const char *szName)
Return whether a file is a directory or a symlink to a directory.
Definition: file_help.c:780
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:1394
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:1495
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:1561
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:717
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:184
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:371
char * WBGetCanonicalPath(const char *szFileName)
Return the canonical path for a file name (similar to POSIX &#39;realpath()&#39; funtion) ...
Definition: file_help.c:807
char * WBGetCurrentDirectory(void)
Return allocated string containing the current working directory.
Definition: file_help.c:750
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:1542
void WBDestroyDirectoryList(void *pDirectoryList)
Destroy a &#39;Directory List&#39; object allocated by WBAllocDirectoryList()
Definition: file_help.c:1366
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:147
long lBufferSize
size of entire buffer
Definition: file_help.h:144