VxWorks API Reference : OS Libraries
usrFsLib - file system user interface subroutine library
cd( ) - change the default directory
pwd( ) - print the current default directory
mkdir( ) - make a directory
rmdir( ) - remove a directory
rm( ) - remove a file
copyStreams( ) - copy from/to specified streams
copy( ) - copy in (or stdin) to out (or stdout)
chkdsk( ) - perform consistency checking on a MS-DOS file system
dirList( ) - list contents of a directory (multi-purpose)
ls( ) - generate a brief listing of a directory
ll( ) - generate a long listing of directory contents
lsr( ) - list the contents of a directory and any of its subdirectories
llr( ) - do a long listing of directory and all its subdirectories contents
cp( ) - copy file into other file/directory.
mv( ) - mv file into other directory.
xcopy( ) - copy a hierarchy of files with wildcards
xdelete( ) - delete a hierarchy of files with wildcards
attrib( ) - modify MS-DOS file attributes on a file or directory
xattrib( ) - modify MS-DOS file attributes of many files
diskFormat( ) - format a disk
diskInit( ) - initialize a file system on a block device
ioHelp( ) - print a synopsis of I/O utility functions
This library provides user-level utilities for managing file systems. These utilities may be used from Tornado Shell, the Target Shell or from an application.
Some of the functions in this library have counterparts of the same names built into the Tornado Shell (aka Windsh). The built-in functions perform similar functions on the Tornado host computer's I/O systems. Hence if one of such functions needs to be executed in order to perform any operation on the Target's I/O system, it must be preceded with an @ sign, e.g.: \ce -> @ls "/sd0" \ce will list the directory of a disk named "/sd0" on the target, wile
-> ls "/tmp"will list the contents of the "/tmp" directory on the host.The target I/O system and the Tornado Shell running on the host, each have their own notion of current directory, which are not related, hence
-> pwdwill display the Tornado Shell current directory on the host file system, while-> @pwdwill display the target's current directory on the target's console.
Some of the functions herein support wildcard characters in argument strings where file or directory names are expected. The wildcards are limited to "*" which matches zero or more characters and "?" which matches any single characters. Files or directories with names beginning with a "." are not normally matched with the "*" wildcard.
Directory listing is implemented in one function dirList( ), which can be accessed using one of these four front-end functions:
- ls( )
- produces a short list of files
- lsr( )
- is like ls( ) but ascends into subdirectories
- ll( )
- produces a detailed list of files, with file size, modification date attributes etc.
- llr( )
- is like ll( ) but also ascends into subdirectories
All of the directory listing functions accept a name of a directory or a single file to list, or a name which contain wildcards, which will result in listing of all objects that match the wildcard string provided.
ioLib, dosFsLib, netDrv, nfsLib, VxWorks Programmer's Guide: Target Shell VxWorks Programmer's Guide: Tornado Users's Guide
cd( ) - change the default directory
STATUS cd ( const char * name /* new directory name */ )
- NOTE
- This is a target resident function, which manipulates the target I/O system. It must be preceded with the @ letter if executed from the Tornado Shell (windsh), which has a built-in command of the same name that operates on the Host's I/O system.
This command sets the default directory to name. The default directory is a device name, optionally followed by a directory local to that device.
To change to a different directory, specify one of the following:
- -
- an entire path name with a device name, possibly followed by a directory name. The entire path name will be changed.
- -
- a directory name starting with a ~ or / or $. The directory part of the path, immediately after the device name, will be replaced with the new directory name.
- -
- a directory name to be appended to the current default directory. The directory name will be appended to the current default directory.
An instance of ".." indicates one level up in the directory tree.
Note that when accessing a remote file system via RSH or FTP, the VxWorks network device must already have been created using netDevCreate( ).
The cd( ) command does very little checking that name represents a valid path. If the path is invalid, cd( ) may return OK, but subsequent calls that depend on the default path will fail.
The following example changes the directory to device /fd0/:
-> cd "/fd0/"This example changes the directory to device wrs: with the local directory ~leslie/target:-> cd "wrs:~leslie/target"After the previous command, the following changes the directory to wrs:~leslie/target/config:-> cd "config"After the previous command, the following changes the directory to wrs:~leslie/target/demo:-> cd "../demo"After the previous command, the following changes the directory to wrs:/etc.-> cd "/etc"Note that ~ can be used only on network devices (RSH or FTP).
OK or ERROR.
usrFsLib, pwd( ), VxWorks Programmer's Guide: Target Shell
pwd( ) - print the current default directory
void pwd (void)
This command displays the current working device/directory.
- NOTE
- This is a target resident function, which manipulates the target I/O system. It must be preceded with the @ letter if executed from the Tornado Shell (windsh), which has a built-in command of the same name that operates on the Host's I/O system.
N/A
usrFsLib, cd( ), VxWorks Programmer's Guide: Target Shell, windsh, Tornado User's Guide: Shell
mkdir( ) - make a directory
STATUS mkdir ( const char * dirName /* directory name */ )
This command creates a new directory in a hierarchical file system. The dirName string specifies the name to be used for the new directory, and can be either a full or relative pathname.
This call is supported by the VxWorks NFS and dosFs file systems.
OK, or ERROR if the directory cannot be created.
usrFsLib, rmdir( ), VxWorks Programmer's Guide: Target Shell
rmdir( ) - remove a directory
STATUS rmdir ( const char * dirName /* name of directory to remove */ )
This command removes an existing directory from a hierarchical file system. The dirName string specifies the name of the directory to be removed, and may be either a full or relative pathname.
This call is supported by the VxWorks NFS and dosFs file systems.
OK, or ERROR if the directory cannot be removed.
usrFsLib, mkdir( ), VxWorks Programmer's Guide: Target Shell
rm( ) - remove a file
STATUS rm ( const char * fileName /* name of file to remove */ )
This command is provided for UNIX similarity. It simply calls remove( ).
OK, or ERROR if the file cannot be removed.
usrFsLib, remove( ), VxWorks Programmer's Guide: Target Shell
copyStreams( ) - copy from/to specified streams
STATUS copyStreams ( int inFd, /* file descriptor of stream to copy from */ int outFd /* file descriptor of stream to copy to */ )
This command copies from the stream identified by inFd to the stream identified by outFd until an end of file is reached in inFd. This command is used by copy( ).
OK, or ERROR if there is an error reading from inFd or writing to outFd.
usrFsLib, copy( ), VxWorks Programmer's Guide: Target Shell
copy( ) - copy in (or stdin) to out (or stdout)
STATUS copy ( const char * in, /* name of file to read (if NULL assume stdin) */ const char * out /* name of file to write (if NULL assume */ /* stdout) */ )
This command copies from the input file to the output file, until an end-of-file is reached.
The following example displays the file dog, found on the default file device:
-> copy <dogThis example copies from the console to the file dog, on device /ct0/, until an EOF (default ^D) is typed:-> copy >/ct0/dogThis example copies the file dog, found on the default file device, to device /ct0/:-> copy <dog >/ct0/dogThis example makes a conventional copy from the file named file1 to the file named file2:-> copy "file1", "file2"Remember that standard input and output are global; therefore, spawning the first three constructs will not work as expected.
OK, or ERROR if in or out cannot be opened/created, or if there is an error copying from in to out.
usrFsLib, copyStreams( ), tyEOFSet( ), cp( ), xcopy( ) VxWorks Programmer's Guide: Target Shell
chkdsk( ) - perform consistency checking on a MS-DOS file system
STATUS chkdsk ( const char * pDevName, /* device name */ u_int repairLevel, /* how to fix errors */ u_int verbose /* verbosity level */ )
This function invokes the integral consistency checking built into the dosFsLib file system, via FIOCHKDSK ioctl. During the test, the file system will be blocked from application code access, and will emit messages describing any inconsistencies found on the disk, as well as some statistics, depending on the value of the verbose argument. Depending the value of repairLevel, the inconsistencies will be repaired, and changes written to disk.
These are the values for repairLevel:
0 Same as DOS_CHK_ONLY (1) DOS_CHK_ONLY (1) Only report errors, do not modify disk. DOS_CHK_REPAIR (2) Repair any errors found. These are the values for verbose:
0 similar to DOS_CHK_VERB_1 DOS_CHK_VERB_SILENT (0xff00) Do not emit any messages, except errors encountered. DOS_CHK_VERB_1 (0x0100) Display some volume statistics when done testing, as well as errors encountered during the test. DOS_CHK_VERB_2 (0x0200) In addition to the above option, display path of every file, while it is being checked. This option may significantly slow down the test process. Note that the consistency check procedure will unmount the file system, meaning the all currently open file descriptors will be deemed unusable.
OK or ERROR if device can not be checked or could not be repaired.
dirList( ) - list contents of a directory (multi-purpose)
STATUS dirList ( int fd, /* file descriptor to write on */ char * dirName, /* name of the directory to be listed */ BOOL doLong, /* if TRUE, do long listing */ BOOL doTree /* if TRUE, recurse into subdirs */ )
This command is similar to UNIX ls. It lists the contents of a directory in one of two formats. If doLong is FALSE, only the names of the files (or subdirectories) in the specified directory are displayed. If doLong is TRUE, then the file name, size, date, and time are displayed. If doTree flag is TRUE, then each subdirectory encountered will be listed as well (i.e. the listing will be recursive).
The dirName parameter specifies the directory to be listed. If dirName is omitted or NULL, the current working directory will be listed. dirName may contain wildcard characters to list some of the directory's contents.
- With dosFsLib file systems, MS-DOS volume label entries are not reported. - Although an output format very similar to UNIX "ls" is employed, some information items have no particular meaning on some file systems. - Some file systems which do not support the POSIX compliant dirLib( ) interface, can not support the doLong and doTree options.
OK or ERROR.
usrFsLib, dirLib, dosFsLib, ls( ), ll( ), lsr( ), llr( )
ls( ) - generate a brief listing of a directory
STATUS ls ( char * dirName, /* name of dir to list */ BOOL doLong /* switch on details */ )
This function is simply a front-end for dirList( ), intended for brevity and backward compatibility. It produces a list of files and directories, without details such as file size and date, and without recursion into subdirectories.
dirName is a name of a directory or file, and may contain wildcards. doLong is provided for backward compatibility.
- NOTE
- This is a target resident function, which manipulates the target I/O system. It must be preceded with the @ letter if executed from the Tornado Shell (windsh), which has a built-in command of the same name that operates on the Host's I/O system.
OK or ERROR.
ll( ) - generate a long listing of directory contents
STATUS ll ( char * dirName /* name of directory to list */ )
This command causes a long listing of a directory's contents to be displayed. It is equivalent to:
-> dirList 1, dirName, TRUE, FALSEdirName is a name of a directory or file, and may contain wildcards.
This is a target resident function, which manipulates the target I/O system. It must be preceded with the @ letter if executed from the Tornado Shell (windsh), which has a built-in command of the same name that operates on the Host's I/O system.
When used with netDrv devices (FTP or RSH), ll( ) does not give directory information. It is equivalent to an ls( ) call with no long-listing option.
OK or ERROR.
lsr( ) - list the contents of a directory and any of its subdirectories
STATUS lsr ( char * dirName /* name of dir to list */ )
This function is simply a front-end for dirList( ), intended for brevity and backward compatibility. It produces a list of files and directories, without details such as file size and date, with recursion into subdirectories.
dirName is a name of a directory or file, and may contain wildcards.
OK or ERROR.
llr( ) - do a long listing of directory and all its subdirectories contents
STATUS llr ( char * dirName /* name of directory to list */ )
This command causes a long listing of a directory's contents to be displayed. It is equivalent to:
-> dirList 1, dirName, TRUE, TRUE* dirName is a name of a directory or file, and may contain wildcards.
When used with netDrv devices (FTP or RSH), ll( ) does not give directory information. It is equivalent to an ls( ) call with no long-listing option.
OK or ERROR.
cp( ) - copy file into other file/directory.
STATUS cp ( const char * src, /* source file or wildcard pattern */ const char * dest /* destination file name or directory */ )
This command copies from the input file to the output file. If destination name is directory, a source file is copied into this directory, using the last element of the source file name to be the name of the destination file.
This function is very similar to copy( ), except it is somewhat more similar to the UNIX "cp" program in its handling of the destination.
src may contain a wildcard pattern, in which case all files matching the pattern will be copied to the directory specified in dest. This function does not copy directories, and is not recursive. To copy entire subdirectories recursively, use xcopy( ).
-> cp( "/sd0/FILE1.DAT","/sd0/dir2/f001.dat") -> cp( "/sd0/dir1/file88","/sd0/dir2") -> cp( "/sd0/*.tmp","/sd0/junkdir")
OK or ERROR if destination is not a directory while src is a wildcard pattern, or if any of the files could not be copied.
SEE ALSO; xcopy( )
mv( ) - mv file into other directory.
STATUS mv ( const char * src, /* source file name or wildcard */ const char * dest /* destination name or directory */ )
This function is similar to rename( ) but behaves somewhat more like the UNIX program "mv", it will overwrite files.
This command moves the src file or directory into a file which name is passed in the dest argument, if dest is a regular file or does not exist. If dest name is a directory, the source object is moved into this directory as with the same name, if dest is NULL, the current directory is assumed as the destination directory. src may be a single file name or a path containing a wildcard pattern, in which case all files or directories matching the pattern will be moved to dest which must be a directory in this case.
-> mv( "/sd0/dir1","/sd0/dir2") -> mv( "/sd0/*.tmp","/sd0/junkdir") -> mv( "/sd0/FILE1.DAT","/sd0/dir2/f001.dat")
OK or error if any of the files or directories could not be moved, or if src is a pattern but the destination is not a directory.
xcopy( ) - copy a hierarchy of files with wildcards
STATUS xcopy ( const char * source, /* source directory or wildcard name */ const char * dest /* destination directory */ )
source is a string containing a name of a directory, or a wildcard or both which will cause this function to make a recursive copy of all files residing in that directory and matching the wildcard pattern into the dest directory, preserving the file names and subdirectories.
This function may call itself in accordance with the depth of the source directory, and occupies approximately 800 bytes per stack frame, meaning that to accommodate the maximum depth of subdirectories which is 20, at least 16 Kbytes of stack space should be available to avoid stack overflow.
OK or ERROR if any operation has failed.
usrFsLib, tarLib, checkStack( ), cp( )
xdelete( ) - delete a hierarchy of files with wildcards
STATUS xdelete ( const char * source /* source directory or wildcard name */ )
source is a string containing a name of a directory, or a wildcard or both which will cause this function to recursively remove all files and subdirectories residing in that directory and matching the wildcard pattern. When a directory is encountered, all its contents are removed, and then the directory itself is deleted.
This function may call itself in accordance with the depth of the source directory, and occupies approximately 520 bytes per stack frame, meaning that to accommodate the maximum depth of subdirectories which is 20, at least 10 Kbytes of stack space should be available to avoid stack overflow.
OK or ERROR if any operation has failed.
usrFsLib, checkStack( ), cp( ), copy( ), xcopy( ), tarLib
attrib( ) - modify MS-DOS file attributes on a file or directory
STATUS attrib ( const char * fileName, /* file or dir name on which to change flags */ const char * attr /* flag settings to change */ )
This function provides means for the user to modify the attributes of a single file or directory. There are four attribute flags which may be modified: "Archive", "System", "Hidden" and "Read-only". Among these flags, only "Read-only" has a meaning in VxWorks, namely, read-only files can not be modified deleted or renamed.
The attr argument string may contain must start with either "+" or "-", meaning the attribute flags which will follow should be either set or cleared. After "+" or "-" any of these four letter will signify their respective attribute flags - "A", "S", "H" and "R".
For example, to write-protect a particular file and flag that it is a system file:
-> attrib( "bootrom.sys", "+RS")
OK, or ERROR if the file can not be opened.
xattrib( ) - modify MS-DOS file attributes of many files
STATUS xattrib ( const char * source, /* file or directory name on which to */ /* change flags */ const char * attr /* flag settings to change */ )
This function is essentially the same as attrib( ), but it accepts wildcards in fileName, and traverses subdirectories in order to modify attributes of entire file hierarchies.
The attr argument string may contain must start with either "+" or "-", meaning the attribute flags which will follow should be either set or cleared. After "+" or "-" any of these four letter will signify their respective attribute flags - "A", "S", "H" and "R".
-> xattrib( "/sd0/sysfiles", "+RS") /* write protect "sysfiles" */ -> xattrib( "/sd0/logfiles", "-R") /* unprotect logfiles before deletion */ -> xdelete( "/sd0/logfiles")
This function may call itself in accordance with the depth of the source directory, and occupies approximately 520 bytes per stack frame, meaning that to accommodate the maximum depth of subdirectories which is 20, at least 10 Kbytes of stack space should be available to avoid stack overflow.
OK, or ERROR if the file can not be opened.
diskFormat( ) - format a disk
STATUS diskFormat ( const char * pDevName /* name of the device to initialize */ )
This command formats a disk and creates a file system on it. The device must already have been created by the device driver and initialized for use with a particular file system, via dosFsDevInit( ).
This command calls ioctl( ) to perform the FIODISKFORMAT function.
-> diskFormat "/fd0/"
OK, or ERROR if the device cannot be opened or formatted.
usrFsLib, dosFsLib VxWorks Programmer's Guide: Target Shell
diskInit( ) - initialize a file system on a block device
STATUS diskInit ( const char * pDevName /* name of the device to initialize */ )
This function is now obsolete, use of dosFsVolFormat( ) is recommended.
This command creates a new, blank file system on a block device. The device must already have been created by the device driver and initialized for use with a particular file system, via dosFsDevCreate( ).
-> diskInit "/fd0/"Note that if the disk is unformatted, it can not be mounted, thus open( ) will return error, in which case use the dosFsVolFormat routine manually.This routine performs the FIODISKINIT ioctl operation.
OK, or ERROR if the device cannot be opened or initialized.
usrFsLib, dosFsLib VxWorks Programmer's Guide: Target Shell
ioHelp( ) - print a synopsis of I/O utility functions
void ioHelp (void)
This function prints out synopsis for the I/O and File System utility functions.
N/A
usrFsLib, VxWorks Programmer's Guide: Target Shell