ckcplm.doc

linux终端仿真程序

B. Functions.

These are divided into three categories: file-related functions (B.1),
communication functions (B.2), and miscellaneous functions (B.3).

B.1.  File-related functions.

In most implementations, these are collected together into a module called
CK?FIO.c, where ? = U (UNIX), V (VMS), O (OS/2), etc (see CKAAAA.HLP).  To be
totally system-independent, C-Kermit maintains its own file numbers, and
provides the functions described in this section to deal with the files
associated with them.  The file numbers are referred to symbolically, and are
defined as follows in CKCKER.H:

#define ZCTERM      0	    	/* Console terminal */
#define ZSTDIO      1		/* Standard input/output */
#define ZIFILE	    2		/* Current input file for SEND command */
#define ZOFILE      3	    	/* Current output file for RECEIVE command */
#define ZDFILE      4	    	/* Current debugging log file */
#define ZTFILE      5	    	/* Current transaction log file */
#define ZPFILE      6	    	/* Current packet log file */
#define ZSFILE      7		/* Current session log file */
#define ZSYSFN	    8		/* Input from a system function (pipe) */
#define ZRFILE      9           /* Local file for READ command */  (NEW)
#define ZWFILE     10           /* Local file for WRITE command */ (NEW)
#define ZNFILS     11	    	/* How many defined file numbers */

In the descriptions below, fn refers to a filename, and n refers to one of
these file numbers.  Functions are of type int unless otherwise noted, and are
listed alphabetically.

int
chkfn(n) int n;
  Checks the file number n.  Returns:
  -1: File number n is out of range
   0: n is in range, but file is not open
   1: n in range and file is open

int
iswild(filspec) char *filespec; *NEW*
  Checks if the file specification is "wild", i.e. contains metacharacters
  or other notations intended to match multiple filenames.  Returns:
   0: not wild
   1: wild

int
isdir(string) char *string; *NEW*
  Checks if the string is the name of an existing directory.  Returns:
   0: not a directory (including any kind of error)
   1: it is an existing directory
  The idea is to check whether the string can be "cd'd" to, so in some cases
  (e.g. OS/2) it might also indicate any file structured device, such as a
  disk drive (like A:).  In VMS, isdir("DEV:[USER.TMP]") would succeed, but
  isdir("DEV:[BLAH]TMP.DIR") would fail because, even though it *is* a
  directory file, you can't "cd" to it.  The other way to check if a file
  is a directory (which would work even in the aforecited VMS case) would be
  if zchki(name) returned -2; we use this test for skipping over directory
  files (or recursing into them, etc) when sending a wildcard file group or
  other kind of file list, or in implementing the IF DIRECTORY command, etc.

char *
zfcdat(name) char *name; *NEW*
  Returns modification (preferably, otherwise creation) date/time of file
  whose name is given in the argument string.  Return value is a pointer to a
  string of the form yyyymmdd hh:mm:ss, for example 19931231 23:59:59, which
  represents the local time (no timezone or daylight savings time finagling
  required).  Returns the null string ("") on failure.  The text pointed to by
  the string pointer might be in a static buffer, and so should be copied to a
  safe place by the caller before any subsequent calls to this function.

struct zfnfp *
zfnqfp(fname, buflen, buf)  char * fname; int buflen; char * buf; *NEW*
  Given the filename "fname", the corresponding fully qualified, absolute
  filename is placed into the buffer buf, with maximum length buflen.
  On failure returns a NULL pointer.  On success returns a pointer to 
  a struct zfnfp (see ckcdeb.h) containing pointers to the full pathname
  and to just the filename.  All references to this function in mainline
  code must be protected by #ifdef ZFNQFP..#endif, because it is not present
  in all of the ck*fio.c modules.  So if you implement this function in a
  version that did not have it before, be sure to add #define ZFNQFP in the
  appropriate spot in ckcdeb.h.

int
zfseek(pos) long pos; *NEW*
  Positions the input pointer on the current input file to the given position.
  The pos argument is 0-based, the offset (distance in bytes) from beginning
  of the file.  Needed for RESEND, PSEND, and other recovery operations.  This
  function is not necessarily possible on all systems, e.g. record-oriented
  systems.  It should only be used on binary files (i.e. files we are sending
  in binary mode) and stream-oriented file systems.  Returns -1 on failure, 0
  on success.

int
zchdir(dirnam) char *dirnam;
  Change current or default directory to the one given in dirnam.
  Returns 1 on success, 0 on failure.

long
zchki(fn) char *fn;
  Check to see if file with name fn is a regular, readable, existing file,
  suitable for Kermit to send -- not a directory, not a symbolic link, etc.
  Returns:
  -3 if file exists but is not accessible (e.g. read-protected)
  -2 if file exists but is not of a readable type
  -1 on error (e.g. file does not exist, or fn is garbage)
  >= 0 (length of file) if file exists and is readable

int
zchko(fn) char *fn;
  Checks to see if a file of the given name can be created.  Returns:
  -1 if file cannot be created, or on any kind of error.
   0 if file can be created.

int
zchkspa(fn,len) char *f; long len;       *NEW*
  Check to see if there is sufficient space to store the file named fn,
  which is len bytes long.  Returns:
  -1 on error.
   0 if there is not enough space.
   1 if there is enough space.
  If you can't write a function to do this, then just make a dummy that
  always returns 1.  Higher level code will recover from disk-full errors.
  The receiving Kermit uses this function to refuse an incoming file based
  on its size, via the attribute mechanism.

int
zchin(n,c) int n; int *c;
  Get a character from file number n, return it in c (call with &c).
  Returns:
  -1 on failure, including EOF.
   0 on success with character in c.

int
zchout(n,c) int n; char c;
  Write the character c to file number n.  Returns:
  -1 error
   0 OK

int
zclose(n) int n;
  Close file number n.  Returns:
  -1 error
   1 OK

int
zdelet(fn) char *name;  *NEW*
  Attempts to delete the named file.  Returns:
  -1 on error
   0 if file was deleted successfully

char *
zgtdir()  *NEW*
  Returns a pointer to the name of the current directory, folder, etc, or a
  NULL pointer if the current directory cannot be determined.  Most Kermit
  versions currently do something like "system(PWDCMD)", but Macintoshes don't
  support system().

char *
zhome()
  Returns a pointer to a string containing the user's home directory, or NULL
  upon error.

int
zinfill()  *NEW*
  This function is used by the macro zminchar(), which is defined in ckcker.h.
  zminchar() manages its own buffer, and calls zinfill() to fill it whenever
  it becomes empty.  It is only used for sending files, and reads characters
  only from file number ZIFILE.  zinfill() returns -1 upon end of file,
  otherwise it returns the first character from the buffer it just read.

int
zkself()
  Kills the current job, session, process, etc, logs out, disappears.  Used by
  the Kermit server when it receives a BYE command.  On failure, returns -1.
  On success, does not return at all!  This function should not be called
  until all other steps have been taken to close files, etc.

VOID
zstrip(fn,&fn2) char *fn1, **fn2;
  Strip device and directory, etc, from file specification, leaving only the 
  filename.  For example DUA0:[PROGRAMS]OOFA.C;3 becomes OOFA.C, or
  /usr/fdc/oofa.c becomes oofa.c.  Returns pointer to result in fn2.

VOID
zltor(fn,fn2) char *fn1, *fn2;
  Local-To-Remote filename translation.  Translates the local filename fn into
  a format suitable for transmission to an arbitrary type of computer, and
  copies the result into the buffer pointed to by fn2.  Translation may involve
  (a) stripping the device and/or directory/path name, (b) converting
  lowercase to uppercase, (c) removing spaces and strange characters, or
  converting them to some innocuous alphabetic character like X, (d)
  discarding or converting extra periods (there should not be more than one).
  Does its best.  Returns no value.  name2 is a pointer to a buffer, furnished
  by the caller, into which zltor() writes the resulting name.  No length
  checking is done.

int
zmail(addr,fn) char *addr, fn;  *NEW*
  Send the local, existing file fn as e-mail to the address addr.  Returns:
  Returns 0 on success
   2 if mail delivered but temp file can't be deleted
  -2 if mail can't be delivered

int
zmkdir(path) char *path;  *NEW*
  Given a pointer to a file specification that might contain directory
  information, in which the filename is expected to be included,
  this routine attempts to create any directories in the file specification
  that don't already exist.  Returns:
   0 on success: no directories needed creation,
     or else all directories that needed creation were created successfully.
  -1 on failure to create any of the needed directories.

VOID
znewn(fn,s) char *fn, **s;
  Transforms the name fn into a filename which is guaranteed to be unique.
  If the file fn does not exist, then the new name will be the same as fn.
  Otherwise, it will be different.  Does its best, returns no value.  New
  name is created in caller's space.  Call like this: znewn(old,&new);.
  The second parameter is a pointer to the new name.  This pointer is set
  by znewn() to point to a static string in its own space.

int
znext(fn) char *fn;
  Copies the next file name from a file list created by zxpand() into the
  string pointed to by fn (see zxpand).  If no more files, then the null
  string is placed there.  Returns the number of files remaining in the list.

int
zopeni(n,fn) int n; char *fn;
  Opens the file named fn for input as file number n.  Returns:
  0 on failure.
  1 on success.

*NEW* (zopeno - the second two parameters are new)
int
zopeno(n,fn,zz,fcb) int n; char *name; struct zattr *zz; struct filinfo *fcb;
  Attempts to open the named file for output as file number n.  zz is a Kermit
  file attribute structure as defined in ckcdeb.h, containing various
  information about the file, including its size, creation date, and so forth.
  This function should attempt to honor as many of these as possible.  fcb is
  a "file control block" in the traditional sense, defined in ckcdeb.h,
  containing information of interest to complicated file systems like VAX/VMS,
  IBM MVS, etc, like blocksize, record length, organization, record format,
  carriage control, disposition (like create vs append), etc.  Returns:
  0 on failure.
  1 on success.

int
zoutdump()  *NEW*
  Dumps an output buffer.  Used with the macro zmchout() defined in ckcker.h.
  Used only with file number ZOFILE, i.e. the file that is being received by
  Kermit during file transfer.  Returns:
  -1 on failure.
   0 on success.

int
zprint(p,fn) char *p, *f;  *NEW*
  Prints the file with name fn on a local printer, with options p.  Returns:
  Returns 0 on success
   3 if file sent to printer but can't be deleted
  -3 if file can't be printed

int
zrename(fn,fn2) char *fn, *fn2;  *NEW*
  Changes the name of file fn to fn2.  If fn2 is the name of an existing
  directory, or a file-structured device, then file fn1 is moved to that
  directory or device, keeping its original name.  Returns:
  -1 on failure.
   0 on success.

VOID
zrtol(fn,fn2) char *fn, *fn2;
  Remote-To-Local filename translation.  Translates a "standard" filename
  (see zrtol) to a local filename.  For example, in Unix this function
  converts uppercase letters to lowercase.  Does its best, returns no value.
  New name is in string pointed to by fn2.

int
zsattr(xx) struct zattr *xx; {  *NEW*
  Fills in a Kermit file attribute structure for the file which is to be sent,
  namely the currently open ZIFILE.
  Returns:
  -1 on failure.
   0 on success with the structure filled in.
  If any string member is null, then it should be ignored by the caller.
  If any numeric member is -1, then it should be ignored by the caller.