Differential D52828 Diff 163554 lib/libc/gen/fts.3

Changeset View

Standalone View

lib/libc/gen/fts.3

	Show All 19 Lines
	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL			.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS			.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.Dd June 30, 2025			.Dd October 1, 2025
	.Dt FTS 3			.Dt FTS 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm fts			.Nm fts
	.Nd traverse a file hierarchy			.Nd traverse a file hierarchy
	.Sh LIBRARY			.Sh LIBRARY
	.Lb libc			.Lb libc
	.Sh SYNOPSIS			.Sh SYNOPSIS
	▲ Show 20 Lines • Show All 334 Lines • ▼ Show 20 Lines
	field.			field.
	Any such modifications should be undone before further calls to			Any such modifications should be undone before further calls to
	.Fn fts_read			.Fn fts_read
	are attempted.			are attempted.
	The			The
	.Fa fts_name			.Fa fts_name
	field is always			field is always
	.Dv NUL Ns -terminated .			.Dv NUL Ns -terminated .
	.Sh FTS_OPEN			.Ss Thread Safety
	The			The
				.Nm
				functions can safely be used in multi-threaded programs provided no
				two threads access the same
				.Vt FTS
				or
				.Vt FTSENT
				structure simultaneously.
				However, unless the
				.Dv FTS_NOCHDIR
				flag was passed to
	.Fn fts_open			.Fn fts_open
				or
				.Fn fts_open_b ,
				calls to
				.Fn fts_read
				and
				.Fn fts_children
				may change the current working directory, which will affect all
				threads.
				Conversely, changing the current working directory either during or
				between calls to
				.Fn fts_read
				or
				.Fn fts_children
				(even in a single-thread program) may cause
				.Nm
				to malfunction unless the
				.Dv FTS_NOCHDIR
				flag was passed to
				.Fn fts_open
				or
				.Fn fts_open_b
				and all paths in
				.Va path_argv
				were absolute.
				.Ss Fn fts_open
				The
				.Fn fts_open
	function takes a pointer to an array of character pointers naming one			function takes a pointer to an array of character pointers naming one
	or more paths which make up a logical file hierarchy to be traversed.			or more paths which make up a logical file hierarchy to be traversed.
	The array must be terminated by a			The array must be terminated by a
	.Dv NULL			.Dv NULL
	pointer.			pointer.
	.Pp			.Pp
	There are			There are
	a number of options, at least one of which (either			a number of options, at least one of which (either
	▲ Show 20 Lines • Show All 150 Lines • ▼ Show 20 Lines
	If the			If the
	.Fn compar			.Fn compar
	argument is			argument is
	.Dv NULL ,			.Dv NULL ,
	the directory traversal order is in the order listed in			the directory traversal order is in the order listed in
	.Fa path_argv			.Fa path_argv
	for the root paths, and in the order listed in the directory for			for the root paths, and in the order listed in the directory for
	everything else.			everything else.
	.Sh FTS_OPEN_B			.Ss Fn fts_open_b
	The			The
	.Fn fts_open_b			.Fn fts_open_b
	function is identical to			function is identical to
	.Fn fts_open			.Fn fts_open
	except that it takes a block pointer instead of a function pointer.			except that it takes a block pointer instead of a function pointer.
	The block is copied before			The block is copied before
	.Fn fts_open_b			.Fn fts_open_b
	returns, so the original can safely go out of scope or be released.			returns, so the original can safely go out of scope or be released.
	.Sh FTS_READ			.Ss Fn fts_read
	The			The
	.Fn fts_read			.Fn fts_read
	function returns a pointer to an			function returns a pointer to an
	.Vt FTSENT			.Vt FTSENT
	structure describing a file in			structure describing a file in
	the hierarchy.			the hierarchy.
	Directories (that are readable and do not cause cycles) are visited at			Directories (that are readable and do not cause cycles) are visited at
	least twice, once in pre-order and once in post-order.			least twice, once in pre-order and once in post-order.
	Show All 34 Lines
	on the same file hierarchy stream unless they represent a file of type			on the same file hierarchy stream unless they represent a file of type
	directory, in which case they will not be overwritten until after a call to			directory, in which case they will not be overwritten until after a call to
	.Fn fts_read			.Fn fts_read
	after the			after the
	.Vt FTSENT			.Vt FTSENT
	structure has been returned by the function			structure has been returned by the function
	.Fn fts_read			.Fn fts_read
	in post-order.			in post-order.
	.Sh FTS_CHILDREN			.Ss Fn fts_children
	The			The
	.Fn fts_children			.Fn fts_children
	function returns a pointer to an			function returns a pointer to an
	.Vt FTSENT			.Vt FTSENT
	structure describing the first entry in a NULL-terminated linked list of			structure describing the first entry in a NULL-terminated linked list of
	the files in the directory represented by the			the files in the directory represented by the
	.Vt FTSENT			.Vt FTSENT
	structure most recently returned by			structure most recently returned by
	▲ Show 20 Lines • Show All 57 Lines • ▼ Show 20 Lines
	Only the names of the files are needed.			Only the names of the files are needed.
	The contents of all the fields in the returned linked list of structures			The contents of all the fields in the returned linked list of structures
	are undefined with the exception of the			are undefined with the exception of the
	.Fa fts_name			.Fa fts_name
	and			and
	.Fa fts_namelen			.Fa fts_namelen
	fields.			fields.
	.El			.El
	.Sh FTS_SET			.Ss Fn fts_set
	The function			The function
	.Fn fts_set			.Fn fts_set
	allows the user application to determine further processing for the			allows the user application to determine further processing for the
	file			file
	.Fa f			.Fa f
	of the stream			of the stream
	.Fa ftsp .			.Fa ftsp .
	The			The
	▲ Show 20 Lines • Show All 53 Lines • ▼ Show 20 Lines
	is done.			is done.
	.It Dv FTS_SKIP			.It Dv FTS_SKIP
	No descendants of this file are visited.			No descendants of this file are visited.
	The file may be one of those most recently returned by either			The file may be one of those most recently returned by either
	.Fn fts_children			.Fn fts_children
	or			or
	.Fn fts_read .			.Fn fts_read .
	.El			.El
	.Sh FTS_CLOSE			.Ss Fn fts_close
	The			The
	.Fn fts_close			.Fn fts_close
	function closes a file hierarchy stream			function closes a file hierarchy stream
	.Fa ftsp			.Fa ftsp
	and restores the current directory to the directory from which			and restores the current directory to the directory from which
	.Fn fts_open			.Fn fts_open
	or			or
	.Fn fts_open_b			.Fn fts_open_b
	▲ Show 20 Lines • Show All 98 Lines • Show Last 20 Lines