kcopydir: Copying a directory structure¶
kcopydir |
Copy a directory structure |
SYNTAX
Make a copy of an entire directory structure. kcopydir is particularly useful for copying directories that contain Sculptor keyed files, which are copied safely even if other processes have them open for update during the copying process. The Sculptor File Manager program provides a front end for the kcopydir program.
Because kcopydir is designed to run as a background process, all messages are suppressed unless otherwise specified.
source_dir dest_dir |
The source and destination directories respectively. By default, kcopydir copies all files and all subdirectories from source_dir to dest_dir. If the path to dest_dir does not already exist, it is created. Existing files in dest_dir with the same name as files in source_dir are replaced. The owner, permissions and modification time of each destination file are set to the same values as the source file. |
The files in each directory are copied in name order except for Sculptor .k files, which are copied before other files and subdirectories that have the same base name.
Sculptor keyed files are recognised by the presence of a .k file and are locked while being copied. This prevents them being updated by another process during the copy. The lock is held while all files and subdirectories that have the same base name are copied.
For example, if a directory contains the files “stock.k, ”stock.d“, ”stock.k“, ”stock.f” and the subdirectory “stock.x”, a lock is held while all these files and the entire content of the subdirectory are copied.
If a file is already locked by another process, kcopydir waits for the lock to be released. The lock placed by kcopydir is a read lock. This allows other processes to read records providing they use commands that don’t lock the records (readu, nextu, etc). A program that attempts to read and lock a record will wait or get an riu trap.
Although this mechanism preserves the integrity of each Sculptor keyed file that is copied, it does not safeguard application dependent relationships between files. The best way to achieve this is to run kcopydir from a program that places read locks on all related files for the duration of the copy.
EXAMPLE
!ofile FILE1 "file1" read
!ofile FILE2 "file2" read
readlock FILE1
readlock FILE1
execu "kcopydir ..."
unlock FILE1
unlock FILE2
Care should be taken to lock files in an order that will not cause a deadlock. If there is any possibility of a deadlock occurring, the locking commands should be placed in a retry loop, each file lock command should have an riu trap and if a trap is triggered, all acquired locks should be released before retrying.
Options
-a |
Abort on error. The default is to continue, except when the error is so serious that continuing is unlikely to be possible. |
-m |
Don’t preserve file modification time. |
-n |
Copy new files only. This flag can be combined with -u to copy new and updated files only. |
-o |
Don’t preserve file owner. This flag is ignored on MS-DOS and Windows. |
-p |
Don’t preserve file permission flags. |
-s |
Ignore subdirectories. Copy files in source_dir only. |
-u |
Copy updated files only. This does not work reliably on MS-DOS and Windows, because the operating system does not reset the file modification time until the application that has updated it either closes or flushes the file. This may not matter in the case of a backup run once a day on files that are opened and closed many times. However, it is important to be aware that a file that is open and has been modified may not be copied. |
-v |
Verbose. Print all messages to standard output. |
-e errfile |
Print error messages to errfile, creating the file empty. |
-E errfile |
Print error messages to errfile, appending to the file if it already exists. |
-l logfile |
Print all messages to logfile, creating the file empty. |
-L logfile |
Print all messages to logfile, appending to the file if it already exists. |
-x exnfile |
Exclude any file whose name is wholly or partly contained in the text file exnfile. A file will be excluded if any part of its name, ignoring the directory component, contains the text from a line in exnfile. For example, if exnfile contains the lines “junk” and “temp”, then all files that contain “junk” or “temp” in any part of their name are excluded. On MS-DOS and Windows, the comparison is case insensitive. |
-X exdfile |
Exclude any directory whose name is wholly or partly contained in the text file exdfile. A directory will be excluded if any part of its name contains the text from a line in exdfile. For example, if exdfile contains the lines “old” and “mydir/test” then all directories that contain “old” or “mydir/test” in any part of their path are excluded. The forward and backward slash characters (/ and \) are considered to be identical. On MS-DOS and Windows, the comparison is case insensitive. |
NOTES
In the Windows versions of Sculptor 5.1.x and earlier, all locks are write locks because the Windows 95, 98 and ME platforms do not support read locks and the code was not written to make an exception for the Windows NT family. Starting with Sculptor 5.3.0 (alpha 6 version), read locks are supported on Windows NT, 2000 and XP. A Sculptor program that is running on Windows 95, 98 or ME always uses write locks when accessing files locally or through Windows networking but uses both read locks and write locks when accessing files through kfserver running on Windows NT, 2000 or XP. There is no known backward compatibility option with this behaviour. Unix versions of kfserver have always supported read locks.
The error number returned by DOS/Windows when a target directory cannot be created on a network path is not always a meaningful value. In these cases, the error normally indicates that the user does not have permission to create the directory. Check that the drive and directory path are shared and have write permission.
RELATED TOPICS |