Native file types and functionality. More...

Collaboration diagram for org.jau.fs.FileUtil:

Classes
interface	PathVisitor
	Path visitor for `FileUtil#visit(FileStats, TraverseOptions, PathVisitor)`. More...

Static Public Member Functions
static native String	get_cwd ()
	Return the current working directory or empty on failure.

static native String	dirname (final String path)
	Return stripped last component from given path separated by `/`, excluding the trailing separator `/`.

static native String	basename (final String path)
	Return stripped leading directory components from given path separated by `/`.

static native String	to_named_fd (final int fd)
	Returns platform dependent named file descriptor of given file descriptor, if supported.

static native int	from_named_fd (final String named_fd)
	Returns the file descriptor from the given named file descriptor.

static native int	from_java_fd (final java.io.FileDescriptor jfd)
	Returns the file descriptor from the given FileDescriptor instance.

static boolean	mkdir (final String path, final FMode mode)
	Create directory.

static boolean	mkdir (final String path)
	See `mkdir(String, FMode)` using `FMode#def_dir`.

static boolean	touch (final String path, final Instant atime, final Instant mtime, final FMode mode)
	Touch the file with given atime and mtime and create file if not existing yet.

static boolean	touch (final String path, final FMode mode)
	Touch the file with current time and create file if not existing yet.

static native List< DirItem >	get_dir_content (final String path)
	Returns a list of directory elements excluding `.`

static boolean	visit (final String path, final TraverseOptions topts, final PathVisitor visitor)
	Visit element(s) of a given path, see traverse_options for detailed settings.

static boolean	visit (final FileStats item_stats, final TraverseOptions topts, final PathVisitor visitor)
	Visit element(s) of a given path, see traverse_options for detailed settings.

static boolean	remove (final String path, final TraverseOptions topts)
	Remove the given path.

static native boolean	compare (final String source1, final String source2, final boolean verbose)
	Compare the bytes of both files, denoted by source1 and source2.

static boolean	copy (final String source_path, final String dest_path, final CopyOptions copts)
	Copy the given source_path to dest_path using copy_options.

static native boolean	rename (final String oldpath, final String newpath)
	Rename oldpath to newpath using POSIX `rename()`, with the following combinations.

static native void	sync ()
	Synchronizes filesystems, i.e.

static long	mount_image (final String image_path, final String target, final String fs_type, final MountFlags flags, final String fs_options)
	Attach the filesystem image named in `image_path` to `target` using an intermediate platform specific filesystem image loop-device.

static long	mount (final String source, final String target, final String fs_type, final MountFlags flags, final String fs_options)
	Attach the filesystem named in `source` to `target` using the given filesystem source directly.

static boolean	umount (final long context, final UnmountFlags flags)
	Detach the given mount_ctx `context`

static boolean	umount (final String target, final UnmountFlags flags)
	Detach the topmost filesystem mounted on `target` optionally using given `umountflags` options if supported.

Static Public Attributes
static final long	UTIME_NOW = ((1l << 30) - 1l)

Detailed Description

Native file types and functionality.

Definition at line 33 of file FileUtil.java.

Member Function Documentation

◆ basename()

static native String org.jau.fs.FileUtil.basename ( final String path )

static

Return stripped leading directory components from given path separated by /.

If only the root path / is given, return /.

Parameters

path	given path

Returns: last non-slash component or .

Here is the caller graph for this function:

◆ compare()

static native boolean org.jau.fs.FileUtil.compare	(	final String	source1,
		final String	source2,
		final boolean	verbose )

static

Compare the bytes of both files, denoted by source1 and source2.

Parameters

source1	first source file to compare
source2	second source file to compare
verbose	defaults to false

Returns: true if both elements are files and their bytes are equal, otherwise false.

Here is the caller graph for this function:

◆ copy()

static boolean org.jau.fs.FileUtil.copy	(	final String	source_path,
		final String	dest_path,
		final CopyOptions	copts )

static

Copy the given source_path to dest_path using copy_options.

The behavior is similar like POSIX cp commandline tooling.

The following behavior is being followed regarding dest_path:

If source_path is a directory and CopyOptions::recursive set
- If dest_path doesn't exist, source_path dir content is copied into the newly created dest_path.
- If dest_path exists as a directory, source_path dir will be copied below the dest_path directory if CopyOptions::into_existing_dir is not set. Otherwise its content is copied into the existing dest_path.
- Everything else is considered an error
If source_path is a file
- If dest_path doesn't exist, source_path file is copied to dest_path as a file.
- If dest_path exists as a directory, source_path file will be copied below the dest_path directory.
- If dest_path exists as a file, CopyOptions::overwrite must be set to have it overwritten by the source_path file
- Everything else is considered an error

Implementation either uses ::sendfile() if running under GNU/Linux, otherwise POSIX ::read() and ::write().

Implementation is most data-race-free (DRF), utilizes following safeguards on recursive directory copy

utilizing parent directory file descriptor and openat() operations against concurrent mutation
for each entered directory
- new destination directory is create with '.<random_number>' and user-rwx permissions only
- its file descriptor is being opened
- its user-read permission is dropped, remains user-wx permissions only
- its renamed to destination path
- all copy operations are performed inside
- at exit, its permissions are restored, etc.

See copy_options for details.

Parameters

source_path
dest_path
copts

Returns: true if successful, otherwise false

Definition at line 356 of file FileUtil.java.

Here is the caller graph for this function:

◆ dirname()

static native String org.jau.fs.FileUtil.dirname ( final String path )

static

Return stripped last component from given path separated by /, excluding the trailing separator /.

If no directory separator / is contained, return ..

If only the root path / is given, return /.

Parameters

path	given path

Returns: leading directory name w/o slash or .

Here is the caller graph for this function:

◆ from_java_fd()

static native int org.jau.fs.FileUtil.from_java_fd ( final java.io.FileDescriptor jfd )

static

Returns the file descriptor from the given FileDescriptor instance.

Parameters

jfd	the FileDescriptor instance

Returns: file descriptor or -1 if invalid or not supported by OS.

See also: FileStats#has_fd()

◆ from_named_fd()

static native int org.jau.fs.FileUtil.from_named_fd ( final String named_fd )

static

Returns the file descriptor from the given named file descriptor.

Detected named file descriptors are (d stands for integer)

/dev/fd/d (GNU/Linux, FreeBSD, ..)
/proc/self/fd/d (GNU/Linux)

Parameters

named_fd the named file descriptor

Returns: file descriptor or -1 if invalid or not supported by OS.

See also: to_named_fd(); FileStats#has_fd()

◆ get_cwd()

static native String org.jau.fs.FileUtil.get_cwd ( )

static

Return the current working directory or empty on failure.

Here is the caller graph for this function:

◆ get_dir_content()

static native List< DirItem > org.jau.fs.FileUtil.get_dir_content ( final String path )

static

Returns a list of directory elements excluding .

and .. for the given path, non recursive.

Parameters

path	path to directory

Returns: list of DirItem if given path exists, is directory and is readable, otherwise null

Here is the caller graph for this function:

◆ mkdir() [1/2]

static boolean org.jau.fs.FileUtil.mkdir ( final String path )

static

See mkdir(String, FMode) using FMode#def_dir.

Definition at line 118 of file FileUtil.java.

◆ mkdir() [2/2]

static boolean org.jau.fs.FileUtil.mkdir	(	final String	path,
		final FMode	mode )

static

Create directory.

Parameters

path	full path to new directory
mode	fmode_t POSIX protection bits used, defaults to `FMode#def_dir`
verbose	defaults to false

Returns: true if successful, otherwise false

Definition at line 110 of file FileUtil.java.

Here is the caller graph for this function:

◆ mount()

static long org.jau.fs.FileUtil.mount	(	final String	source,
		final String	target,
		final String	fs_type,
		final MountFlags	flags,
		final String	fs_options )

static

Attach the filesystem named in source to target using the given filesystem source directly.

This method either requires root permissions
or the following capabilities: cap_sys_admin,cap_setuid, cap_setgid.

Parameters

source	filesystem path for device, directory, file or dummy-string which shall be attached
target	directory where `source` filesystem shall be attached to
fs_type	type of filesystem, e.g. `squashfs`, `tmpfs`, `iso9660`, etc.
flags	mount flags, e.g. `MS_LAZYTIME \| MS_NOATIME \| MS_RDONLY` for a read-only lazy-time and no-atime filesystem.
fs_options	comma separated options for the filesystem `fs_type`, see mount(8) for available options for the used filesystem.

Returns: mount_ctx structure containing mounted status etc

See also: mount_image(); umount()

Definition at line 428 of file FileUtil.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mount_image()

static long org.jau.fs.FileUtil.mount_image	(	final String	image_path,
		final String	target,
		final String	fs_type,
		final MountFlags	flags,
		final String	fs_options )

static

Attach the filesystem image named in image_path to target using an intermediate platform specific filesystem image loop-device.

This method either requires root permissions
or the following capabilities: cap_sys_admin,cap_setuid, cap_setgid.

Unmounting shall be done via umount() with mount_ctx argument to ensure all intermediate resources are released.

Parameters

image_path	path of image source file
target	directory where `image_path` filesystem shall be attached to
fs_type	type of filesystem, e.g. `squashfs`, `tmpfs`, `iso9660`, etc.
flags	filesystem agnostic mount flags, see mountflags_linux.
fs_options	comma separated options for the filesystem `fs_type`, see mount(8) for available options for the used filesystem.

Returns: mount_ctx structure containing mounted status etc

See also: mount(); umount()

Definition at line 404 of file FileUtil.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ remove()

static boolean org.jau.fs.FileUtil.remove	(	final String	path,
		final TraverseOptions	topts )

static

Remove the given path.

If path represents a director, recursive must be set to true.

The given traverse_options options are handled as follows:

traverse_options::parent_dir_last will be added by implementation to operate correct
traverse_options::recursive shall shall be set by caller to remove directories
traverse_options::follow_symlinks shall be set by caller to remove symbolic linked directories recursively, which is kind of dangerous. If not set, only the symbolic link will be removed (default)

Implementation is most data-race-free (DRF), utilizes following safeguards

utilizing parent directory file descriptor and openat() and unlinkat() operations against concurrent mutation

Parameters

path	path to remove
topts	given traverse_options for this operation, defaults to traverse_options::none

Returns: true only if the file or the directory with content has been deleted, otherwise false

Definition at line 304 of file FileUtil.java.

Here is the caller graph for this function:

◆ rename()

static native boolean org.jau.fs.FileUtil.rename	(	final String	oldpath,
		final String	newpath )

static

Rename oldpath to newpath using POSIX rename(), with the following combinations.

oldpath and newpath refer to the same file, a successful no-operation.
oldpath file
- newpath not-existing file
- newpath existing file to be atomically replaced
oldpath directory
- newpath not-existing directory
- newpath existing empty directory
oldpath symlink will be renamed
newpath symlink will be overwritten

Parameters

oldpath	previous path
newpath	new path

Returns: true only if the rename operation was successful, otherwise false

◆ sync()

static native void org.jau.fs.FileUtil.sync ( )

static

Synchronizes filesystems, i.e.

all pending modifications to filesystem metadata and cached file data will be written to the underlying filesystems.

◆ to_named_fd()

static native String org.jau.fs.FileUtil.to_named_fd ( final int fd )

static

Returns platform dependent named file descriptor of given file descriptor, if supported.

Implementation returns (d stands for integer):

/dev/fd/d (GNU/Linux, FreeBSD, ..)

Currently implementation always returns above pattern, not handling the target OS differences.

Parameters

fd	file descriptor.

Returns: the named file descriptor or null if fd < 0 or not supported by OS.

See also: from_named_fd(); FileStats.has_fd()

◆ touch() [1/2]

static boolean org.jau.fs.FileUtil.touch	(	final String	path,
		final FMode	mode )

static

Touch the file with current time and create file if not existing yet.

Parameters

path	full path to file
mode	fmode_t POSIX protection bits used, defaults to `FMode#def_file`
verbose	defaults to false

Returns: true if successful, otherwise false

Definition at line 152 of file FileUtil.java.

◆ touch() [2/2]

static boolean org.jau.fs.FileUtil.touch	(	final String	path,
		final Instant	atime,
		final Instant	mtime,
		final FMode	mode )

static

Touch the file with given atime and mtime and create file if not existing yet.

Parameters

path	full path to file
atime	new access time
mtime	new modification time
mode	fmode_t POSIX protection bits used, defaults to `FMode#def_file`
verbose	defaults to false

Returns: true if successful, otherwise false

Definition at line 131 of file FileUtil.java.

Here is the caller graph for this function:

◆ umount() [1/2]

static boolean org.jau.fs.FileUtil.umount	(	final long	context,
		final UnmountFlags	flags )

static

Detach the given mount_ctx context

This method either requires root permissions
or the following capabilities: cap_sys_admin,cap_setuid, cap_setgid.

Parameters

context	native mount context, previously attached via mount_image() or mount()
flags	optional umount options, if supported by the system

Returns: true if successful, otherwise false

See also: mount(); mount_image()

Definition at line 448 of file FileUtil.java.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ umount() [2/2]

static boolean org.jau.fs.FileUtil.umount	(	final String	target,
		final UnmountFlags	flags )

static

Detach the topmost filesystem mounted on target optionally using given umountflags options if supported.

This method either requires root permissions
or the following capabilities: cap_sys_admin,cap_setuid, cap_setgid.

Parameters

target	directory of previously attached filesystem
umountflags	optional umount options, if supported by the system

Returns: true if successful, otherwise false

See also: mount(); mount_image()

Definition at line 467 of file FileUtil.java.

Here is the call graph for this function:

◆ visit() [1/2]

static boolean org.jau.fs.FileUtil.visit	(	final FileStats	item_stats,
		final TraverseOptions	topts,
		final PathVisitor	visitor )

static

Visit element(s) of a given path, see traverse_options for detailed settings.

All elements of type fmode_t::file, fmode_t::dir and fmode_t::no_access or fmode_t::not_existing will be visited by the given path_visitor visitor.

Depth passed to path_visitor is the recursive directory depth and starts with 1 for the initial directory.

path_visitor returning false stops traversal in general but TraverseOptions.Bit#dir_check_entry will only skip traversing the denied directory.

Parameters

item_stats	pre-fetched file_stats for a given dir_item, used for efficiency
topts	given traverse_options for this operation
visitor	path_visitor function `bool visitor(const file_stats& item_stats, size_t depth)`.

Returns: true if successful including no path_visitor stopped traversal by returning false excluding TraverseOptions.Bit#dir_check_entry.

Definition at line 222 of file FileUtil.java.

◆ visit() [2/2]

static boolean org.jau.fs.FileUtil.visit	(	final String	path,
		final TraverseOptions	topts,
		final PathVisitor	visitor )

static

Visit element(s) of a given path, see traverse_options for detailed settings.

All elements of type fmode_t::file, fmode_t::dir and fmode_t::no_access or fmode_t::not_existing will be visited by the given path_visitor visitor.

Depth passed to path_visitor is the recursive directory depth and starts with 1 for the initial directory.

path_visitor returning false stops traversal in general but TraverseOptions.Bit#dir_check_entry will only skip traversing the denied directory.

Parameters

path	the starting path
topts	given traverse_options for this operation
visitor	path_visitor function `bool visitor(const file_stats& item_stats, size_t depth)`.

Returns: true if successful including no path_visitor stopped traversal by returning false excluding TraverseOptions.Bit#dir_check_entry.

Definition at line 201 of file FileUtil.java.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ UTIME_NOW

final long org.jau.fs.FileUtil.UTIME_NOW = ((1l << 30) - 1l)

static

Definition at line 143 of file FileUtil.java.

The documentation for this class was generated from the following file:

java_jni/org/jau/fs/FileUtil.java

Classes

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

◆ basename()

◆ compare()

◆ copy()

◆ dirname()

◆ from_java_fd()

◆ from_named_fd()

◆ get_cwd()

◆ get_dir_content()

◆ mkdir() [1/2]

◆ mkdir() [2/2]

◆ mount()

◆ mount_image()

◆ remove()

◆ rename()

◆ sync()

◆ to_named_fd()

◆ touch() [1/2]

◆ touch() [2/2]

◆ umount() [1/2]

◆ umount() [2/2]

◆ visit() [1/2]

◆ visit() [2/2]

Member Data Documentation

◆ UTIME_NOW