tools: document shared helper functions
Add function-level comments to the shared helper routines in tools.c. Document the purpose and behavior of the common DOS compatibility, keyboard, paging, memory, string, environment, current directory handle, path formatting, wildcard and endian/NCP22 helper functions. No behavior change.
This commit is contained in:
Mario Fetka
254
tools.c
254
tools.c
@@ -160,8 +160,15 @@ int tool_copy_ncp22_name(uint8 *dst, char *src, uint8 *len_out)
|
||||
|
||||
#ifdef __WATCOMC__
|
||||
/*
|
||||
* Borland C compatibility wrappers used by the historical mars-nwe DOS tools.
|
||||
* Open Watcom does not provide getcurdir()/setdisk() under these Borland names.
|
||||
* getcurdir
|
||||
*
|
||||
* Purpose:
|
||||
* Borland-compatible wrapper for DOS INT 21h AH=47h. It returns the
|
||||
* current directory for the selected drive without the drive letter.
|
||||
*
|
||||
* Notes:
|
||||
* Open Watcom does not provide getcurdir() under the Borland name used by
|
||||
* the historical MARS-NWE DOS tools.
|
||||
*/
|
||||
int getcurdir(int drive, char *directory)
|
||||
{
|
||||
@@ -176,6 +183,13 @@ int getcurdir(int drive, char *directory)
|
||||
return(regs.x.cflag ? -1 : 0);
|
||||
}
|
||||
|
||||
/*
|
||||
* setdisk
|
||||
*
|
||||
* Purpose:
|
||||
* Borland-compatible wrapper for DOS INT 21h AH=0eh. It selects the DOS
|
||||
* default drive using the Borland drive numbering convention.
|
||||
*/
|
||||
void setdisk(int drive)
|
||||
{
|
||||
REGS regs;
|
||||
@@ -186,6 +200,13 @@ void setdisk(int drive)
|
||||
}
|
||||
#endif
|
||||
|
||||
/*
|
||||
* key_pressed
|
||||
*
|
||||
* Purpose:
|
||||
* Checks whether a key is waiting in the BIOS keyboard buffer without
|
||||
* consuming it.
|
||||
*/
|
||||
int key_pressed(void)
|
||||
{
|
||||
#ifdef __WATCOMC__
|
||||
@@ -204,6 +225,12 @@ int key_pressed(void)
|
||||
#endif
|
||||
}
|
||||
|
||||
/*
|
||||
* clear_kb
|
||||
*
|
||||
* Purpose:
|
||||
* Drains all pending keys from the BIOS keyboard buffer.
|
||||
*/
|
||||
void clear_kb(void)
|
||||
{
|
||||
#ifdef __WATCOMC__
|
||||
@@ -219,6 +246,16 @@ void clear_kb(void)
|
||||
#endif
|
||||
}
|
||||
|
||||
/*
|
||||
* ask_user
|
||||
*
|
||||
* Purpose:
|
||||
* Prints a formatted yes/no question and waits until the user answers with
|
||||
* Y/J or N.
|
||||
*
|
||||
* Returns:
|
||||
* 1 for yes, 0 for no.
|
||||
*/
|
||||
int ask_user(char *p, ...)
|
||||
{
|
||||
int key;
|
||||
@@ -245,6 +282,12 @@ int ask_user(char *p, ...)
|
||||
return(flag);
|
||||
}
|
||||
|
||||
/*
|
||||
* xmalloc
|
||||
*
|
||||
* Purpose:
|
||||
* Allocates memory or terminates the utility with a diagnostic.
|
||||
*/
|
||||
char *xmalloc(uint size)
|
||||
{
|
||||
char *p = (size) ? (char *)malloc(size) : (char*)NULL;
|
||||
@@ -255,6 +298,12 @@ char *xmalloc(uint size)
|
||||
return(p);
|
||||
}
|
||||
|
||||
/*
|
||||
* xcmalloc
|
||||
*
|
||||
* Purpose:
|
||||
* Allocates zero-filled memory or terminates the utility with a diagnostic.
|
||||
*/
|
||||
char *xcmalloc(uint size)
|
||||
{
|
||||
char *p = xmalloc(size);
|
||||
@@ -262,6 +311,12 @@ char *xcmalloc(uint size)
|
||||
return(p);
|
||||
}
|
||||
|
||||
/*
|
||||
* x_x_xfree
|
||||
*
|
||||
* Purpose:
|
||||
* Frees an allocated pointer and clears the caller's pointer value.
|
||||
*/
|
||||
void x_x_xfree(char **p)
|
||||
{
|
||||
if (*p != (char *)NULL){
|
||||
@@ -270,8 +325,16 @@ void x_x_xfree(char **p)
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* strmaxcpy
|
||||
*
|
||||
* Purpose:
|
||||
* Copies at most len bytes from source to dest and always terminates dest.
|
||||
*
|
||||
* Returns:
|
||||
* Number of copied source bytes, excluding the terminating zero byte.
|
||||
*/
|
||||
int strmaxcpy(char *dest, char *source, int len)
|
||||
/* copied max. len chars + '\0' Byte */
|
||||
{
|
||||
int slen = (source != (char *)NULL) ? min(len, strlen(source)) : 0;
|
||||
if (dest == (char *)NULL) return(0);
|
||||
@@ -280,6 +343,12 @@ int strmaxcpy(char *dest, char *source, int len)
|
||||
return(slen);
|
||||
}
|
||||
|
||||
/*
|
||||
* xadd_char
|
||||
*
|
||||
* Purpose:
|
||||
* Appends one character to a bounded C string and keeps it terminated.
|
||||
*/
|
||||
char *xadd_char(char *s, int c, int maxlen)
|
||||
{
|
||||
if (s && maxlen) {
|
||||
@@ -291,6 +360,13 @@ char *xadd_char(char *s, int c, int maxlen)
|
||||
return(s);
|
||||
}
|
||||
|
||||
/*
|
||||
* down_char
|
||||
*
|
||||
* Purpose:
|
||||
* Converts one DOS character to lowercase for the ASCII range and the
|
||||
* German OEM characters historically handled by MARS-NWE.
|
||||
*/
|
||||
static uint8 down_char(uint8 ch)
|
||||
{
|
||||
if (ch > 64 && ch < 91) return(ch + 32);
|
||||
@@ -303,6 +379,13 @@ static uint8 down_char(uint8 ch)
|
||||
return(ch);
|
||||
}
|
||||
|
||||
/*
|
||||
* up_char
|
||||
*
|
||||
* Purpose:
|
||||
* Converts one DOS character to uppercase for the ASCII range and the
|
||||
* German OEM characters historically handled by MARS-NWE.
|
||||
*/
|
||||
static uint8 up_char(uint8 ch)
|
||||
{
|
||||
if (ch > 96 && ch < 123) return(ch - 32);
|
||||
@@ -315,6 +398,12 @@ static uint8 up_char(uint8 ch)
|
||||
return(ch);
|
||||
}
|
||||
|
||||
/*
|
||||
* upstr
|
||||
*
|
||||
* Purpose:
|
||||
* Uppercases a DOS string in place.
|
||||
*/
|
||||
uint8 *upstr(uint8 *s)
|
||||
{
|
||||
if (!s) return((uint8*)NULL);
|
||||
@@ -322,6 +411,12 @@ uint8 *upstr(uint8 *s)
|
||||
return(s);
|
||||
}
|
||||
|
||||
/*
|
||||
* deb
|
||||
*
|
||||
* Purpose:
|
||||
* Removes trailing spaces and tabs from a string in place.
|
||||
*/
|
||||
void deb(uint8 *s)
|
||||
{
|
||||
if (!s || !*s) return;
|
||||
@@ -333,6 +428,13 @@ void deb(uint8 *s)
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* leb
|
||||
*
|
||||
* Purpose:
|
||||
* Historical leading-space helper used by the old tools. It keeps the
|
||||
* original behavior and shifts the string to the first whitespace boundary.
|
||||
*/
|
||||
void leb(uint8 *s)
|
||||
{
|
||||
if (!s || !*s || (*s != 32 && *s != 9)) return;
|
||||
@@ -343,6 +445,13 @@ void leb(uint8 *s)
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* korrpath
|
||||
*
|
||||
* Purpose:
|
||||
* Normalizes a DOS/NetWare path for the older tools by converting backslash
|
||||
* separators to slash and lowercasing DOS characters.
|
||||
*/
|
||||
void korrpath(char *s)
|
||||
{
|
||||
if (!s) return;
|
||||
@@ -352,6 +461,12 @@ void korrpath(char *s)
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* get_path_fn
|
||||
*
|
||||
* Purpose:
|
||||
* Splits a historical slash/colon path into directory part and file name.
|
||||
*/
|
||||
void get_path_fn(char *s, char *p, char *fn)
|
||||
{
|
||||
int j= strlen(s);
|
||||
@@ -396,6 +511,13 @@ typedef struct {
|
||||
uint16 blocks;
|
||||
} SPEICH_BLOCK;
|
||||
|
||||
/*
|
||||
* getglobenvironment
|
||||
*
|
||||
* Purpose:
|
||||
* Locates the parent DOS environment block through the PSP and reports its
|
||||
* allocated and currently used size.
|
||||
*/
|
||||
static char *getglobenvironment(uint16 *maxsize, uint16 *aktsize)
|
||||
{
|
||||
static uint16 globmaxenvsize=0;
|
||||
@@ -423,6 +545,12 @@ static char *getglobenvironment(uint16 *maxsize, uint16 *aktsize)
|
||||
return(globenviron);
|
||||
}
|
||||
|
||||
/*
|
||||
* getglobenv
|
||||
*
|
||||
* Purpose:
|
||||
* Reads one variable from the parent DOS environment block.
|
||||
*/
|
||||
char *getglobenv(char *option)
|
||||
{
|
||||
uint16 maxenvsize;
|
||||
@@ -446,6 +574,12 @@ char *getglobenv(char *option)
|
||||
return(NULL);
|
||||
}
|
||||
|
||||
/*
|
||||
* putglobenv
|
||||
*
|
||||
* Purpose:
|
||||
* Updates or removes one variable in the parent DOS environment block.
|
||||
*/
|
||||
int putglobenv(char *option)
|
||||
{
|
||||
uint16 maxenvsize;
|
||||
@@ -492,6 +626,12 @@ int putglobenv(char *option)
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
* tool_page_line
|
||||
*
|
||||
* Purpose:
|
||||
* Implements Novell-style paged output prompting after 24 printed lines.
|
||||
*/
|
||||
int tool_page_line(int *line_count, int *continuous)
|
||||
{
|
||||
int ch;
|
||||
@@ -529,6 +669,12 @@ int tool_page_line(int *line_count, int *continuous)
|
||||
* command-specific modules.
|
||||
****************************************************************/
|
||||
|
||||
/*
|
||||
* tool_strsame
|
||||
*
|
||||
* Purpose:
|
||||
* Compares two command-line strings case-insensitively for ASCII letters.
|
||||
*/
|
||||
int tool_strsame(char *a, char *b)
|
||||
{
|
||||
if (!a) a = "";
|
||||
@@ -544,6 +690,12 @@ int tool_strsame(char *a, char *b)
|
||||
return(1);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_is_help_arg
|
||||
*
|
||||
* Purpose:
|
||||
* Recognizes the common help arguments used by the DOS utilities.
|
||||
*/
|
||||
int tool_is_help_arg(char *s)
|
||||
{
|
||||
if (!s) return(0);
|
||||
@@ -551,12 +703,24 @@ int tool_is_help_arg(char *s)
|
||||
tool_strsame(s, "?"));
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_is_option
|
||||
*
|
||||
* Purpose:
|
||||
* Checks whether an argument is a DOS-style option beginning with / or -.
|
||||
*/
|
||||
int tool_is_option(char *s)
|
||||
{
|
||||
if (!s) return(0);
|
||||
return(s[0] == '/' || s[0] == '-');
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_is_files_option
|
||||
*
|
||||
* Purpose:
|
||||
* Recognizes the /FILES option and its short form.
|
||||
*/
|
||||
int tool_is_files_option(char *s)
|
||||
{
|
||||
if (!s) return(0);
|
||||
@@ -564,6 +728,12 @@ int tool_is_files_option(char *s)
|
||||
tool_strsame(s, "/F") || tool_strsame(s, "-F"));
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_is_subdirs_option
|
||||
*
|
||||
* Purpose:
|
||||
* Recognizes the /SUBDIRS, /SUBDIRECTORIES and /S recursive options.
|
||||
*/
|
||||
int tool_is_subdirs_option(char *s)
|
||||
{
|
||||
if (!s) return(0);
|
||||
@@ -573,6 +743,12 @@ int tool_is_subdirs_option(char *s)
|
||||
tool_strsame(s, "/S") || tool_strsame(s, "-S"));
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_get_current_drive
|
||||
*
|
||||
* Purpose:
|
||||
* Returns the DOS default drive using INT 21h AH=19h.
|
||||
*/
|
||||
int tool_get_current_drive(void)
|
||||
{
|
||||
REGS regs;
|
||||
@@ -582,6 +758,13 @@ int tool_get_current_drive(void)
|
||||
return((int)regs.h.al);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_current_dhandle
|
||||
*
|
||||
* Purpose:
|
||||
* Resolves the current DOS drive to the active NetWare connection and
|
||||
* directory handle.
|
||||
*/
|
||||
int tool_current_dhandle(uint8 *connid, uint8 *dhandle)
|
||||
{
|
||||
uint8 flags = 0;
|
||||
@@ -596,6 +779,13 @@ int tool_current_dhandle(uint8 *connid, uint8 *dhandle)
|
||||
return(0);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_current_dhandle_only
|
||||
*
|
||||
* Purpose:
|
||||
* Convenience wrapper for callers that only need the current directory
|
||||
* handle and do not use the connection id.
|
||||
*/
|
||||
int tool_current_dhandle_only(uint8 *dhandle)
|
||||
{
|
||||
uint8 connid = 0;
|
||||
@@ -603,6 +793,13 @@ int tool_current_dhandle_only(uint8 *dhandle)
|
||||
return(tool_current_dhandle(&connid, dhandle));
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_current_prefix
|
||||
*
|
||||
* Purpose:
|
||||
* Builds the current SERVER\VOLUME:PATH display prefix used by Novell-like
|
||||
* command output.
|
||||
*/
|
||||
int tool_current_prefix(char *out, int max)
|
||||
{
|
||||
uint8 connid = 0;
|
||||
@@ -642,6 +839,12 @@ int tool_current_prefix(char *out, int max)
|
||||
return(0);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_is_current_path
|
||||
*
|
||||
* Purpose:
|
||||
* Checks whether a path argument refers to the current directory.
|
||||
*/
|
||||
int tool_is_current_path(char *path)
|
||||
{
|
||||
if (!path || !*path) return(1);
|
||||
@@ -651,6 +854,12 @@ int tool_is_current_path(char *path)
|
||||
return(0);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_upcopy
|
||||
*
|
||||
* Purpose:
|
||||
* Copies a path/string while uppercasing ASCII letters and converting / to \.
|
||||
*/
|
||||
void tool_upcopy(char *dst, char *src, int max)
|
||||
{
|
||||
int i = 0;
|
||||
@@ -666,6 +875,13 @@ void tool_upcopy(char *dst, char *src, int max)
|
||||
dst[i] = 0;
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_basename
|
||||
*
|
||||
* Purpose:
|
||||
* Extracts the final DOS/NetWare path component after uppercasing and path
|
||||
* separator normalization.
|
||||
*/
|
||||
void tool_basename(char *dst, char *src, int max)
|
||||
{
|
||||
char up[260];
|
||||
@@ -681,6 +897,13 @@ void tool_basename(char *dst, char *src, int max)
|
||||
strmaxcpy(dst, up, max - 1);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_header_path
|
||||
*
|
||||
* Purpose:
|
||||
* Formats a path for Novell-style command headers relative to the current
|
||||
* mapped NetWare prefix.
|
||||
*/
|
||||
void tool_header_path(char *out, char *path, int max)
|
||||
{
|
||||
char prefix[260];
|
||||
@@ -719,6 +942,12 @@ void tool_header_path(char *out, char *path, int max)
|
||||
strcat(out, p);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_is_dot_dir
|
||||
*
|
||||
* Purpose:
|
||||
* Checks for the special . and .. directory entries.
|
||||
*/
|
||||
int tool_is_dot_dir(char *name)
|
||||
{
|
||||
if (!name) return(0);
|
||||
@@ -727,6 +956,12 @@ int tool_is_dot_dir(char *name)
|
||||
return(0);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_join_path
|
||||
*
|
||||
* Purpose:
|
||||
* Joins a base path and child name with a DOS/NetWare separator when needed.
|
||||
*/
|
||||
void tool_join_path(char *out, char *base, char *name, int max)
|
||||
{
|
||||
int len;
|
||||
@@ -747,6 +982,12 @@ void tool_join_path(char *out, char *base, char *name, int max)
|
||||
strcat(out, name);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_has_wildcards
|
||||
*
|
||||
* Purpose:
|
||||
* Checks whether a path contains DOS wildcard characters.
|
||||
*/
|
||||
int tool_has_wildcards(char *path)
|
||||
{
|
||||
if (!path) return(0);
|
||||
@@ -757,6 +998,13 @@ int tool_has_wildcards(char *path)
|
||||
return(0);
|
||||
}
|
||||
|
||||
/*
|
||||
* tool_parent_pattern
|
||||
*
|
||||
* Purpose:
|
||||
* Splits a wildcard path into parent directory and search pattern. Missing
|
||||
* patterns default to *.* for Novell-style directory scans.
|
||||
*/
|
||||
void tool_parent_pattern(char *dir, char *pattern, char *path,
|
||||
int maxdir, int maxpat)
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user