Home Libraries Author Links

Recurs: Recurse a Directory Tree
[SysToMath Base C Library]

Collaboration diagram for Recurs: Recurse a Directory Tree:

Detailed Description

Recurse the directory tree spanned by a root directory or traverse a directory chain from a root directory to a given descendant directory.


Files

file  recurs.h
 Specification of data types and functions for recursing directory trees or traversing directory chains.

Defines

#define stmRecurs   stmRecurse
 Alternative name for stmRecurse().

Typedefs

typedef int StmRecursUsrFctType (const char *dirname, const char *entryname, const struct stat *direntry, int status, void *data, size_t len)
 User function type for the pusrfct arguments of stmRecurse() and stmTraverse().

Enumerations

enum  StmRecursFlags {
  StmRecursFollowLinks = 0x00000001,
  StmRecursDoNotRecurse = 0x00000002
}
 Constants used for the flags argunment of stmRecurse(). More...
enum  StmRecursStatus {
  StmRecursLeaf,
  StmRecursDbeg,
  StmRecursDend,
  StmRecursDns
}
 Constants used for the status argument of the user function referenced by the pusrfct parameter of stmRecurse() and stmTraverse(). More...

Functions

int stmRecurse (const char *root, StmRecursUsrFctType *pusrfct, void *data, size_t len, StmDword flags)
 Recurse the directory tree spanned by the directory root calling a user function for each file system element visited.
int stmTraverse (const char *root, const char *path, StmRecursUsrFctType *pusrfct, void *data, size_t len)
 Traverse the directory chain from the directory root to its descendant directory path.

Variables

StmBool stmRecursDebug
 Debug flag.


Define Documentation

#define stmRecurs   stmRecurse

Alternative name for stmRecurse().

Deprecated:
Only for backward compatibility.

Definition at line 99 of file recurs.h.


Typedef Documentation

typedef int StmRecursUsrFctType(const char *dirname, const char *entryname, const struct stat *direntry, int status, void *data, size_t len)

User function type for the pusrfct arguments of stmRecurse() and stmTraverse().

For the usage context and the required semantics of such a user function see stmRecurse() and stmTraverse.

Definition at line 142 of file recurs.h.


Enumeration Type Documentation

enum StmRecursFlags

Constants used for the flags argunment of stmRecurse().

They may be bitwise ored.

Enumerator:
StmRecursFollowLinks  Follow symbolic links.

StmRecursDoNotRecurse  No directory recursion.

Definition at line 106 of file recurs.h.

enum StmRecursStatus

Constants used for the status argument of the user function referenced by the pusrfct parameter of stmRecurse() and stmTraverse().

Enumerator:
StmRecursLeaf  Leaf: No directory.

StmRecursDbeg  Directory begin.

StmRecursDend  Directory end.

StmRecursDns  Directory not searchable.

Definition at line 116 of file recurs.h.


Function Documentation

int stmRecurse ( const char *  root,
StmRecursUsrFctType pusrfct,
void *  data,
size_t  len,
StmDword  flags 
)

Recurse the directory tree spanned by the directory root calling a user function for each file system element visited.

Parameters:
[in] root Root of the directory tree to recurse or the single file system element to handle.
[in] pusrfct Address of a user function of type StmRecursUsrFctType called for each file system element visited.
[in,out] data If not NULL, data buffer with input data ready to be modified thus yielding output data.
[in] len Byte size of the data buffer.
[in] flags Bitwise orable enumerators of the enumeration StmRecursFlags.
Effects:
The function performs a recursive walkthrough of the directory tree spanned by root, if root is a directory. If root is a symbolic link pointing to a directory, the tree spanned by that directory is handled. If root is a non-directory file system element, or is a symbolic link pointing to a non-directory file system element, that file system element is handled.
The parameter pusrfct references a user function
          int usrfct (const char *dirname, const char *entryname,
                      const struct stat *direntry, int status,
                      void *data, size_t len)
of type StmRecursUsrFctType. Depending on the file system element visited, it is called with a different value of parameter status as follows:
Meaning of the user function parameter status
status File system element visited
StmRecursLeaf The file system element visited is no directory.
StmRecursDbeg The file system element visited is a searchable directory just being entered. After this all file system elements of that directory are visited in turn.
StmRecursDend The file system element visited is a searchable directory just being left. That means the directory tree spanned by the directory has been handled.
StmRecursDns The file system element visited is a non-searchable directory. In this case the file system elements of that directory are not visited.
Depending on the value of status the user function is called for a file system element fsyselem visited with its first three parameters as follows:
Meaning of the user function parameters dirname, entryname and direntry dependent on the parameter status
status dirname entryname direntry
StmRecursLeaf Path of the parent directory of fsyselem Base name of fsyselem Points to struct stat of fsyselem
StmRecursDbeg Path of fsyselem Points to the data buffer of the parent directory of fsyselem Points to struct stat of fsyselem
StmRecursDend Path of fsyselem Points to the data buffer of the parent directory of fsyselem Points to struct stat of fsyselem
StmRecursDns Path of fsyselem Points to the data buffer of the parent directory of fsyselem Points to garbage
All user function calls have the two additional parameters data and len. By this, if the parameter data of stmRecures() is not NULL, for each directory file system element visited a user supplied and initialized data buffer of byte length defined by the parameter len of stmRecurse() is accessible. This way for instance global and/or directory specific data can be supplied or be achieved.
The data buffer supplied by the user through the parameter data of stmRecurse() corresponds to the parent directory of root. For each directory visited (also for root, if root is a directory) a temporary buffer of byte length len initialized with a copy of the data buffer of its parent directory is allocated. Depending on the value of its parameter status the user function shall perform the following actions:
Actions of the user function depending on its parameter status
status Possible user funcion actions
StmRecursLeaf The data buffer referenced by data can be modified subject to the information supplied by the other parameters.
StmRecursDbeg,
StmRecursDend,
StmRecursDns
The data buffer referenced by data can be modified subject to the information supplied by the other parameters. Moreover, by means of the parameter entryname also the data buffer of the parent directory of the directory visited is accessible.
Normally the user function shall return with 0, else with a non-zero value. In the non-zero case the recursive walkthrough is aborted. If the return value is negative this is regarded as an error code and stmRecurse() immediately returns with that error code. If that error code is -1 (EOF), the variable errno shall reflect the error's cause. If the return value of the user function is positive and its parameter status was StmRecursDbeg, only the recursive descent of the directory visited is omitted and stmRecurse() is continued.
If the parameter flags contains the StmRecursFollowLinks bit, the recursive walkthrough follows symbolic links, else not. If the parameter flags contains the StmRecursDoNotRecurse bit, the recursive descent into directories is suppressed.
Returns:
0 on success.

A negative value on error. If that return value is -1 (EOF), the variable errno reflects the error's cause.

See also:
stmTraverse().

int stmTraverse ( const char *  root,
const char *  path,
StmRecursUsrFctType pusrfct,
void *  data,
size_t  len 
)

Traverse the directory chain from the directory root to its descendant directory path.

Parameters:
[in] root Begin of the directory chain to be traversed.
[in] path NULL, the empty string, or descendant directory of root defining the end directory of the directory chain to be traversed.
[in] pusrfct Address of a user function of type StmRecursUsrFctType called for each directory of the chain.
[in,out] data If not NULL, data buffer with input data ready to be modified thus yielding output data.
[in] len Byte size of the data buffer.
Effects:
The function performs a traversal of the directory chain beginning with root, if root is a directory. If root is a symbolic link pointing to a directory, that directory is the begin of the chain. It is an error, if root is a non-directory file system element, or is a symbolic link pointing to a non-directory file system element. If path is NULL or the empty string, the directory chain only consits of the directory designated by root. Else the end of the directory chain to be traversed is defined by the parameter path which shall be a descendant directory of root and shall be supplied by the directory names or symbolic link names targetting directories forming the chain separated by path separator characters and optionally preceded by a path separator character.
The parameter pusrfct references a user function
          int usrfct (const char *dirname, const char *entryname,
                      const struct stat *direntry, int status,
                      void *data, size_t len)
of type StmRecursUsrFctType. Depending on the situation, it is called with a different value of parameter status as follows:
Meaning of the user function parameter status
status Situation on call
StmRecursDbeg The directory chain element is just being entered. After this the next directory chain element is visited, if existing.
StmRecursDend The directory chain element is just being left. That means all subsequent directory chain elements have been visited.
Depending on the value of status the user function is called for a directory chain element direlem with its first three parameters as follows:
Meaning of the user function parameters dirname, entryname and direntry dependent on the parameter status
status dirname entryname direntry
StmRecursDbeg,
StmRecursDend
Path of direlem Points to the data buffer of the parent directory of direlem Points to struct stat of direlem
All user function calls have the two additional parameters data and len. By this, if the parameter data of stmTraverse() is not NULL, for each directory chain element visited a user supplied and initialized data buffer of byte length defined by the parameter len of stmTraverse() is accessible. This way for instance global and/or directory specific data can be supplied or be achieved.
The data buffer supplied by the user through the parameter data of stmTraverse() corresponds to the parent directory of root. For each directory visited (also for root) a temporary buffer of byte length len initialized with a copy of the data buffer of its parent directory is allocated. Depending on the value of its parameter status the user function shall perform the following actions:
Actions of the user function depending on its parameter status
status Possible user funcion actions
StmRecursDbeg,
StmRecursDend
The data buffer referenced by data can be modified subject to the information supplied by the other parameters. Moreover, by means of the parameter entryname also the data buffer of the parent directory of the directory visited is accessible.
Normally the user function shall return with 0, else with a non-zero value. In the non-zero case the directory chain traversal is aborted. If the return value is negative this is regarded as an error code and stmTraverse() immediately returns with that error code. If that error code is -1 (EOF), the variable errno shall reflect the error's cause. If the return value of the user function is positive and its parameter status was StmRecursDbeg, only the traversal of the directory chain is aborted and stmTraverse() returns with 0.
Returns:
0 on success.

A negative value on error. If that return value is -1 (EOF), the variable errno reflects the error's cause.

See also:
stmRecurse().


Variable Documentation

StmBool stmRecursDebug

Debug flag.

If the flag stmRecursDebug is StmTrue, in case of an error in stmRecurse() or stmTraverse() an error message specifying the error location is printed on stderr. By default the flag stmRecursDebug is StmFalse.


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).