/**************************************************************************** * include/ftw.h * * SPDX-License-Identifier: Apache-2.0 * * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. The * ASF licenses this file to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance with the * License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations * under the License. * ****************************************************************************/ #ifndef __INCLUDE_FTW_H #define __INCLUDE_FTW_H /**************************************************************************** * Included Files ****************************************************************************/ /* The header defines the stat structure and the symbolic names for * st_mode and the file type test macros as described in sys/stat.h. * * Inclusion of the header may also make visible all symbols from * sys/stat.h. */ #include /**************************************************************************** * Pre-processor Definitions ****************************************************************************/ /* Macros for use as values of the third argument to the application-supplied * function that is passed as the second argument to ftw() and nftw(): */ #define FTW_F 0 /* File */ #define FTW_D 1 /* Directory */ #define FTW_DNR 2 /* Directory without read permission */ #define FTW_DP 3 /* Directory with subdirectories visited */ #define FTW_NS 4 /* Unknown type; stat() failed */ #define FTW_SL 5 /* Symbolic link */ #define FTW_SLN 6 /* Symbolic link that names a nonexistent file */ /* Macros for use as values of the fourth argument to nftw() */ #define FTW_PHYS 1 /* Physical walk, does not follow symbolic links. * Otherwise, nftw() follows links but does not walk * down any path that crosses itself. */ #define FTW_MOUNT 2 /* The walk does not cross a mount point. */ #define FTW_DEPTH 4 /* All subdirectories are visited before the directory * itself. */ #ifndef CONFIG_DISABLE_ENVIRON #define FTW_CHDIR 8 /* The walk changes to each directory before reading * it. */ #endif #if defined(CONFIG_FS_LARGEFILE) # define ftw64 ftw # define nftw64 nftw #endif /**************************************************************************** * Public Types ****************************************************************************/ /* The fourth argument of the ftw/nftw callback is a pointer to an FTW * structure. The value of base is the offset of the object's filename in * the pathname passed as the first argument to the callback. The value of * level indicates depth relative to the root of the walk, where the root * level is 0. */ struct FTW { int base; /* Offset of object's filename in the pathname */ int level; /* Depth relative to the root of the walk */ }; /* This is the type of the ftw callback */ typedef int (*ftw_cb_t)(FAR const char *path, FAR const struct stat *buf, int info); /* This is the type of the nftw callback */ typedef int (*nftw_cb_t)(FAR const char *path, FAR const struct stat *buf, int info, FAR struct FTW *pftw); /**************************************************************************** * Public Function Prototypes ****************************************************************************/ #ifdef __cplusplus #define EXTERN extern "C" extern "C" { #else #define EXTERN extern #endif /**************************************************************************** * Name: ftw * * Description: * The ftw() function will recursively descend the directory hierarchy * rooted in 'path'. For each object in the hierarchy, ftw() will call * the function pointed to by 'fn', passing it a pointer to a null- * terminated character string containing the name of the object, a * pointer to a stat structure containing information about the object, * and an integer that characterizes object. * * The ftw() function will visit a directory before visiting any of its * descendants. * * The ftw() function will use at most one file descriptor for each level * in the tree. * * The tree traversal will continue until either the tree is exhausted, an * invocation of 'fn' returns a non-zero value, or some error, other than * EACCES, is detected within ftw(). * * When ftw() returns it will close any directory streams and file * descriptors it uses not counting any opened by the application-supplied * 'fn' function. * * The results are unspecified if the application-supplied 'fn' function * does not preserve the current working directory. * * The ftw() function need not be reentrant. A function that is not * required to be reentrant is not required to be thread-safe. * * Input Parameters: * path - The 'root' of the directory hierarchy to descend * fn - The callback function to be invoked as each object in the * hierarchy is encountered. * fdlimit - The fdlimit argument specifies the maximum number of directory * streams or file descriptors or both available for use by ftw() * while traversing the tree.The maximum depth of the directories * to visit. The fdlimit argument should be in the range [1, * {OPEN_MAX}]. * * Returned Value: * If the tree is exhausted, ftw() will return 0. If the function pointed * to by fn returns a non-zero value, ftw() will stop its tree traversal * and return whatever value was returned by the function pointed to by * 'fn'. If ftw() detects an error, it will return -1 and set errno to * indicate the error. * * If ftw() encounters an error other than EACCES (see FTW_DNR and FTW_NS), * it will return -1 and set errno to indicate the error. The external * variable errno may contain any error value that is possible when a * directory is opened or when one of the stat functions is executed on a * directory or file. * ****************************************************************************/ int ftw(FAR const char *path, ftw_cb_t fn, int fdlimit); /**************************************************************************** * Name: nftw * * Description: * The nftw() function will recursively descend the directory hierarchy * rooted in 'path'. The nftw() function has a similar effect to ftw() * except that it takes an additional argument 'flags' * * Input Parameters: * * path - The 'root' of the directory hierarchy to descend * fn - The callback function to be invoked as each object in the * hierarchy is encountered. * fdlimit - The fdlimit argument specifies the maximum number of directory * streams or file descriptors or both available for use by * nftw() while traversing the tree.The maximum depth of the * directories to visit. The fdlimit argument should be in the * range [1, {OPEN_MAX}]. * flags - A bitwise-inclusive OR of zero or more of the following flags: * * FTW_CHDIR * If set, nftw() will change the current working directory to each * directory as it reports files in that directory. If clear, nftw() * will not change the current working directory. * FTW_DEPTH * If set, nftw() will report all files in a directory before * reporting the directory itself. If clear, nftw() will report any * directory before reporting the files in that directory. * FTW_MOUNT * If set, nftw() will only report files in the same file system as * path. If clear, nftw() will report all files encountered during * the walk. * FTW_PHYS * If set, nftw() will perform a physical walk and will not follow * symbolic links. * * Returned Value: * If the tree is exhausted, nftw() will return 0. If the function pointed * to by fn returns a non-zero value, nftw() will stop its tree traversal * and return whatever value was returned by the function pointed to by * 'fn'. If nftw() detects an error, it will return -1 and set errno to * indicate the error. * * If nftw() encounters an error other than EACCES (see FTW_DNR and * FTW_NS), it will return -1 and set errno to indicate the error. The * external variable errno may contain any error value that is possible * when a directory is opened or when one of the stat functions is * executed on a directory or file. * * ****************************************************************************/ int nftw(FAR const char *path, nftw_cb_t fn, int fdlimit, int flags); #undef EXTERN #ifdef __cplusplus } #endif #endif /* __INCLUDE_FTW_H */