ckcplm.txt 126 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907
  1. The Kermit Project
  2. Columbia University
  3. 612 West 115th Street
  4. New York NY 10025 USA
  5. kermit@columbia.edu
  6. ...since 1981
  7. C-Kermit Program Logic Manual
  8. Frank da Cruz
  9. The Kermit Project
  10. As of: C-Kermit 9.0.300, 30 June 2011
  11. Last update: Fri Jul 1 15:47:34 2011
  12. IF YOU ARE READING A PLAIN-TEXT version of this document, note that
  13. this file is a plain-text dump of a Web page. You can visit the
  14. original (and possibly more up-to-date) Web page here:
  15. http://www.columbia.edu/kermit/ckcplm.html
  16. CONTENTS
  17. 1. INTRODUCTION
  18. 2. FILES
  19. 3. SOURCE CODE PORTABILITY AND STYLE
  20. 4. MODULES
  21. 4.A. Group A: Library Routines
  22. 4.B. Group B: Kermit File Transfer
  23. 4.C. Group C: Character-Set Conversion
  24. 4.D. Group D: User Interface
  25. 4.E. Group E: Platform-Dependent I/O
  26. 4.F. Group F: Network Support
  27. 4.G. Group G: Formatted Screen Support
  28. 4.H. Group H: Pseudoterminal Support
  29. 4.I. Group I: Security
  30. I. APPENDIX I: FILE PERMISSIONS
  31. 1. INTRODUCTION
  32. The Kermit Protocol is specified in the book Kermit, A File
  33. Transfer Protocol by Frank da Cruz, Digital Press / Butterworth
  34. Heinemann, Newton, MA, USA (1987), 379 pages, ISBN 0-932376-88-6. It is
  35. assumed the reader is familiar with the Kermit protocol specification.
  36. This file describes the relationship among the modules and functions of
  37. C-Kermit 5A and later, and other programming considerations. C-Kermit
  38. is designed to be portable to any kind of computer that has a C
  39. compiler. The source code is broken into many files that are grouped
  40. according to their function, as shown in the Contents.
  41. C-Kermit has seen constant development since 1985. Throughout its
  42. history, there has been a neverending tug-of-war among:
  43. a. Functionality: adding new features, fixing bugs, improving
  44. performance.
  45. b. Adding support for new platforms or communication methods.
  46. c. "Buzzword 1.0 compliance".
  47. The latter category is the most frustrating, since it generally
  48. involves massive changes just to keep the software doing what it did
  49. before in some new setting: e.g. the K&R-to-ANSIC conversion (which had
  50. to be done, of course, without breaking K&R); Y2K (not a big deal in
  51. our case); the many and varied UNIX and other API "standards" with
  52. which to "comply".
  53. Upon first glance at the source code, you will probably be appalled.
  54. Many will be tempted to clean it up and modernize it. But as soon as
  55. you do, you are sure to break something. Remember that above all else,
  56. the C-Kermit code is portable to every Unix platform that ever existed,
  57. going back Unix V7 (1979)*, and to several other completely different
  58. and unrelated operating-system families such as DEC/HP VMS, DG AOS/VS,
  59. and Stratus VOS, as well as to some Unix offshoots like OS-9 and Plan 9
  60. (from Outer Space). Every release of Kermit has been checked on every
  61. platform available -- the older the better! -- to make sure it still
  62. builds and runs. Even today (2011), there are modern Unix systems that
  63. have non-ANSI C compilers, foremost among them HP-UX (where an ANSI
  64. optimizing C compiler is available, but only as an expensive add-on).
  65. In a way, portability is the most important feature of C-Kermit and
  66. every effort should be made to preserve it through future releases.
  67. Voluminous edit histories are available going back to May 1985. The
  68. first versions of C-Kermit were done on our DEC VAX-11/750 with
  69. Ultrix 1.0 and 2.0 (as well as departmental 750s with 4.2BSD**), DEC
  70. Pro-380 workstations (desktop PDP-11s) running 2.9BSD, which was
  71. ported to the 380 by us. Later (1988 or so) on a big VAX 8650 with
  72. Ultrix, which became an 8700 (these no doubt weighed several tons), and
  73. finally a succession of non-DEC equipment: an Encore Multimax, 25 years
  74. worth of Suns, and now Linux on HP Blades. We also had our own VMS
  75. development systems for some years. All this plus a generous assortment
  76. of departmental and offsite guest accounts on a multitude of platforms.
  77. Anyway, the edit histories:
  78. ckc04e.txt C-Kermit 4.2(030) May 1985 to 4E(072) Jan 1989.
  79. ckc04f.txt C-Kermit 4F(077) Arp 1989 to 4F(095) Aug 1989.
  80. ckc168.txt Updates to C-Kermit 5A(168) for VMS Nov 1991
  81. ckc178.txt C-Kermit 5A(100) Jul 1989 to 5A(178) Jan 1992
  82. ckc188.txt C-Kermit 5A(188) development, 1992
  83. ckc189.txt C-Kermit 5A(189) development, 1993
  84. ckc192.txt C-Kermit 6.0(192) development, 1998
  85. ckc197.txt C-Kermit 7.0(197) development, 2000
  86. ckc200.txt C-Kermit 8.0.200 development, 2001
  87. ckc211.txt C-Kermit 8.0.201 through 8.0.209 2001-2004
  88. ckc300.txt C-Kermit 9.0.300 June 2011
  89. _________________________________
  90. * C-Kermit 6.0 was the last one to be built on V7, as I recall. The
  91. code should still be good for V7 but it probably has outgrown the
  92. 16-bit address space. In any case there is still a V7 makefile target
  93. and a V7 path through the forest of #ifdefs in the code if anybody is
  94. running V7 on an emulator and would like to try building C-Kermit.
  95. There is no support for V6 but that is only because no V6 system was
  96. ever found for development. Notice that some other 16-bit Unixes are
  97. supported in the code, including 2.9BSD and Tandy Xenix 3.0, but have
  98. not been tried since C-Kermit 6.0
  99. ** C-Kermit 9.0.300 was built successfully on 4.2BSD about 25 years
  100. later, in June 2011.
  101. 2. FILES
  102. C-Kermit source files begin with the two letters "ck", for example
  103. ckutio.c. Filenames are kept short (6.3) for maximum portability and
  104. (obviously I hope) do not contain spaces or more than one period. The
  105. third character in the name denotes something about the function group
  106. and the expected level of portability:
  107. a General descriptive material and documentation (text)
  108. b BOO file encoders and decoders (obsolete)
  109. c All platforms with C compilers (*)
  110. d Data General AOS/VS
  111. e Reserved for "ckermit" files, like ckermit.ini, ckermit2.txt
  112. f (reserved)
  113. g (reserved)
  114. h (reserved)
  115. i Commodore Amiga (Intuition)
  116. j (unused)
  117. k (unused)
  118. l Stratus VOS
  119. m Macintosh with Mac OS 1-9
  120. n (unused)
  121. o OS/2 and Microsoft Windows 9x/ME/NT/2000/XP/Vista/etc
  122. p Plan 9 from Bell Labs
  123. q (reserved)
  124. r DEC PDP-11 with RSTS/E (never used, open for reassignment)
  125. s Atari ST GEMDOS (last supported in version 5A(189))
  126. t DEC PDP-11 with RT-11 (never used, open for reassignment)
  127. u Unix-based operating systems (*)
  128. v VMS and OpenVMS
  129. w Wart (Lex-like preprocessor, platform independent)
  130. x (reserved)
  131. y (reserved)
  132. z (reserved)
  133. 0-3 (reserved)
  134. 4 IBM AS/400
  135. 5-8 (reserved)
  136. 9 Microware OS-9
  137. _ (underscore) Encryption modules
  138. (*) In fact there is little distinction between the ckc*.* and cku*.*
  139. categories. It would make more sense for all cku*.* modules to be
  140. ckc*.* ones, except ckufio.c, ckutio.c, ckucon.c, ckucns.c, and
  141. ckupty.c, which truly are specific to Unix. The rest (ckuus*.c,
  142. ckucmd.c, etc) are quite portable.
  143. One hint before proceeding: functions are scattered all over the ckc*.c
  144. and cku*.c modules, where function size has begun to take precedence
  145. over the desirability of grouping related functions together, the aim
  146. being to keep any particular module from growing disproportionately
  147. large. The easiest way (in UNIX) to find out in what source file a
  148. given function is defined is like this (where the desired function is
  149. foo()...):
  150. grep ^foo\( ck*.c
  151. This works because the coding convention has been to make function
  152. names always start on the left margin with their contents indented, for
  153. example:
  154. static char *
  155. foo(x,y) int x, y; {
  156. ...
  157. }
  158. Also note the style for bracket placement. This allows bracket-matching
  159. text editors (such as EMACS) to help you make sure you know which
  160. opening bracket a closing bracket matches, particularly when the
  161. opening bracket is above the visible screen, and it also makes it easy
  162. to find the end of a function (search for '}' on the left margin).
  163. Of course EMACS tags work nicely with this format too:
  164. $ cd kermit-source-directory
  165. $ etags ck[cu]*.c
  166. $ emacs
  167. Esc-X Visit-Tags-Table<CR><CR>
  168. (but remember that the source file for ckcpro.c is ckcpro.w!)
  169. Also:
  170. * Tabs should be set every 8 spaces, as on a VT100.
  171. * All lines must no more than 79 characters wide after tab expansion.
  172. * Note the distinction between physical tabs (ASCII 9) and the
  173. indentation conventions, which are: 4 for block contents, 2 for
  174. most other stuff (obviously this is not a portability issue, just
  175. style).
  176. 3. SOURCE CODE PORTABILITY AND STYLE
  177. C-Kermit was designed in 1985 as a platform-independent replacement for
  178. the earlier Unix Kermit. C-Kermit's design was expected to promote
  179. portability, and judging from the number of platforms to which it has
  180. been adapted since then, the model is effective, if not ideal
  181. (obviously if we had it all to do over, we'd change a few things). To
  182. answer the oft-repeated question: "Why are there so many #ifdefs?",
  183. it's because:
  184. * Many of them are related to feature selection and program size, and
  185. so need to be there anyway.
  186. * Those that treat compiler, library, platform, header-file, and
  187. similar differences have built up over time as hundreds of people
  188. all over the world adapted C-Kermit to their particular
  189. environments and sent back their changes. There might be more
  190. politically-correct ways to achieve portability, but this one is
  191. natural and proven. The basic idea is to introduce changes that can
  192. be selected by defining a symbol, which, if not defined, leaves the
  193. program exactly as it was before the changes.
  194. * Although it might be possible to "clean up" the "#ifdef mess",
  195. nobody has access to all the hundreds of platforms served by the
  196. #ifdefs to check the results.
  197. And to answer the second-most-oft-repeated question: "Why don't you
  198. just use GNU autoconfig / automake / autowhatever instead of
  199. hard-coding all those #ifdefs?" Answers:
  200. * The GNU tools are not available on all the platforms where C-Kermit
  201. must be built and I wouldn't necessarily trust them if they were.
  202. * Each platform is a moving target, so the tools themselves would
  203. need to updated before Kermit could be updated.
  204. * It would only add another layer of complexity to an already complex
  205. process.
  206. * Conversion at this point would not be practical unless there was a
  207. way to test the results on all the hundreds of platforms where
  208. C-Kermit is supposed to build.
  209. When writing code for the system-independent C-Kermit modules, please
  210. stick to the following coding conventions to ensure portability to the
  211. widest possible variety of C preprocessors, compilers, and linkers, as
  212. well as certain network and/or email transports. The same holds true
  213. for many of the "system dependent" modules too; particularly the Unix
  214. ones, since they must be buildable by a wide variety of compilers and
  215. linkers, new and old.
  216. This list does not purport to be comprehensive, and although some items
  217. on it might seem far-fetched, they would not be listed unless I had
  218. encountered them somewhere, some time. I wish I had kept better records
  219. so I could cite specific platforms and compilers.
  220. * Try to keep variable and function names unique within 6 characters,
  221. especially if they are used across modules, since 6 is the maximum
  222. for some old linkers (actually, this goes back to TOPS-10 and -20
  223. and other old DEC OS's where C-Kermit never ran anyway; a more
  224. realistic maximum is probably somewhere between 8 and 16). We know
  225. for certain that VAX C has a 31-character max because it complains
  226. -- others might not complain, but just silently truncate, thus
  227. folding two or more routines/variables into one.
  228. * Keep preprocessor symbols unique within 8 characters; that's the
  229. max for some preprocessors (sorry, I can't give a specific example,
  230. but in 1988 or thereabouts, I had to change character-set symbols
  231. like TC_LATIN1 and TC_LATIN2 to TC_1LATIN and TC_2LATIN because the
  232. digits were being truncated and ignored on a platform where I
  233. actually had to build C-Kermit 5A; unfortunately I didn't note
  234. which platform -- maybe some early Ultrix version?)
  235. * Don't create preprocessor symbols, or variable or function names,
  236. that start with underscore (_). These are usually reserved for
  237. internal use by the compiler and header files.
  238. * Don't put #include directives inside functions or { blocks }.
  239. * Don't use the #if or #elif preprocessor constructions, only use
  240. #ifdef, #ifndef, #define, #undef, and #endif.
  241. * Put tokens after #endif in comment brackets, e.g. #endif /* FOO */.
  242. * Don't indent preprocessor statements - # must always be first char
  243. on line.
  244. * Don't put whitespace after # in preprocessor statements.
  245. * Don't use #pragma, even within #ifdefs -- it makes some
  246. preprocessors give up.
  247. * Same goes for #module, #if, etc - #ifdefs do NOT protect them.
  248. * Don't use logical operators in preprocessor constructions.
  249. * Avoid #ifdefs inside argument list to function calls (I can't
  250. remember why this one is here, but probably needn't be; we do this
  251. all the time).
  252. * Always cast strlen() in expressions to int:
  253. if ((int)strlen(foo) < x)...
  254. * Avoid typedefs; they might be portable but they are very confusing
  255. and there's no way to test for their presence or absence at compile
  256. time. Use preprocessor symbols instead if possible; at least you
  257. can test their definitions.
  258. * Unsigned long is not portable; use a preprocessor symbol (Kermit
  259. uses ULONG for this).
  260. * Long long is not portable. If you really need it, be creative.
  261. * Similarly 1234LL is not portable, nor almost any other constant
  262. modifier other than L.
  263. * Unsigned char is not portable, use CHAR (a preprocessor symbol
  264. defined in the Kermit header files) and always take precautions
  265. against character signage (more about this below).
  266. * Don't use initializers with automatic arrays or structs: it's not
  267. portable.
  268. * Don't use big automatic arrays or structs in functions that might
  269. be called recursively; some platforms have fixed-size stacks (e.g.
  270. Windows 9x: 256K) and recursive functions crash with stack
  271. overflow. Even when there is not a compiler limitation, this causes
  272. memory to be consumed without bound, and can end up filling swap
  273. space.
  274. * Don't assume that struct assignment performs a copy, or that it
  275. even exists.
  276. * Don't use sizeof to get the size of an array; someone might come
  277. along later and and change it from static to malloc'd. Always use a
  278. symbol to refer to the array's size.
  279. * Don't put prototypes for static functions into header files that
  280. are used by modules that don't contain that function; the link step
  281. can fail with unresolved references (e.g. on AOS/VS).
  282. * Avoid the construction *++p (the order of evaluation varies; it
  283. shouldn't but at least one compiler had a bug that made me include
  284. this item).
  285. * Don't use triple assignments, like a = b = c = 0; (or quadruple,
  286. etc). Some compilers generate bad code for these, or crash, etc
  287. (some version of DEC C as I recall).
  288. * Some compilers don't allow structure members to have the same names
  289. as other identifiers. Try to give structure members unique names.
  290. * Don't assume anything about order of evaluation in boolean
  291. expressions, or that they will stop early if a required condition
  292. is not true, e.g.:
  293. if (i > 0 && p[i-1] == blah)
  294. can still dump core if i == 0 (hopefully this is not true of any
  295. modern compiler, but I would not have said this if it did not
  296. actually happen somewhere).
  297. * Don't have a switch() statement with no cases (e.g. because of
  298. #ifdefs); this is a fatal error in some compilers.
  299. * Don't put lots of code in a switch case; move it out to a separate
  300. function; some compilers run out of memory when presented with a
  301. huge switch() statement -- it's not the number of cases that
  302. matters; it's the overall amount of code.
  303. * Some compilers might also limit the number of switch() cases, e.g.
  304. to 254.
  305. * Don't put anything between "switch() {" and "case:" -- switch
  306. blocks are not like other blocks.
  307. * Don't jump into or out of switches.
  308. * Don't make character-string constants longer than about 250 bytes.
  309. Longer strings should be broken up into arrays of strings.
  310. * Don't write into character-string constants (obviously). Even when
  311. you know you are not writing past the end; the compiler or linker
  312. might have put them into read-only and/or shared memory, and/or
  313. coalesced multiple equal constants so if you change one you change
  314. them all.
  315. * Don't depend on '\r' being carriage return.
  316. * Don't depend on '\n' being linefeed or for that matter any SINGLE
  317. character.
  318. * Don't depend on '\r' and '\n' being different (e.g. as separate
  319. switch() cases).
  320. * In other words, don't use \n or \r to stand for specific
  321. characters; use \012 and \015 instead.
  322. * Don't code for "buzzword 1.0 compliance", unless "buzzword" is K&R
  323. and "1.0" is the first edition.
  324. * Don't use or depend on anything_t (size_t, pid_t, etc), except
  325. time_t, without #ifdef protection (time_t is the only one I've
  326. found that is accepted everywhere). This is a tough one because the
  327. same function might require (say) a size_t arg on one platform,
  328. whereas size_t is unheard of on another; or worse, it might require
  329. a totally different data type, like int or long or some other
  330. typedef'd thing. It has often proved necessary to define a symbol
  331. to stand for the type of a particular argument to a particular
  332. library or system function to get around this problem.
  333. * Don't use or depend on internationalization ("i18n") features,
  334. wchar_t, locales, etc, in portable code; they are not portable.
  335. Anyway, locales are not the right model for Kermit's
  336. multi-character-set support. Kermit does all character-set
  337. conversion itself and does not use any external libraries or
  338. functions.
  339. * In particular, don't use any library functions that deal with wide
  340. characters or Unicode in any form. These are not only nonportable,
  341. but a constantly shifting target (e.g. the ones in glibc).
  342. * Don't make any assumption about signal handler type. It can be
  343. void, int, long, or anything else. Always declare signal handlers
  344. as SIGTYP (see definition in ckcdeb.h and augment it if necessary)
  345. and always use SIGRETURN at exit points from signal handlers.
  346. * Signals should always be re-armed to be used again (this barely
  347. scratches the surface -- the differences between BSD/V7 and System
  348. V and POSIX signal handling are numerous, and some platforms do not
  349. even support signals, alarms, or longjmps correctly or at all --
  350. avoid all of this if you can).
  351. * On the other hand, don't assume that signals are disarmed after
  352. being raised. In some platforms you have to re-arm them, in others
  353. they stay armed.
  354. * Don't call malloc() and friends from a signal handler; don't do
  355. anything but setting integer global variables in a signal handler.
  356. * malloc() does not initialize allocated memory -- it never said it
  357. did. Don't expect it to be all 0's.
  358. * Did You Know: malloc() can succeed and the program can still dump
  359. core later when it attempts to use the malloc'd memory? (This
  360. happens when allocation is deferred until use and swap space is
  361. full.)
  362. * memset(), memmove(), and memcpy() are not portable, don't use them
  363. without protecting them in ifdefs (we have USE_MEMCPY for this).
  364. bzero()/bcopy() too, except we're guaranteed to have
  365. bzero()/bcopy() when using the sockets library (not really). See
  366. examples in the source.
  367. * Don't assume that strncpy() stops on the first null byte -- most
  368. versions always copy the number of bytes given in arg 3, padding
  369. out with 0's and overwriting whatever was there before. Use
  370. C-Kermit ckstrncpy() if you want predictable non-padding behavior,
  371. guaranteed NUL-termination, and a useful return code.
  372. * DID YOU KNOW.. that some versions of inet_blah() routines return IP
  373. addresses in network byte order, while others return them local
  374. machine byte order? So passing them to ntohs() or whatever is not
  375. always the right thing to do.
  376. * Don't use ANSI-format function declarations without #ifdef
  377. CK_ANSIC, and always provide an #else for the non-ANSI case.
  378. * Use the Kermit _PROTOTYP() macro for declaring function prototypes;
  379. it works in both the ANSI and non-ANSI cases.
  380. * Don't depend on any other ANSI preprocessor features like "pasting"
  381. -- they are often missing or nonoperational.
  382. * Don't assume any C++ syntax or semantics.
  383. * Don't use // as a comment introducer. C is not C++.
  384. * Don't declare a string as "char foo[]" in one module and "extern
  385. char * foo" in another, or vice-versa: this causes core dumps.
  386. * With compiler makers falling all over themselves trying to outdo
  387. each other in ANSI strictness, it has become increasingly necessary
  388. to cast EVERYTHING. Especially char vs unsigned char. We need to
  389. use unsigned chars if we want to deal with 8-bit character sets,
  390. but most character- and string-oriented APIs want (signed) char
  391. arguments, so explicit casts are necessary. It would be nice if
  392. every compiler had a -funsigned-char option (as gcc does), but they
  393. don't.
  394. * a[x], where x is an unsigned char, can produce a wild memory
  395. reference if x, when promoted to an int, becomes negative. Cast it
  396. to (unsigned), even though it ALREADY IS unsigned.
  397. * Be careful how you declare functions that have char or long
  398. arguments; for ANSI compilers you MUST use ANSI declarations to
  399. avoid promotion problems, but you can't use ANSI declarations with
  400. non-ANSI compilers. Thus declarations of such functions must be
  401. hideously entwined in #ifdefs. Example:
  402. int /* Put character in server command buffer */
  403. #ifdef CK_ANSIC
  404. putsrv(char c)
  405. #else
  406. putsrv(c) char c;
  407. #endif /* CK_ANSIC */
  408. /* putsrv */ {
  409. *srvptr++ = c;
  410. *srvptr = '\0'; /* Make sure buffer is null-terminated */
  411. return(0);
  412. }
  413. * Be careful how you return characters from functions that return int
  414. values -- "getc-like functions" -- in the ANSI world. Unless you
  415. explicitly cast the return value to (unsigned), it is likely to be
  416. "promoted" to an int and have its sign extended.
  417. * At least one compiler (the one on DEC OSF/1 1.3) treats "/*" and
  418. "*/" within string constants as comment begin and end. No amount of
  419. #ifdefs will get around this one. You simply can't put these
  420. sequences in a string constant, e.g. "/usr/local/doc/*.*".
  421. * Avoid putting multiple macro references on a single line, e.g.:
  422. putchar(BS); putchar(SP); putchar(BS)
  423. This overflows the CPP output buffer of more than a few C preprocessors
  424. (this happened, for example, with SunOS 4.1 cc, which evidently has a
  425. 1K macro expansion buffer).
  426. C-Kermit needs constant adjustment to new OS and compiler releases.
  427. Every new OS release shuffles header files or their contents, or
  428. prototypes, or data types, or levels of ANSI strictness, etc. Every
  429. time you make an adjustment to remove a new compilation error, BE VERY
  430. CAREFUL to #ifdef it on a symbol unique to the new configuration so
  431. that the previous configuration (and all other configurations on all
  432. other platforms) remain as before.
  433. Assume nothing. Don't assume header files are where they are supposed
  434. to be, that they contain what you think they contain, that they define
  435. specific symbols to have certain values -- or define them at all! Don't
  436. assume system header files protect themselves against multiple
  437. inclusion. Don't assume that particular system or library calls are
  438. available, or that the arguments are what you think they are -- order,
  439. data type, passed by reference vs value, etc. Be conservative when
  440. attempting to write portable code. Avoid all advanced features.
  441. If you see something that does not make sense, don't assume it's a
  442. mistake -- it might be there for a reason, and changing it or removing
  443. is likely to cause compilation, linking, or runtime failures sometime,
  444. somewhere. Some huge percentage of the code, especially in the
  445. platform-dependent modules, is workarounds for compiler, linker, or API
  446. bugs.
  447. But finally... feel free to violate any or all of these rules in
  448. platform-specific modules for environments in which the rules are
  449. certain not to apply. For example, in VMS-specific code, it is OK to
  450. use #if, because VAX C, DEC C, and VMS GCC all support it.
  451. 3.1. Memory Leaks
  452. The C language and standard C library are notoriously inadequate and
  453. unsafe. Strings are arrays of characters, usually referenced through
  454. pointers. There is no native string datatype. Buffers are fixed size,
  455. and C provides no runtime bounds checking, thus allowing overwriting of
  456. other data or even program code. With the popularization of the
  457. Internet, the "buffer exploit" has become a preferred method for
  458. hackers to hijack privileged programs; long data strings are fed to a
  459. program in hopes that it uses unsafe C library calls such as strcpy()
  460. or sprintf() to copy strings into automatic arrays, thus overwriting
  461. the call stack, and therefore the routine's return address. When such a
  462. hole is discovered, a "string" can be constructed that contains machine
  463. code to hijack the program's privileges and penetrate the system.
  464. This problem is partially addressed by the strn...() routines, which
  465. should always be used in preference to their str...() equivalents
  466. (except when the copy operation has already been prechecked, or there
  467. is a good reason for not using them, e.g. the sometimes undesirable
  468. side effect of strncpy() zeroing the remainder of the buffer). The most
  469. gaping whole, however, is sprintf(), which performs no length checking
  470. on its destination buffer, and is not easy to replace. Although
  471. snprintf() routines are starting to appear, they are not yet
  472. widespread, and certainly not universal, nor are they especially
  473. portable, or even full-featured.
  474. For these reasons, we have started to build up our own little library
  475. of C Library replacements, ckclib.[ch]. These are safe and highly
  476. portable primitives for memory management and string manipulation, such
  477. as:
  478. ckstrncpy()
  479. Like strncpy but returns a useful value, doesn't zero buffer.
  480. ckitoa()
  481. Opposite of atoi()
  482. ckltoa()
  483. Opposite of atol()
  484. ckctoa()
  485. Returns character as string
  486. ckmakmsg()
  487. Used with ck?to?() as a safe sprintf() replacement for up to 4
  488. items
  489. ckmakxmsg()
  490. Like ckmakmsg() but accepts up to 12 items
  491. More about library functions in Section 4.A.
  492. 3.2. The "char" vs "unsigned char" Dilemma
  493. This is one of the most aggravating and vexing characteristics of the C
  494. language. By design, chars (and char *'s) are SIGNED. But in the modern
  495. era, however, we need to process characters that can have (or include)
  496. 8-bit values, as in the ISO Latin-1, IBM CP 850, or UTF-8 character
  497. sets, so this data must be treated as unsigned. But some C compilers
  498. (such as those based on the Bell UNIX V7 compiler) do not support
  499. "unsigned char" as a data type. Therefore we have the macro or typedef
  500. CHAR, which we use when we need chars to be unsigned, but which,
  501. unfortunately, resolves itself to "char" on those compilers that don't
  502. support "unsigned char". AND SO... We have to do a lot of fiddling at
  503. runtime to avoid sign extension and so forth.
  504. Some modern compilers (e.g. IBM, DEC, Microsoft) have options that say
  505. "make all chars be unsigned" (e.g. GCC "-funsigned-char") and we use
  506. them when they are available. Other compilers don't have this option,
  507. and at the same time, are becoming increasingly strict about type
  508. mismatches, and spew out torrents of warnings when we use a CHAR where
  509. a char is expected, or vice versa. We fix these one by one using casts,
  510. and the code becomes increasingly ugly. But there remains a serious
  511. problem, namely that certain library and kernel functions have
  512. arguments that are declared as signed chars (or pointers to them),
  513. whereas our character data is unsigned. Fine, we can can use casts here
  514. too -- but who knows what happens inside these routines.
  515. 4. MODULES
  516. When C-Kermit is on the far end of a connection, it is said to be in
  517. remote mode. When C-Kermit has made a connection to another computer,
  518. it is in local mode. (If C-Kermit is "in the middle" of a multihop
  519. connection, it is still in local mode.)
  520. On another axis, C-Kermit can be in any of several major states:
  521. Command State
  522. Reading and writing from the job's controlling terminal or
  523. "console". In this mode, all i/o is handled by the Group E
  524. conxxx() (console i/o) routines.
  525. Protocol State
  526. Reading and writing from the communications device. In this
  527. mode, all i/o is handled by the Group E ttxxx() (terminal i/o)
  528. routines.
  529. Terminal State
  530. Reading from the keyboard with conxxx() routines and writing to
  531. the communications device with ttxxx() routines AND vice-versa.
  532. When in local mode, the console and communications device are distinct.
  533. During file transfer, Kermit may put up a file-transfer display on the
  534. console and sample the console for interruption signals.
  535. When in remote mode, the console and communications device are the
  536. same, and therefore there can be no file-transfer display on the
  537. console or interruptions from it (except for "in-band" interruptions
  538. such as ^C^C^C).
  539. 4.A. Group A: Library Functions
  540. Library functions, strictly portable, can be used by all modules on all
  541. platforms: ckclib.h, ckclib.c.
  542. (To be filled in... For now, see Section 3.1 and the comments in
  543. ckclib.c.)
  544. 4.B. Group B: Kermit File Transfer
  545. The Kermit protocol kernel. These files, whose names start with "ckc
  546. are supposed to be totally portable C, and are expected to compile
  547. correctly on any platform with any C compiler. "Portable" does not mean
  548. the same as as "ANSI" -- these modules must compile on 10- and 20-year
  549. old computers, with C preprocessors, compilers, and/or linkers that
  550. have all sorts of restrictions. The Group B modules do not include any
  551. header files other than those that come with Kermit itself. They do not
  552. contain any library calls except from the standard C library (e.g.
  553. printf()). They most certainly do not contain any system calls. Files:
  554. ckcsym.h
  555. For use by C compilers that don't allow -D on the command line.
  556. ckcasc.h
  557. ASCII character symbol definitions.
  558. ckcsig.h
  559. System-independent signal-handling definitions and prototypes.
  560. ckcdeb.h
  561. Originally, debugging definitions. Now this file also contains
  562. all definitions and prototypes that are shared by all modules in
  563. all groups.
  564. ckcker.h
  565. Kermit protocol symbol definitions.
  566. ckcxla.h
  567. Character-set-related symbol definitions (see next section).
  568. ckcmai.c
  569. The main program. This module contains the declarations of all
  570. the protocol-related global variables that are shared among the
  571. other modules.
  572. ckcpro.w
  573. The protocol module itself, written in "wart", a lex-like
  574. preprocessor that is distributed with Kermit under the name
  575. CKWART.C.
  576. ckcfns.c, ckcfn2.c, ckcfn3.c
  577. The protocol support functions used by the protocol module.
  578. Group B modules may call upon functions from Group E, but not
  579. from Group D modules (with the single exception that the main
  580. program invokes the user interface, which is in Group D). (This last
  581. assertion is really only a conjecture.)
  582. 4.C. Group C: Character-Set Conversion
  583. Character set translation tables and functions. Used by the Group
  584. B, protocol modules, but may be specific to different computers. (So
  585. far, all character character sets supported by C-Kermit are supported
  586. in ckuxla.c and ckuxla.h, including Macintosh and IBM character
  587. sets). These modules should be completely portable, and not rely on any
  588. kind of system or library services.
  589. ckcxla.h
  590. Character-set definitions usable by all versions of C-Kermit.
  591. ck?xla.h
  592. Character-set definitions for computer "?", e.g. ckuxla.h
  593. for UNIX, ckmxla.h for Macintosh.
  594. ck?xla
  595. Character-set translation tables and functions for computer "?",
  596. For example, CKUXLA.C for UNIX, CKMXLA.C for Macintosh. So far,
  597. these are the only two such modules. The UNIX module is used for
  598. all versions of C-Kermit except the Macintosh version.
  599. ckcuni.h
  600. Unicode definitions
  601. ckcuni.c
  602. Unicode module
  603. Here's how to add a new file character set in the original (non-Unicode
  604. modules). Assuming it is based on the Roman (Latin) alphabet. Let's
  605. call it "Barbarian". First, in ck?xla.h, add a definition for FC_BARBA
  606. (8 chars maximum length) and increase MAXFCSETS by 1. Then, in
  607. ck?xla.c:
  608. * Add a barbarian entry into the fcsinfo array.
  609. * Add a "barbarian" entry to file character set keyword table,
  610. fcstab.
  611. * Add a "barbarian" entry to terminal character set keyword table,
  612. ttcstab.
  613. * Add a translation table from Latin-1 to barbarian: yl1ba[].
  614. * Add a translation table from barbarian to Latin-1: ybal1[].
  615. * Add a translation function from Barbarian to ASCII: xbaas().
  616. * Add a translation function from Barbarian to Latin-1: xbal1().
  617. * Add a translation function from Latin-1 to Barbarian: xl1ba().
  618. * etc etc for each transfer character set...
  619. * Add translation function pointers to the xls and xlr tables.
  620. Other translations involving Barbarian (e.g. from Barbarian to
  621. Latin-Cyrillic) are performed through these tables and functions. See
  622. ckuxla.h and ckuxla.c for extensive examples.
  623. To add a new Transfer Character Set, e.g. Latin Alphabet 9 (for the
  624. Euro symbol), again in the "old" character-set modules:
  625. In ckcxla.h:
  626. + Add a TC_xxxx definition and increase MAXTCSETS accordingly.
  627. In ck?xla.h (since any transfer charset is also a file charset):
  628. + Add an FC_xxxx definition and increase MAXFCSETS accordingly.
  629. In ck?xla.c:
  630. + Add a tcsinfo[] entry.
  631. + Make a tcstab[] keyword table entry.
  632. + Make an fcsinfo[] table entry.
  633. + Make an fcstab[] keyword table entry.
  634. + Make a tcstab[] keyword table entry.
  635. + If necessary, make a langinfo[] table entry.
  636. + Make entries in the function pointer arrays.
  637. + Provide any needed functions.
  638. As of C-Kermit 7.0, character sets are also handled in parallel by the
  639. new (and very large) Unicode module, ckcuni.[ch]. Eventually we should
  640. phase out the old way, described just above, and operate entirely in
  641. (and through) Unicode. The advantages are many. The disadvantages are
  642. size and performance. To add a character to the Unicode modules:
  643. In ckcuni.h:
  644. + (To be filled in...)
  645. In ckcuni.c:
  646. + (To be filled in...)
  647. 4.D. Group D: User Interface
  648. This is the code that communicates with the user, gets her commands,
  649. informs her of the results. It may be command-line oriented,
  650. interactive prompting dialog, menus and arrow keys, windows and mice,
  651. speech recognition, telepathy, etc. The one provided is command-and
  652. prompt, with the ability to read commands from various sources: the
  653. console keyboard, a file, or a macro definition. The user interface has
  654. three major functions:
  655. 1. Sets the parameters for the file transfer and then starts it. This
  656. is done by setting certain (many) global variables, such as the
  657. protocol machine start state, the file specification, file type,
  658. communication parameters, packet length, window size, character
  659. set, etc.
  660. 2. Displays messages on the user's screen during the file transfer,
  661. using the screen() function, which is called by the group-1
  662. modules.
  663. 3. Executes any commands directly that do not require Kermit protocol,
  664. such as the CONNECT command, local file management commands,
  665. parameter-setting commands, FTP client commands, etc.
  666. If you plan to embed the Group B, files into a program with a
  667. different user interface, your interface must supply an appropriate
  668. screen() function, plus a couple related ones like chkint() and
  669. intmsg() for handling keyboard (or mouse, etc) interruptions during
  670. file transfer. The best way to find out about this is to link all the
  671. C-Kermit modules together except the ckuu*.o and ckucon.o modules, and
  672. see which missing symbols turn up.
  673. C-Kermit's character-oriented user interface (as opposed to the
  674. Macintosh version's graphical user interface) consists of the following
  675. modules. C-Kermit can be built with an interactive command parser, a
  676. command-line-option-only parser, a graphical user interface, or any
  677. combination, and it can even be built with no user interface at all (in
  678. which case it runs as a remote-mode Kermit server).
  679. ckucmd.h
  680. ckucmd.c
  681. The command parsing primitives used by the interactive command
  682. parser to parse keywords, numbers, filenames, etc, and to give
  683. help, complete fields, supply defaults, allow abbreviations and
  684. editing, etc. This package is totally independent of Kermit, but
  685. does depend on the Group E functions.
  686. ckuusr.h
  687. Definitions of symbols used in Kermit's commands.
  688. ckuus*.c
  689. Kermit's interactive command parser, including the script
  690. programming language: ckuusr.c (includes top-level keyword
  691. tables); ckuus2.c (HELP command text); ckuus3.c (most
  692. of the SET command); ckuus4.c (includes variables and
  693. functions); ckuus.c (miscellaneous);
  694. ckuusy.c
  695. The command-line-option parser.
  696. ckuusx.c
  697. User interface functions common to both the interactive and
  698. command-line parsers.
  699. ckuver.h
  700. Version heralds for different implementations.
  701. ckuscr.c
  702. The (old, uucp-like) SCRIPT command
  703. ckudia.c
  704. The DIAL command. Includes specific knowledge of many types of
  705. modems.
  706. Note that none of the above files is actually Unix-specific. Over time
  707. they have proven to be portable among all platforms where C-Kermit is
  708. built: Unix, VMS, AOS/VS, Amiga, OS-9, VOS, etc etc. Thus the third
  709. letter should more properly be "c", but changing it would be too
  710. confusing.
  711. ck?con.c, ckucns.c
  712. The CONNECT command. Terminal connection, and in some cases
  713. (Macintosh, Windows) also terminal emulation. NOTE: As of
  714. C-Kermit 7.0, there are two different CONNECT modules for UNIX:
  715. ckucon.c -- the traditional, portable, fork()-based version
  716. -- and ckucns.c, a new version that uses select() rather
  717. than forks so it can handle encryption. ckucns.c is the
  718. preferred version for Unix; ckucon.c is not likely to keep pace
  719. with it in terms of upgrades, etc. However, since select() is
  720. not portable to every platform, ckucon.c will be kept
  721. indefinitely for those platforms that can't use ckucns.c. NOTE:
  722. SunLink X.25 support is available only in ckucon.c.
  723. ck_*.*, ckuat*.*
  724. Modules having to do with authentication and encryption. Since
  725. the relaxation of USA export laws, they are included with the
  726. general source-code distribution. Secure C-Kermit binaries can
  727. be built using special targets in the standard makefile.
  728. However, secure prebuilt binaries may not be distributed.
  729. For other implementations, the files may, and probably do, have
  730. different names. For example, the Macintosh graphical user interface
  731. filenames start with "ckm". Kermit 95 uses the ckucmd and ckuus*
  732. modules, but has its own CONNECT command modules. And so on.
  733. Here is a brief description of C-Kermit's "user interface interface",
  734. from ckuusr.c. It is nowhere near complete; in particular, hundreds of
  735. global variables are shared among the many modules. These should, some
  736. day, be collected into classes or structures that can be passed around
  737. as needed; not only for purity's sake, but also to allow for multiple
  738. simultaneous communication sessions and or user interfaces. Our list of
  739. things to do is endless, and reorganizing the source is almost always
  740. at the bottom.
  741. The ckuus*.c modules (like many of the ckc*.c modules) depend on the
  742. existence of C library features like fopen, fgets, feof, (f)printf,
  743. argv/argc, etc. Other functions that are likely to vary among operating
  744. systems -- like setting terminal modes or interrupts -- are invoked via
  745. calls to functions that are defined in the Group E
  746. platform-dependent modules, ck?[ft]io.c. The command line parser
  747. processes any arguments found on the command line, as passed to main()
  748. via argv/argc. The interactive parser uses the facilities of the cmd
  749. package (developed for this program, but, in theory, usable by any
  750. program). Any command parser may be substituted for this one. The only
  751. requirements for the Kermit command parser are these:
  752. 1. Set parameters via global variables like duplex, speed, ttname,
  753. etc. See ckcmai.c for the declarations and descriptions of
  754. these variables.
  755. 2. If a command can be executed without the use of Kermit protocol,
  756. then execute the command directly and set the sstate (start state)
  757. variable to 0. Examples include SET commands, local directory
  758. listings, the CONNECT command.
  759. 3. If a command requires the Kermit protocol, set the following
  760. variables:
  761. sstate string data
  762. 'x' (enter server mode) (none)
  763. 'r' (send a 'get' command) cmarg, cmarg2
  764. 'v' (enter receive mode) cmarg2
  765. 'g' (send a generic command) cmarg
  766. 's' (send files) nfils, cmarg & cmarg2 OR cmlist
  767. 'c' (send a remote host command) cmarg
  768. cmlist is an array of pointers to strings.
  769. cmarg, cmarg2 are pointers to strings.
  770. nfils is an integer (hmmm, probably should be an unsigned long).
  771. cmarg can be:
  772. A filename string (possibly wild), or:
  773. a pointer to a prefabricated generic command string, or:
  774. a pointer to a host command string.
  775. cmarg2 is:
  776. The name to send a single file under, or:
  777. the name under which to store an incoming file; must not
  778. be wild.
  779. If it's the name for receiving, a null value means to
  780. store the file under the name it arrives with.
  781. cmlist is:
  782. A list of nonwild filenames, such as passed via argv.
  783. nfils is an integer, interpreted as follows:
  784. -1: filespec (possibly wild) in cmarg, must be expanded
  785. internally.
  786. 0: send from stdin (standard input).
  787. >0: number of files to send, from cmlist.
  788. The screen() function is used to update the screen during file
  789. transfer. The tlog() function writes to a transaction log (if TLOG is
  790. defined). The debug() function writes to a debugging log (if DEBUG is
  791. defined). The intmsg() and chkint() functions provide the user i/o for
  792. interrupting file transfers.
  793. 4.E. Group E: Platform-Dependent I/O
  794. Platform-dependent function definitions. All the Kermit modules,
  795. including the command package, call upon these functions, which are
  796. designed to provide system-independent primitives for controlling and
  797. manipulating devices and files. For Unix, these functions are defined
  798. in the files ckufio.c (files), ckutio.c (communications), and
  799. ckusig.c (signal handling).
  800. For VMS, the files are ckvfio.c, ckvtio.c, and ckusig.c (VMS
  801. can use the same signal handling routines as Unix). It doesn't really
  802. matter what the files are called, except for Kermit distribution
  803. purposes (grouping related files together alphabetically), only that
  804. each function is provided with the name indicated, observes the same
  805. calling and return conventions, and has the same type.
  806. The Group E modules contain both functions and global variables that
  807. are accessed by modules in the other groups. These are now described.
  808. (By the way, I got this list by linking all the C-Kermit modules
  809. together except ckutio and ckufio. These are the symbols that ld
  810. reported as undefined. But that was a long time ago, probably circa
  811. Version 6.)
  812. 4.E.1. Global Variables
  813. char *DELCMD;
  814. Pointer to string containing command for deleting files.
  815. Example: char *DELCMD = "rm -f "; (UNIX)
  816. Example: char *DELCMD = "delete "; (VMS)
  817. Note trailing space. Filename is concatenated to end of this
  818. string. NOTE: DELCMD is used only in versions that do not
  819. provide their own built-in DELETE command.
  820. char *DIRCMD;
  821. Pointer to string containing command for listing files when a
  822. filespec is given.
  823. Example: char *DIRCMD = "/bin/ls -l "; (UNIX)
  824. Example: char *DIRCMD = "directory "; (VMS)
  825. Note trailing space. Filename is concatenated to end of this
  826. string. NOTE: DIRCMD is used only in versions that do not
  827. provide their own built-in DIRECTORY command.
  828. char *DIRCM2;
  829. Pointer to string containing command for listing files when a
  830. filespec is not given. (currently not used, handled in another
  831. way.)
  832. Example: char *DIRCMD2 = "/bin/ls -ld *";
  833. NOTE: DIRCMD2 is used only in versions that do not provide their
  834. own built-in DIRECTORY command.
  835. char *PWDCMD;
  836. Pointer to string containing command to display current
  837. directory.
  838. Example: char *PWDCMD = "pwd ";
  839. NOTE: PWDCMD is used only in versions that do not provide their
  840. own built-in PWD command.
  841. char *SPACMD;
  842. Pointer to command to display free disk space in current
  843. device/directory.
  844. Example: char *SPACMD = "df .";
  845. NOTE: SPACMD is used only in versions that do not provide their
  846. own built-in SPACE command.
  847. char *SPACM2;
  848. Pointer to command to display free disk space in another
  849. device/directory.
  850. Example: char *SPACM2 = "df ";
  851. Note trailing space. Device or directory name is added to this
  852. string. NOTE: SPACMD2 is used only in versions that do not
  853. provide their own built-in SPACE command.
  854. char *TYPCMD;
  855. Pointer to command for displaying the contents of a file.
  856. Example: char *TYPCMD = "cat ";
  857. Note trailing space. Device or directory name is added to this
  858. string. NOTE: TYPCMD is used only in versions that do not
  859. provide their own built-in TYPE command.
  860. char *WHOCMD;
  861. Pointer to command for displaying logged-in users.
  862. Example: char *WHOCMD = "who ";
  863. Note trailing space. Specific user name may be added to this
  864. string.
  865. int backgrd = 0;
  866. Flag for whether program is running in foreground (0) or
  867. background (nonzero). Background operation implies that screen
  868. output should not be done and that all errors should be fatal.
  869. int ckxech;
  870. Flag for who is to echo console typein:
  871. 1: The program (system is not echoing).
  872. 0: The OS, front end, terminal, etc (not this program).
  873. char *ckxsys;
  874. Pointer to string that names the computer and operating system.
  875. Example: char *ckxsys = " NeXT Mach 1.0";
  876. Tells what computer system ckxv applies to. In UNIX Kermit, this
  877. variable is also used to print the program herald, and in the
  878. SHOW VERSION command.
  879. char *ckxv;
  880. Pointer to version/edit info of ck?tio.c module.
  881. Example: char *ckxv = "UNIX Communications Support, 6.0.169, 6
  882. Sep 96";
  883. Used by SHOW VERSION command.
  884. char *ckzsys;
  885. Like ckxsys, but briefer.
  886. Example: char *ckzsys = " 4.3 BSD";
  887. Tells what platform ckzv applies to. Used by the SHOW VERSION
  888. command.
  889. char *ckzv;
  890. Pointer to version/edit info of ck?fio.c module.
  891. Example: char *ckzv = "UNIX File support, 6.0.113, 6 Sep 96";
  892. Used by SHOW VERSION command.
  893. int dfflow;
  894. Default flow control. 0 = none, 1 = Xon/Xoff, ... (see FLO_xxx
  895. symbols in ckcdeb.h)
  896. Set by Group E module. Used by ckcmai.c to initialize flow
  897. control variable.
  898. int dfloc;
  899. Default location. 0 = remote, 1 = local. Set by Group E module.
  900. Used by ckcmai.c to initialize local variable. Used in various
  901. places in the user interface.
  902. int dfprty;
  903. Default parity. 0 = none, 'e' = even, 'o' = odd, 'm' = mark, 's'
  904. = space. Set by Group E module. Used by ckcmai.c to initialize
  905. parity variable.
  906. char *dftty;
  907. Default communication device. Set by Group E module. Used in
  908. many places. This variable should be initialized the symbol
  909. CTTNAM, which is defined in ckcdeb.h, e.g. as "/dev/tty" for
  910. UNIX, "TT:" for VMS, etc. Example: char *dftty = CTTNAM;
  911. char *mtchs[];
  912. Array of string pointers to filenames that matched the most
  913. recent wildcard match, i.e. the most recent call to zxpand().
  914. Used (at least) by command parsing package for partial filename
  915. completion.
  916. int tilde_expand;
  917. Flag for whether to attempt to expand leading tildes in
  918. directory names (used in UNIX only, and then only when the
  919. symbol DTILDE is defined.
  920. int ttnproto;
  921. The protocol being used to communicate over a network device.
  922. Values are defined in ckcnet.h. Example: NP_TELNET is network
  923. protocol "telnet".
  924. int maxnam;
  925. The maximum length for a filename, exclusive of any device or
  926. directory information, in the format of the host operating
  927. system.
  928. int maxpath;
  929. The maximum length for a fully specified filename, including
  930. device designator, directory name, network node name, etc, in
  931. the format of the host operating system, and including all
  932. punctuation.
  933. int ttyfd;
  934. File descriptor of the communication device. -1 if there is no
  935. open or usable connection, including when C-Kermit is in remote
  936. mode. Since this is not implemented everywhere, references to it
  937. are in #ifdef CK_TTYFD..#endif.
  938. 4.E.2. Functions
  939. These are divided into three categories: file-related functions (B.1),
  940. communication functions (B.2), and miscellaneous functions (B.3).
  941. 4.E.2.1. File-Related Functions
  942. In most implementations, these are collected together into a module
  943. called ck?fio.c, where ? = "u" (ckutio.c for Unix), "v"
  944. (ckvtio.c for VMS), etc. To be totally platform-independent,
  945. C-Kermit maintains its own file numbers, and provides the functions
  946. described in this section to deal with the files associated with them.
  947. The file numbers are referred to symbolically, and are defined as
  948. follows in ckcker.h:
  949. #define ZCTERM 0 /* Console terminal */
  950. #define ZSTDIO 1 /* Standard input/output */
  951. #define ZIFILE 2 /* Current input file for SEND command */
  952. #define ZOFILE 3 /* Current output file for RECEIVE command */
  953. #define ZDFILE 4 /* Current debugging log file */
  954. #define ZTFILE 5 /* Current transaction log file */
  955. #define ZPFILE 6 /* Current packet log file */
  956. #define ZSFILE 7 /* Current session log file */
  957. #define ZSYSFN 8 /* Input from a system function (pipe) */
  958. #define ZRFILE 9 /* Local file for READ command */ (NEW)
  959. #define ZWFILE 10 /* Local file for WRITE command */ (NEW)
  960. #define ZMFILE 11 /* Auxiliary file for internal use */ (NEW)
  961. #define ZNFILS 12 /* How many defined file numbers */
  962. In the descriptions below, fn refers to a filename, and n refers to one
  963. of these file numbers. Functions are of type int unless otherwise
  964. noted, and are listed mostly alphabetically.
  965. int
  966. chkfn(n) int n;
  967. Checks the file number n. Returns:
  968. -1: File number n is out of range
  969. 0: n is in range, but file is not open
  970. 1: n in range and file is open
  971. int
  972. iswild(filspec) char *filespec;
  973. Checks if the file specification is "wild", i.e. contains
  974. metacharacters or other notations intended to match multiple
  975. filenames. Returns:
  976. 0: not wild
  977. 1: wild.
  978. int
  979. isdir(string) char *string;
  980. Checks if the string is the name of an existing directory. The
  981. idea is to check whether the string can be "cd'd" to, so in some
  982. cases (e.g. DOS) it might also indicate any file structured
  983. device, such as a disk drive (like A:). Other nonzero returns
  984. indicate system-dependent information; e.g. in VMS
  985. isdir("[.FOO]") returns 1 but isdir("FOO.DIR;1") returns 2 to
  986. indicate the directory-file name is in a format that needs
  987. conversion before it can be combined with a filename. Returns:
  988. 0: not a directory (including any kind of error)
  989. 1: it is an existing directory
  990. char *
  991. zfcdat(name) char *name;
  992. Returns modification (preferably, otherwise creation) date/time
  993. of file whose name is given in the argument string. Return value
  994. is a pointer to a string of the form yyyymmdd hh:mm:ss, for
  995. example 19931231 23:59:59, which represents the local time (no
  996. timezone or daylight savings time finagling required). Returns
  997. the null string ("") on failure. The text pointed to by the
  998. string pointer might be in a static buffer, and so should be
  999. copied to a safe place by the caller before any subsequent calls
  1000. to this function.
  1001. struct zfnfp *
  1002. zfnqfp(fn, buflen, buf) char * fn; int buflen; char * buf;
  1003. Given the filename fn, the corresponding fully qualified,
  1004. absolute filename is placed into the buffer buf, whose length is
  1005. buflen. On failure returns a NULL pointer. On success returns a
  1006. pointer to a struct zfnfp containing pointers to the full
  1007. pathname and to just the filename, and an int giving the length
  1008. of the full pathname. All references to this function in
  1009. mainline code must be protected by #ifdef ZFNQFP..#endif,
  1010. because it is not present in all of the ck*fio.c modules. So if
  1011. you implement this function in a version that did not have it
  1012. before, be sure to add #define ZFNQFP in the appropriate spot in
  1013. ckcdeb.h or in the build-procedure CFLAGS.
  1014. int
  1015. zcmpfn(s1,s2) char * s2, * s2;
  1016. Compares two filenames to see if they refer to the same.
  1017. Internally, the arguments can be converted to fully qualified
  1018. pathnames, e.g. with zfnqfp(), realpath(), or somesuch. In Unix
  1019. or other systems where symbolic links exist, the link should be
  1020. resolved before making the comparison or looking at the inodes.
  1021. Returns:
  1022. 0: Files are not identical.
  1023. 1: Files are identical.
  1024. int
  1025. zfseek(pos) long pos;
  1026. Positions the input pointer on the current input file to the
  1027. given position. The pos argument is 0-based, the offset
  1028. (distance in bytes) from beginning of the file. Needed for
  1029. RESEND, PSEND, and other recovery operations. This function is
  1030. not necessarily possible on all systems, e.g. record-oriented
  1031. systems. It should only be used on binary files (i.e. files we
  1032. are sending in binary mode) and stream-oriented file systems.
  1033. Returns:
  1034. -1: on failure.
  1035. 0: On success.
  1036. int
  1037. zchdir(dirnam) char *dirnam;
  1038. Changes current or default directory to the one given in dirnam.
  1039. Returns:
  1040. 0: On failure.
  1041. 1: on success.
  1042. long
  1043. zchki(fn) char *fn;
  1044. Check to see if file with name fn is a regular, readable,
  1045. existing file, suitable for Kermit to send -- not a directory,
  1046. not a symbolic link, etc. Returns:
  1047. -3: if file exists but is not accessible (e.g. read-protected);
  1048. -2: if file exists but is not of a readable type (e.g. a
  1049. directory);
  1050. -1: on error (e.g. file does not exist, or fn is garbage);
  1051. >=0: (length of file) if file exists and is readable.
  1052. Also see isdir(), zgetfs().
  1053. int
  1054. zchkpid(pid) unsigned long pid;
  1055. Returns:
  1056. 1: If the given process ID (e.g. pid in UNIX) is valid and
  1057. active
  1058. 0: otherwise.
  1059. long
  1060. zgetfs(fn) char *fn;
  1061. Gets the size of the given file, regardless of accessibility.
  1062. Used for directory listings. Unlike zchki(), should return the
  1063. size of any kind of file, even a directory. zgetfs() also should
  1064. serve as a mini "get file info" function that can be used until
  1065. we design a better one, by also setting some global variables:
  1066. int zgfs_link = 1/0 = file is (not) a symbolic link.
  1067. int zgfs_dir = 1/0 = file is (not) a directory.
  1068. char linkname[] = if zgfs_link != 0, name of file link points
  1069. to.
  1070. Returns:
  1071. -1: on error (e.g. file does not exist, or fn is garbage);
  1072. >=0: (length of file) if file exists and is readable.
  1073. int
  1074. zchko(fn) char *fn;
  1075. Checks to see if a file of the given name can be created.
  1076. Returns:
  1077. -1: if file cannot be created, or on any kind of error.
  1078. 0: if file can be created.
  1079. int
  1080. zchkspa(fn,len) char *f; long len;
  1081. Checks to see if there is sufficient space to store the file
  1082. named fn, which is len bytes long. If you can't write a function
  1083. to do this, then just make a dummy that always returns 1; higher
  1084. level code will recover from disk-full errors. The receiving
  1085. Kermit uses this function to refuse an incoming file based on
  1086. its size, via the attribute mechanism. Returns:
  1087. -1: on error.
  1088. 0: if there is not enough space.
  1089. 1: if there is enough space.
  1090. int
  1091. zchin(n,c) int n; int *c;
  1092. Gets a character from file number n, return it in c (call with
  1093. &c). Returns:
  1094. -1: on failure, including EOF.
  1095. 0: on success with character in c.
  1096. int
  1097. zchout(n,c) int n; char c;
  1098. Writes the character c to file number n. Returns:
  1099. -1: on error.
  1100. 0: on success.
  1101. int
  1102. zclose(n) int n;
  1103. Closes file number n. Returns:
  1104. -1: on error.
  1105. 1: on success.
  1106. int
  1107. zdelet(fn) char *name;
  1108. Attempts to delete (remove, erase) the named file. Returns:
  1109. -1: on error.
  1110. 1: if file was deleted successfully.
  1111. char *
  1112. zgperm(char * f)
  1113. Returns a pointer to the system-dependent numeric
  1114. permissions/protection string for file f, or NULL upon failure.
  1115. Used if CK_PERMS is defined.
  1116. char *
  1117. ziperm(char * f)
  1118. Returns a pointer to the system-dependent symbolic
  1119. permissions/protection string for file f, or NULL upon failure.
  1120. Used if CK_PERMS is defined. Example: In UNIX zgperm(f) might
  1121. return "100770", but ziperm() might return "-rwxrwx---". In VMS,
  1122. zgperm() would return a hexadecimal string, but ziperm() would
  1123. return something like "(RWED,RWED,RE,)".
  1124. char *
  1125. zgtdir()
  1126. Returns a pointer to the name of the current directory, folder,
  1127. etc, or a NULL pointer if the current directory cannot be
  1128. determined. If possible, the directory specification should be
  1129. (a) fully specified, e.g. as a complete pathname, and (b) be
  1130. suitable for appending a filename. Thus, for example, Unix
  1131. directory names should end with '/'. VMS directory names should
  1132. look like DEV:[NAME] (rather than, say, NAME.DIR;1).
  1133. char *
  1134. zhome()
  1135. Returns a pointer to a string containing the user's home
  1136. directory, or NULL upon error. Should be formatted like zgtdir()
  1137. (q.v.).
  1138. int
  1139. zinfill()
  1140. Fill buffer from input file. This function is used by the macro
  1141. zminchar(), which is defined in ckcker.h. zminchar() manages its
  1142. own buffer, and calls zinfill() to fill it whenever it becomes
  1143. empty. It is used only for sending files, and reads characters
  1144. only from file number ZIFILE. zinfill() returns -1 upon end of
  1145. file, -2 upon fatal error, and -3 upon timeout (e.g. when
  1146. reading from a pipe); otherwise it returns the first character
  1147. from the buffer it just read.
  1148. int
  1149. zkself()
  1150. Kills the current job, session, process, etc, logs out,
  1151. disappears. Used by the Kermit server when it receives a BYE
  1152. command. On failure, returns -1. On success, does not return at
  1153. all! This function should not be called until all other steps
  1154. have been taken to close files, etc.
  1155. VOID
  1156. zstrip(fn,&fn2) char *fn1, **fn2;
  1157. Strips device and directory, etc, from file specification fn,
  1158. leaving only the filename (including "extension" or "filetype"
  1159. -- the part after the dot). For example DUA0:[PROGRAMS]OOFA.C;3
  1160. becomes OOFA.C, or /usr/fdc/oofa.c becomes oofa.c. Returns a
  1161. pointer to result in fn2.
  1162. int
  1163. zsetperm(char * file, unsigned int code)
  1164. Set permissions of file to given system-dependent code. 0: On
  1165. failure.
  1166. 1: on success.
  1167. int
  1168. zsetroot(char * dir)
  1169. Sets the root for the user's file access, like Unix chroot(),
  1170. but does not require privilege. In Unix, this must be
  1171. implemented entirely by Kermit's own file access routines.
  1172. Returns:
  1173. 1: Success
  1174. -1: Invalid argument
  1175. -2:
  1176. -3: Internal error
  1177. -4: Access to given directory denied
  1178. -5: New root not within old root
  1179. int
  1180. zinroot(char * file)
  1181. If no root is set (zsetroot()), returns 1.
  1182. Otherwise, if given file is in the root, returns 1.
  1183. Otherwise, returns 0.
  1184. VOID
  1185. zltor(fn,fn2) char *fn1, *fn2;
  1186. Local-To-Remote filename translation. OBSOLETE: replaced by
  1187. nzltor() (q.v.). Translates the local filename fn into a format
  1188. suitable for transmission to an arbitrary type of computer, and
  1189. copies the result into the buffer pointed to by fn2. Translation
  1190. may involve (a) stripping the device and/or directory/path name,
  1191. (b) converting lowercase to uppercase, (c) removing spaces and
  1192. strange characters, or converting them to some innocuous
  1193. alphabetic character like X, (d) discarding or converting extra
  1194. periods (there should not be more than one). Does its best.
  1195. Returns no value. name2 is a pointer to a buffer, furnished by
  1196. the caller, into which zltor() writes the resulting name. No
  1197. length checking is done.
  1198. #ifdef NZLTOR
  1199. VOID
  1200. nzltor(fn,fn2,convert,pathnames,max) char *fn1,*fn2; int
  1201. convert,pathnames,max;
  1202. Replaces zltor(). This new version handles pathnames and checks
  1203. length. fn1 and fn2 are as in zltor(). This version is called
  1204. unconditionally for each file, rather than only when filename
  1205. conversion is enabled. Pathnames can have the following values:
  1206. PATH_OFF: Pathname, if any, is to be stripped
  1207. PATH_REL: The relative pathname is to be included
  1208. PATH_ABS: The full pathname is to be included
  1209. After handling pathnames, conversion is done to the result as in
  1210. the zltor() description if convert != 0; if relative or absolute
  1211. pathnames are included, they are converted to UNIX format, i.e.
  1212. with slash (/) as the directory separator. The max parameter
  1213. specifies the maximum size of fn2. If convert > 0, the regular
  1214. conversions are done; if convert < 0, minimal conversions are
  1215. done (we skip uppercasing the letters, we allow more than one
  1216. period, etc; this can be used when we know our partner is UNIX
  1217. or similar).
  1218. #endif /* NZLTOR */
  1219. int
  1220. nzxpand(fn,flags) char *fn; int flags;
  1221. Replaces zxpand(), which is obsolete as of C-Kermit 7.0.
  1222. Call with:
  1223. fn = Pointer to filename or pattern.
  1224. flags = option bits:
  1225. flags & ZX_FILONLY Match regular files
  1226. flags & ZX_DIRONLY Match directories
  1227. flags & ZX_RECURSE Descend through directory tree
  1228. flags & ZX_MATCHDOT Match "dot files"
  1229. flags & ZX_NOBACKUP Don't match "backup files"
  1230. flags & ZX_NOLINKS Don't follow symlinks.
  1231. Returns the number of files that match fn, with data structures
  1232. set up so the first file (if any) will be returned by the next
  1233. znext() call. If ZX_FILONLY and ZX_DIRONLY are both set, or
  1234. neither one is set, files and directories are matched. Notes:
  1235. 1. It is essential that the number returned by nzxpand() reflect
  1236. the actual number of filenames that will be returned by
  1237. znext() calls. In other words:
  1238. for (n = nzxpand(string,flags); n > 0; n--) {
  1239. znext(buf);
  1240. printf("%s\n", buf);
  1241. }
  1242. should print all the file names; no more, no less.
  1243. 2. In UNIX, DOS, OS-9, etc, where directories contain entries for
  1244. themselves (.) and the superior directory (..), these should
  1245. NOT be included in the list under any circumstances, including
  1246. when ZX_MATCHDOT is set.
  1247. 3. Additional option bits might be added in the future, e.g. for
  1248. sorting (sort by date/name/size, reverse/ascending, etc).
  1249. Currently this is done only in higher level code (through a
  1250. hack in which the nzxpand() exports its filename array, which
  1251. is not portable because not all OS's can use this mechanism).
  1252. int
  1253. zmail(addr,fn) char *addr, fn;
  1254. Send the local, existing file fn as e-mail to the address addr.
  1255. Returns:
  1256. 0: on success
  1257. 2: if mail delivered but temp file can't be deleted
  1258. -2: if mail can't be delivered
  1259. int
  1260. zmkdir(path) char *path;
  1261. The path can be a file specification that might contain
  1262. directory information, in which the filename is expected to be
  1263. included, or an unambiguous directory specification (e.g. in
  1264. UNIX it must end with "/"). This routine attempts to create any
  1265. directories in the given path that don't already exist. Returns
  1266. 0 or greater success: no directories needed creation, or else
  1267. all directories that needed creation were created successfully;
  1268. the return code is the number of directories that were created.
  1269. Returns -1 on failure to create any of the needed directories.
  1270. int
  1271. zrmdir(path) char *path;
  1272. Attempts to remove the given directory. Returns 0 on success, -1
  1273. on failure. The detailed semantics are open -- should it fail if
  1274. the directory contains any files or subdirectories, etc. It is
  1275. probably best for this routine to behave in whatever manner is
  1276. customary on the underlying platform; e.g. in UNIX, VMS, DOS,
  1277. etc, where directories can not be removed unless they are empty.
  1278. VOID
  1279. znewn(fn,s) char *fn, **s;
  1280. Transforms the name fn into a filename that is guaranteed to be
  1281. unique. If the file fn does not exist, then the new name is the
  1282. same as fn; Otherwise, it's different. this function does its
  1283. best, returns no value. New name is created in caller's space.
  1284. Call like this: znewn(old,&new);. The second parameter is a
  1285. pointer to the new name. This pointer is set by znewn() to point
  1286. to a static string in its own space, so be sure to the result to
  1287. a safe place before calling this function again.
  1288. int
  1289. znext(fn) char *fn;
  1290. Copies the next file name from a file list created by zxpand()
  1291. into the string pointed to by fn (see zxpand). If no more files,
  1292. then the null string is placed there. Returns 0 if there are no
  1293. more filenames, with 0th element the array pointed to by fn set
  1294. to NUL. If there is a filename, it is stored in the array
  1295. pointed to by fn and a positive number is returned. NOTE: This
  1296. is a change from earlier definitions of this function
  1297. (pre-1999), which returned the number of files remaining; thus 0
  1298. was the return value when returning the final file. However, no
  1299. mainline code ever depended on the return value, so this change
  1300. should be safe.
  1301. int
  1302. zopeni(n,fn) int n; char *fn;
  1303. Opens the file named fn for input as file number n. Returns:
  1304. 0: on failure.
  1305. 1: on success.
  1306. int
  1307. zopeno(n,fn,zz,fcb) int n; char *name; struct zattr *zz; struct
  1308. filinfo *fcb;
  1309. Attempts to open the named file for output as file number n. zz
  1310. is a Kermit file attribute structure as defined in ckcdeb.h,
  1311. containing various information about the file, including its
  1312. size, creation date, and so forth. This function should attempt
  1313. to honor as many of these as possible. fcb is a "file control
  1314. block" in the traditional sense, defined in ckcdeb.h, containing
  1315. information relevant to complicated file systems like VMS (RMS),
  1316. IBM MVS, etc, like blocksize, record length, organization,
  1317. record format, carriage control, etc. Returns:
  1318. 0: on failure.
  1319. 1: on success.
  1320. int
  1321. zoutdump()
  1322. Dumps a file output buffer. Used with the macro zmchout()
  1323. defined in ckcker.h. Used only with file number ZOFILE, i.e. the
  1324. file that is being received by Kermit during file transfer.
  1325. Returns:
  1326. -1: on failure.
  1327. 0: on success.
  1328. int
  1329. zprint(p,fn) char *p, *f;
  1330. Prints the file with name fn on a local printer, with options p.
  1331. Returns:
  1332. 0: on success
  1333. 3: if file sent to printer but can't be deleted
  1334. -3: if file can't be printed
  1335. int
  1336. zrename(fn,fn2) char *fn, *fn2;
  1337. Changes the name of file fn to fn2. If fn2 is the name of an
  1338. existing directory, or a file-structured device, then file fn is
  1339. moved to that directory or device, keeping its original name. If
  1340. fn2 lacks a directory separator when passed to this function, an
  1341. appropriate one is supplied. Returns:
  1342. -1: on failure.
  1343. 0: on success.
  1344. int
  1345. zcopy(source,dest) char * source, * dest;
  1346. Copies the source file to the destination. One file only. No
  1347. wildcards. The destination string may be a filename or a
  1348. directory name. Returns:
  1349. 0: on success.
  1350. <0: on failure:
  1351. -2: source file is not a regular file.
  1352. -3: source file not found.
  1353. -4: permission denied.
  1354. -5: source and destination are the same file.
  1355. -6: i/o error.
  1356. -1: other error.
  1357. char *
  1358. zlocaltime(char *)
  1359. Call with: "yyyymmdd hh:mm:ss" GMT/UTC date-time. Returns
  1360. pointer to local date-time string "yyyymmdd hh:mm:ss" on
  1361. success, NULL on failure.
  1362. VOID
  1363. zrtol(fn,fn2) char *fn, *fn2;
  1364. Remote-To-Local filename translation. OBSOLETE: replaced by
  1365. nzrtol(). Translates a "standard" filename to a local filename.
  1366. For example, in Unix this function might convert an
  1367. all-uppercase name to lowercase, but leave lower- or mix-case
  1368. names alone. Does its best, returns no value. New name is in
  1369. string pointed to by fn2. No length checking is done.
  1370. #ifdef NZLTOR
  1371. int
  1372. nzrtol(fn,fn2,convert,pathnames,max) char *fn1,*fn2; int
  1373. convert,pathnames,max;
  1374. Replaces zrtol. Like zrtol but handles pathnames and checks
  1375. length. See nzltor for detailed description of parameters.
  1376. #endif /* NZLTOR */
  1377. int
  1378. zsattr(xx) struct zattr *xx;
  1379. Fills in a Kermit file attribute structure for the file which is
  1380. to be sent, namely the currently open ZIFILE. Note that this is
  1381. not a very good design, but we're stuck with it. Callers must
  1382. ensure that zsattr() is called only on real files, not on pipes,
  1383. internally generated file-like objects such as server REMOTE
  1384. command responses, etc. Returns:
  1385. -1: on failure.
  1386. 0: on success with the structure filled in.
  1387. If any string member is null, it should be ignored by the
  1388. caller.
  1389. If any numeric member is -1, it should be ignored by the caller.
  1390. int
  1391. zshcmd(s) char *s;
  1392. s contains to pointer to a command to be executed by the host
  1393. computer's shell, command parser, or operating system. If the
  1394. system allows the user to choose from a variety of command
  1395. processors (shells), then this function should employ the user's
  1396. preferred shell. If possible, the user's job (environment,
  1397. process, etc) should be set up to catch keyboard interruption
  1398. signals to allow the user to halt the system command and return
  1399. to Kermit. The command must run in ordinary, unprivileged user
  1400. mode. If possible, this function should return -1 on failure to
  1401. start the command, or else it should return 1 if the command
  1402. succeeded and 0 if it failed.
  1403. int
  1404. pexitstatus
  1405. zshcmd() and zsyscmd() should set this to the command's actual
  1406. exit status code if possible.
  1407. int
  1408. zsyscmd(s) char *s;
  1409. s contains to pointer to a command to be executed by the host
  1410. computer's shell, command parser, or operating system. If the
  1411. system allows the user to choose from a variety of command
  1412. processors (shells), then this function should employ the system
  1413. standard shell (e.g. /bin/sh for Unix), so that the results will
  1414. always be the same for everybody. If possible, the user's job
  1415. (environment, process, etc) should be set up to catch keyboard
  1416. interruption signals to allow the user to halt the system
  1417. command and return to Kermit. The command must run in ordinary,
  1418. unprivileged user mode. If possible, this function should return
  1419. -1 on failure to start the command, or else it should return 1
  1420. if the command succeeded and 0 if it failed.
  1421. VOID
  1422. z_exec(s,args) char * s; char * args[];
  1423. This one executes the command s (which is searched for using the
  1424. system's normal searching mechanism, such as PATH in UNIX), with
  1425. the given argument vector, which follows the conventions of UNIX
  1426. argv[]: the name of the command pointed to by element 0, the
  1427. first arg by element 1, and so on. A null args[] pointer
  1428. indicates the end of the argument list. All open files must
  1429. remain open so the exec'd process can use them. Returns only if
  1430. unsuccessful.
  1431. int
  1432. zsinl(n,s,x) int n, x; char *s;
  1433. Reads a line from file number n. Writes the line into the
  1434. address s provided by the caller. Writing terminates when
  1435. newline is read, but with newline discarded. Writing also
  1436. terminates upon EOF or if length x is exhausted. Returns:
  1437. -1: on EOF or error.
  1438. 0: on success.
  1439. int
  1440. zsout(n,s) int n; char *s;
  1441. Writes the string s out to file number n. Returns:
  1442. -1: on failure.
  1443. 0: on success.
  1444. int
  1445. zsoutl(n,s) int n; char *s;
  1446. Writes the string s out to file number n and adds a line
  1447. (record) terminator (boundary) appropriate for the system and
  1448. the file format. Returns:
  1449. -1: on failure.
  1450. 0: on success.
  1451. int
  1452. zsoutx(n,s,x) int n, x; char *s;
  1453. Writes exactly x characters from string s to file number n. If s
  1454. has fewer than x characters, then the entire string s is
  1455. written. Returns:
  1456. -1: on failure.
  1457. >= 0: on success, the number of characters actually written.
  1458. int
  1459. zstime(fn,yy,x) char *fn; struct zattr *yy; int x;
  1460. Sets the creation date (and other attributes) of an existing
  1461. file, or compares a file's creation date with a given date. Call
  1462. with:
  1463. fn: pointer to name of existing file.
  1464. yy: Pointer to a Kermit file attribute structure in which yy->date.val
  1465. is a date of the form yyyymmdd hh:mm:ss, e.g. 19900208 13:00:00, which
  1466. is to be used for setting or comparing the file date. Other attributes
  1467. in the struct can also be set, such as the protection/permission (See
  1468. Appendix I), when it makes sense (e.g. "yy->lprotect.val" can be
  1469. set if the remote system ID matches the local one).
  1470. x: A function code: 0 means to set the file's creation date as given.
  1471. 1 means compare the date from the yy struct with the file's date.
  1472. Returns:
  1473. -1: on any kind of error.
  1474. 0: if x is 0 and the file date was set successfully.
  1475. 0: if x is 1 and date from attribute structure > file creation
  1476. date.
  1477. 1: if x is 1 and date from attribute structure <= file
  1478. creation date.
  1479. VOID
  1480. zstrip(name,name2) char *name, **name2;
  1481. Strips pathname from filename "name". Constructs the resulting
  1482. string in a static buffer in its own space and returns a pointer
  1483. to it in name2. Also strips device name, file version numbers,
  1484. and other "non-name" material.
  1485. int
  1486. zxcmd(n,s) char *s;
  1487. Runs a system command so its output can be accessed as if it
  1488. were file n. The command is run in ordinary, unprivileged user
  1489. mode.
  1490. If n is ZSTDIO or ZCTERM, returns -1.
  1491. If n is ZIFILE or ZRFILE, then Kermit reads from the command,
  1492. otherwise Kermit writes to the command.
  1493. Returns 0 on error, 1 on success.
  1494. int
  1495. zxpand(fn) char *fn;
  1496. OBSOLETE: Replaced by nzxpand(), q.v.
  1497. #ifdef ZXREWIND
  1498. int
  1499. zxrewind()
  1500. Returns the number of files returned by the most recent
  1501. nzxpand() call, and resets the list to the beginning so the next
  1502. znext() call returns the first file. Returns -1 if zxpand has
  1503. not yet been called. If this function is available, ZXREWIND
  1504. should be defined; otherwise it should not be referenced.
  1505. #endif /* ZXREWIND */
  1506. int
  1507. xsystem(cmd) char *cmd;
  1508. Executes the system command without redirecting any of its i/o,
  1509. similar (well, identical) to system() in Unix. But before
  1510. passing the command to the system, xsystem() ensures that all
  1511. privileges are turned off, so that the system command executes
  1512. in ordinary unprivileged user mode. If possible, xsystem()
  1513. returns the return code of the command that was executed.
  1514. 4.E.2.2. IKSD Variables and Functions
  1515. These must be implemented in any C-Kermit version that is to be
  1516. installed as an Internet Kermit Service Daemon (IKSD). IKSD is expected
  1517. to be started by the Internet Daemon (e.g. inetd) with its standard i/o
  1518. redirected to the incoming connection.
  1519. int ckxanon;
  1520. Nonzero if anonymous logins allowed.
  1521. extern int inserver;
  1522. Nonzero if started in IKSD mode.
  1523. extern int isguest;
  1524. Nonzero if IKSD and user logged in anonymously.
  1525. extern char * homdir;
  1526. Pointer to user's home directory.
  1527. extern char * anonroot;
  1528. Pointer to file-system root for anonymous users.
  1529. Existing functions must make "if (inserver && isguest)" checks for
  1530. actions that would not be legal for guests: zdelete(), zrmdir(),
  1531. zprint(), zmail(), etc.
  1532. int
  1533. zvuser(name) char * name;
  1534. Verifies that user "name" exists and is allowed to log in. If
  1535. the name is "ftp" or "anonymous" and ckxanon != 0, a guest login
  1536. is set up. Returns 0 if user not allowed to log in, nonzero if
  1537. user may log in.
  1538. int
  1539. zvpass(string) char * string;
  1540. Verifies password of the user from the most recent zvuser()
  1541. call. Returns nonzero if password is valid for user, 0 if it
  1542. isn't. Makes any appropriate system log entries (IKSD logins,
  1543. failed login attempts, etc). If password is valid, logs the user
  1544. in as herself (if real user), or sets up restricted anonymous
  1545. access if user is guest (e.g. changes file-system root to
  1546. anonroot and sets isguest = 1).
  1547. VOID
  1548. zsyslog()
  1549. Begins any desired system logging of an IKSD session.
  1550. VOID
  1551. zvlogout()
  1552. Terminates an IKSD session. In most cases this is simply a
  1553. wrapper for exit() or doexit(), with some system logging added.
  1554. 4.E.2.3. Privilege Functions
  1555. These functions are used by C-Kermit to adapt itself to operating
  1556. systems where the program can be made to run in a "privileged" mode,
  1557. e.g. setuid or setgid in Unix. C-Kermit should NOT read and write files
  1558. or start subprocesses as a privileged program. This would present a
  1559. serious threat to system security. The security package has been
  1560. installed to prevent such security breaches by turning off the
  1561. program's special privileges at all times except when they are needed.
  1562. In UNIX, the only need Kermit has for privileged status is access to
  1563. the UUCP lockfile directory, in order to read, create, and destroy
  1564. lockfiles, and to open communication devices that are normally
  1565. protected against the user (see the Unix C-Kermit Installation
  1566. Instructions for discussion). Therefore, privileges should only be
  1567. enabled for these operations and disabled at all other times. This
  1568. relieves the programmer of the responsibility of putting expensive and
  1569. unreliable access checks around every file access and subprocess
  1570. creation.
  1571. Strictly speaking, these functions are not required in all C-Kermit
  1572. implementations, because their use (so far, at least) is internal to
  1573. the Group E modules. However, they should be included in all C-Kermit
  1574. implementations for operating systems that support the notion of a
  1575. privileged program (UNIX, RSTS/E, what others?).
  1576. int
  1577. priv_ini()
  1578. Determine whether the program is running in privileged status.
  1579. If so, turn off the privileges, in such a way that they can be
  1580. turned on again when needed. Called from sysinit() at program
  1581. startup time. Returns:
  1582. 0 on success
  1583. nonzero on failure, in which case the program should halt
  1584. immediately.
  1585. int
  1586. priv_on()
  1587. If the program is not privileged, this function does nothing. If
  1588. the program is privileged, this function returns it to
  1589. privileged status. priv_ini() must have been called first.
  1590. Returns:
  1591. 0 on success
  1592. nonzero on failure
  1593. int
  1594. priv_off()
  1595. Turns privileges off (if they are on) in such a way that they
  1596. can be turned back on again. Returns:
  1597. 0 on success
  1598. nonzero on failure
  1599. int
  1600. priv_can()
  1601. Turns privileges off in such a way that they cannot be turned
  1602. back on. Returns:
  1603. 0 on success
  1604. nonzero on failure
  1605. int
  1606. priv_chk()
  1607. Attempts to turns privileges off in such a way that they can be
  1608. turned on again later. Then checks to make sure that they were
  1609. really turned off. If they were not really turned off, then they
  1610. are canceled permanently. Returns:
  1611. 0 on success
  1612. nonzero on failure
  1613. 4.E.2.4. Console-Related Functions
  1614. These relate to the program's "console", or controlling terminal, i.e.
  1615. the terminal that the user is logged in on and types commands at, or on
  1616. a PC or workstation, the actual keyboard and screen.
  1617. int
  1618. conbin(esc) char esc;
  1619. Puts the console into "binary" mode, so that Kermit's command
  1620. parser can control echoing and other treatment of characters
  1621. that the user types. esc is the character that will be used to
  1622. get Kermit's attention during packet mode; puts this in a global
  1623. place. Sets the ckxech variable. Returns:
  1624. -1: on error.
  1625. 0: on success.
  1626. int
  1627. concb(esc) char esc;
  1628. Put console in "cbreak" (single-character wakeup) mode. That is,
  1629. ensure that each console character is available to the program
  1630. immediately when the user types it. Otherwise just like
  1631. conbin(). Returns:
  1632. -1: on error.
  1633. 0: on success.
  1634. int
  1635. conchk()
  1636. Returns a number, 0 or greater, the number of characters waiting
  1637. to be read from the console, i.e. the number of characters that
  1638. the user has typed that have not been read yet by Kermit.
  1639. long
  1640. congspd();
  1641. Returns the speed ("baud rate") of the controlling terminal, if
  1642. known, otherwise -1L.
  1643. int
  1644. congks(timo) int timo;
  1645. Get Keyboard Scancode. Reads a keyboard scan code from the
  1646. physical console keyboard. If the timo parameter is greater than
  1647. zero, then times out and returns -2 if no character appears
  1648. within the given number of seconds. Upon any other kind of
  1649. error, returns -1. Upon success returns a scan code, which may
  1650. be any positive integer. For situations where scan codes cannot
  1651. be read (for example, when an ASCII terminal is used as the
  1652. job's controlling terminal), this function is identical to
  1653. coninc(), i.e. it returns an 8-bit character value. congks() is
  1654. for use with workstations whose keyboards have Alternate,
  1655. Command, Option, and similar modifier keys, and Function keys
  1656. that generate codes greater than 255.
  1657. int
  1658. congm()
  1659. Console get modes. Gets the current console terminal modes and
  1660. saves them so that conres() can restore them later. Returns 1 if
  1661. it got the modes OK, 0 if it did nothing (e.g. because Kermit is
  1662. not connected with any terminal), -1 on error.
  1663. int
  1664. coninc(timo) int timo;
  1665. Console Input Character. Reads a character from the console. If
  1666. the timo parameter is greater than zero, then coninc() times out
  1667. and returns -2 if no character appears within the given number
  1668. of seconds. Upon any other kind of error, returns -1. Upon
  1669. success, returns the character itself, with a value in the range
  1670. 0-255 decimal.
  1671. VOID
  1672. conint(f,s) SIGTYP (*f)(), (*s)();
  1673. Sets the console to generate an interrupt if the user types a
  1674. keyboard interrupt character, and to transfer control the
  1675. signal-handling function f. For systems with job control, s is
  1676. the address of the function that suspends the job. Sets the
  1677. global variable "backgrd" to zero if Kermit is running in the
  1678. foreground, and to nonzero if Kermit is running in the
  1679. background. See ckcdeb.h for the definition of SIGTYP. No return
  1680. value.
  1681. VOID
  1682. connoi()
  1683. Console no interrupts. Disable keyboard interrupts on the
  1684. console. No return value.
  1685. int
  1686. conoc(c) char c;
  1687. Writes character c to the console terminal. Returns:
  1688. 0 on failure, 1 on success.
  1689. int
  1690. conol(s) char *s;
  1691. Writes string s to the console. Returns -1 on error, 0 or
  1692. greater on success.
  1693. int
  1694. conola(s) char *s[]; {
  1695. Writes an array of strings to the console. Returns -1 on error,
  1696. 0 or greater on success.
  1697. int
  1698. conoll(s) char *s;
  1699. Writes string s to the console, followed by the necessary line
  1700. termination characters to put the console cursor at the
  1701. beginning of the next line. Returns -1 on error, 0 or greater on
  1702. success.
  1703. int
  1704. conres()
  1705. Restores the console terminal to the modes obtained by congm().
  1706. Returns: -1 on error, 0 on success.
  1707. int
  1708. conxo(x,s) int x; char *s;
  1709. Write x characters from string s to the console. Returns 0 or
  1710. greater on success, -1 on error.
  1711. char *
  1712. conkbg();
  1713. Returns a pointer to the designator of the console keyboard
  1714. type. For example, on a PC, this function would return "88",
  1715. "101", etc. Upon failure, returns a pointer to the empty string.
  1716. 4.E.2.5. Communications Functions
  1717. The communication device is the device used for terminal emulation and
  1718. file transfer. It may or may not be the same device as the console, and
  1719. it may or may not be a terminal (serial-port) device; it could also be
  1720. a network connection. For brevity, the communication device is referred
  1721. to here as the "tty". When the communication device is the same as the
  1722. console device, Kermit is said to be in remote mode. When the two
  1723. devices are different, Kermit is in local mode.
  1724. int
  1725. ttchk()
  1726. Returns the number of characters that have arrived at the
  1727. communication device but have not yet been read by ttinc(),
  1728. ttinl(), and friends. If communication input is buffered (and it
  1729. should be), this is the sum of the number of unread characters
  1730. in Kermit's buffer PLUS the number of unread characters in the
  1731. operating system's internal buffer. The call must be
  1732. nondestructive and nonblocking, and as inexpensive as possible.
  1733. Returns:
  1734. 0: or greater on success,
  1735. 0: in case of internal error,
  1736. -1: or less when it determines the connection has been broken,
  1737. or there is no connection.
  1738. That is, a negative return from ttchk() should reliably indicate
  1739. that there is no usable connection. Furthermore, ttchk() should
  1740. be callable at any time to see if the connection is open. When
  1741. the connection is open, every effort must be made to ensure that
  1742. ttchk returns an accurate number of characters waiting to be
  1743. read, rather than just 0 (no characters) or 1 (1 or more
  1744. characters), as would be the case when we use select(). This
  1745. aspect of ttchk's operation is critical to successful operation
  1746. of sliding windows and streaming, but "nondestructive buffer
  1747. peeking" is an obscure operating system feature, and so when it
  1748. is not available, we have to do it ourselves by managing our own
  1749. internal buffer at a level below ttinc(), ttinl(), etc, as in
  1750. the UNIX version (non-FIONREAD case).
  1751. An external global variable, clsondisc, if nonzero, means that
  1752. if a serial connection drops (carrier on-to-off transition
  1753. detected by ttchk()), the device should be closed and released
  1754. automatically.
  1755. int
  1756. ttclos()
  1757. Closes the communication device (tty or network). If there were
  1758. any kind of exclusive access locks connected with the tty, these
  1759. are released. If the tty has a modem connection, it is hung up.
  1760. For true tty devices, the original tty device modes are
  1761. restored. Returns:
  1762. -1: on failure.
  1763. 0: on success.
  1764. int
  1765. ttflui()
  1766. Flush communications input buffer. If any characters have
  1767. arrived but have not yet been read, discard these characters. If
  1768. communications input is buffered by Kermit (and it should be),
  1769. this function flushes Kermit's buffer as well as the operating
  1770. system's internal input buffer. Returns:
  1771. -1: on failure.
  1772. 0: on success.
  1773. int
  1774. ttfluo()
  1775. Flush tty output buffer. If any characters have been written but
  1776. not actually transmitted (e.g. because the system has been
  1777. flow-controlled), remove them from the system's output buffer.
  1778. (Note, this function is not actually used, but it is recommended
  1779. that all C-Kermit programmers add it for future use, even if it
  1780. is only a dummy function that returns 0 always.)
  1781. int
  1782. ttgmdm()
  1783. Looks for the modem signals CTS, DSR, and CTS, and returns those
  1784. that are on in as its return value, in a bit mask as described
  1785. for ttwmdm, in which a bit is on (1) or off (0) according to
  1786. whether the corresponding signal is on (asserted) or off (not
  1787. asserted). Return values:
  1788. -3: Not implemented
  1789. -2: if the line does not have modem control
  1790. -1: on error
  1791. >=0: on success, with bit mask containing the modem signals.
  1792. long
  1793. ttgspd()
  1794. Returns the current tty speed in BITS (not CHARACTERS) per
  1795. second, or -1 if it is not known or if the tty is really a
  1796. network, or upon any kind of error. On success, the speed
  1797. returned is the actual number of bits per second, like 1200,
  1798. 9600, 19200, etc.
  1799. int
  1800. ttgwsiz()
  1801. Get terminal window size. Returns -1 on error, 0 if the window
  1802. size can't be obtained, 1 if the window size has been
  1803. successfully obtained. Upon success, the external global
  1804. variables tt_rows and tt_cols are set to the number of screen
  1805. rows and number of screen columns, respectively. As this
  1806. function is not implemented in all ck*tio.c modules, calls to it
  1807. must be wrapped in #ifdef CK_TTGWSIZ..#endif. NOTE: This
  1808. function must be available to use the TELNET NAWS feature
  1809. (Negotiate About Window Size) as well as Rlogin.
  1810. int
  1811. tthang()
  1812. Hang up the current tty device. For real tty devices, turn off
  1813. DTR for about 1/3-1/2 second (or other length of time, depending
  1814. on the system). If the tty is really a network connection, close
  1815. it. Returns:
  1816. -1: on failure.
  1817. 0: if it does not even try to hang up.
  1818. 1: if it believes it hung up successfully.
  1819. VOID
  1820. ttimoff()
  1821. Turns off all pending timer interrupts.
  1822. int
  1823. ttinc(timo) int timo; (function is old, return codes are new)
  1824. Reads one character from the communication device. If timo is
  1825. greater than zero, wait the given number of seconds and then
  1826. time out if no character arrives, otherwise wait forever for a
  1827. character. Returns:
  1828. -3: internal error (e.g. tty modes set wrong)
  1829. -2: communications disconnect
  1830. -1: timeout or other error
  1831. >=0: the character that was read.
  1832. It is HIGHLY RECOMMENDED that ttinc() be internally buffered so
  1833. that calls to it are relatively inexpensive. If it is possible
  1834. to to implement ttinc() as a macro, all the better, for example
  1835. something like:
  1836. #define ttinc(t) ( (--txbufn >= 0) ? txbuf[ttbufp++] : txbufr(t) )
  1837. (see description of txbufr() below)
  1838. int
  1839. ttinl(dest,max,timo,eol,start,turn) int max,timo,turn; CHAR
  1840. *dest, eol, start;
  1841. ttinl() is Kermit's packet reader. Reads a packet from the
  1842. communications device, or up to max characters, whichever occurs
  1843. first. A line is a string of characters starting with the start
  1844. character up to and including the character given in eol or
  1845. until the length is exhausted, or, if turn != 0, until the line
  1846. turnaround character (turn) is read. If turn is 0, ttinl()
  1847. *should* use the packet length field to detect the end, to allow
  1848. for the possibility that the eol character appears unprefixed in
  1849. the packet data. (The turnaround character is for half-duplex
  1850. linemode connections.)
  1851. If timo is greater than zero, ttinl() times out if the eol
  1852. character is not encountered within the given number of seconds
  1853. and returns -1.
  1854. The characters that were input are copied into "dest" with their
  1855. parity bits stripped if parity is not none. The first character
  1856. copied into dest should be the start character, and the last
  1857. should be the final character of the packet (the last block
  1858. check character). ttinl() should also absorb and discard the eol
  1859. and turn characters, and any other characters that are waiting
  1860. to be read, up until the next start character, so that
  1861. subsequent calls to ttchk() will not succeed simply because
  1862. there are some terminators still sitting in the buffer that
  1863. ttinl() didn't read. This operation, if performed, MUST NOT
  1864. BLOCK (so if it can't be performed in a guaranteed nonblocking
  1865. way, don't do it).
  1866. On success, ttinl() returns the number of characters read.
  1867. Optionally, ttinl() can sense the parity of incoming packets. If
  1868. it does this, then it should set the global variable ttprty
  1869. accordingly. ttinl() should be coded to be as efficient as
  1870. possible, since it is at the "inner loop" of packet reception.
  1871. ttinl() returns:
  1872. -1: Timeout or other possibly correctable error.
  1873. -2: Interrupted from keyboard.
  1874. -3: Uncorrectable i/o error -- connection lost, configuration
  1875. problem, etc.
  1876. >=0: on success, the number of characters that were actually
  1877. read and placed in the dest buffer, not counting the trailing
  1878. null.
  1879. int
  1880. ttoc(c) char c;
  1881. Outputs the character c to the communication line. If the
  1882. operation fails to complete within two seconds, this function
  1883. returns -1. Otherwise it returns the number of characters
  1884. actually written to the tty (0 or 1). This function should only
  1885. be used for interactive, character-mode operations, like
  1886. terminal connection, script execution, dialer i/o, where the
  1887. overhead of the signals and alarms does not create a bottleneck.
  1888. (THIS DESCRIPTION NEEDS IMPROVEMENT -- If the operation fails
  1889. within a "certain amount of time"... which might be dependent on
  1890. the communication method, speed, etc. In particular,
  1891. flow-control deadlocks must be accounted for and broken out of
  1892. to prevent the program from hanging indefinitely, etc.)
  1893. int
  1894. ttol(s,n) int n; char *s;
  1895. Kermit's packet writer. Writes the n characters of the string
  1896. pointed to to by s. NOTE: It is ttol's responsibility to write
  1897. ALL of the characters, not just some of them. Returns:
  1898. -1: on a possibly correctable error (so it can be retried).
  1899. -3: on a fatal error, e.g. connection lost.
  1900. >=0: on success, the actual number of characters written (the
  1901. specific number is not actually used for anything).
  1902. int
  1903. ttopen(ttname,lcl,modem,timo) char *ttname; int *lcl, modem,
  1904. timo;
  1905. Opens a tty device, if it is not already open. ttopen must check
  1906. to make sure the SAME device is not already open; if it is,
  1907. ttopen returns successfully without doing anything. If a
  1908. DIFFERENT device is currently open, ttopen() must call ttclos()
  1909. to close it before opening the new one.
  1910. Parameters:
  1911. ttname:
  1912. character string - device name or network host name.
  1913. lcl:
  1914. If called with lcl < 0, sets value of lcl as
  1915. follows:
  1916. 0: the terminal named by ttname is the job's
  1917. controlling terminal.
  1918. 1: the terminal named by ttname is not the job's
  1919. controlling terminal.
  1920. If the device is already open, or if the requested
  1921. device can't be opened, then lcl remains (and is
  1922. returned as) -1.
  1923. modem:
  1924. Less than zero: this is the negative of the network
  1925. type, and ttname is a network host name. Network
  1926. types (from ckcnet.h:
  1927. NET_TCPB 1 TCP/IP Berkeley (socket) (implemented in ckutio.c)
  1928. NET_TCPA 2 TCP/IP AT&T (streams) (not yet implemented)
  1929. NET_DEC 3 DECnet (not yet implemented)
  1930. Zero or greater: ttname is a terminal device name.
  1931. Zero means a direct connection (don't use modem
  1932. signals). Positive means use modem signals depending
  1933. on the current setting of ttcarr (see ttscarr()).
  1934. timo:
  1935. > 0: number of seconds to wait for open() to return
  1936. before timing out.
  1937. <=0: no timer, wait forever (e.g. for incoming
  1938. call).
  1939. For real tty devices, ttopen() attempts to gain
  1940. exclusive access to the tty device, for example in
  1941. UNIX by creating a "lockfile" (in other operating
  1942. systems, like VMS, exclusive access probably
  1943. requires no special action).
  1944. Side effects:
  1945. Copies its arguments and the tty file descriptor to global
  1946. variables that are available to the other tty-related
  1947. functions, with the lcl value altered as described above.
  1948. Gets all parameters and settings associated with the line
  1949. and puts them in a global area, so that they can be
  1950. restored by ttres(), e.g. when the device is closed.
  1951. Returns:
  1952. 0: on success
  1953. -5: if device is in use
  1954. -4: if access to device is denied
  1955. -3: if access to lock mechanism denied
  1956. -2: upon timeout waiting for device to open
  1957. -1: on other error
  1958. int
  1959. ttpkt(speed,flow,parity) long speed; int flow, parity;
  1960. Puts the currently open tty device into the appropriate modes
  1961. for transmitting and receiving Kermit packets.
  1962. Arguments:
  1963. speed:
  1964. if speed > -1, and the device is a true tty device,
  1965. and Kermit is in local mode, ttpkt also sets the
  1966. speed.
  1967. flow:
  1968. if in the range 0-3, ttpkt selects the corresponding
  1969. type of flow control. Currently 0 is defined as no
  1970. flow control, 1 is Xon/Xoff, and no other types are
  1971. defined. If (and this is a horrible hack, but it
  1972. goes back many years and will be hard to eradicate)
  1973. flow is 4, then the appropriate tty modes are set
  1974. for modem dialing, a special case in which we talk
  1975. to a modem-controlled line without requiring
  1976. carrier. If flow is 5, then we require carrier.
  1977. parity:
  1978. This is simply copied into a global variable so that
  1979. other functions (like ttinl, ttinc, etc) can use it.
  1980. Side effects:
  1981. Copies its arguments to global variables, flushes the
  1982. terminal device input buffer.
  1983. Returns:
  1984. -1: on error.
  1985. 0: on success.
  1986. int
  1987. ttsetflow(int)
  1988. Enables the given type of flow control on the open serial
  1989. communications device immediately. Arguments are the FLO_xxx
  1990. values from ckcdeb.h, except FLO_DIAL, FLO_DIAX, or FLO_AUTO,
  1991. which are not actual flow-control types. Returns 0 on success,
  1992. -1 on failure.
  1993. #ifdef TTSPDLIST
  1994. long *
  1995. ttspdlist()
  1996. Returns a pointer to an array of longs, or NULL on failure. On
  1997. success, element 0 of the array contains number, n, indicating
  1998. how many follow. Elements 1-n are serial speeds, expressed in
  1999. bits per second, that are legal on this platform. The user
  2000. interface may use this list to construct a menu, keyword table,
  2001. etc.
  2002. #endif /* TTSPDLIST */
  2003. int
  2004. ttres()
  2005. Restores the tty device to the modes and settings that were in
  2006. effect at the time it was opened (see ttopen). Returns:
  2007. -1: on error.
  2008. 0: on success.
  2009. int
  2010. ttruncmd(string) char * string;
  2011. Runs the given command on the local system, but redirects its
  2012. input and output to the communication (SET LINE, SET PORT, or
  2013. SET HOST) device. Returns:
  2014. 0: on failure.
  2015. 1: on success.
  2016. int
  2017. ttscarr(carrier) int carrier;
  2018. Copies its argument to a variable that is global to the other
  2019. tty-related functions, and then returns it. The values for
  2020. carrier are defined in ckcdeb.h: CAR_ON, CAR_OFF, CAR_AUTO.
  2021. ttopen(), ttpkt(), and ttvt() use this variable when deciding
  2022. how to open the tty device and what modes to select. The
  2023. meanings are these:
  2024. CAR_OFF: Ignore carrier at all times.
  2025. CAR_ON: Require carrier at all times, except when dialing. This means,
  2026. for example, that ttopen() could hang forever waiting for carrier if it
  2027. is not present.
  2028. CAR_AUTO: If the modem type is zero (i.e. the connection is direct),
  2029. this is the same as CAR_OFF. If the modem type is positive, then heed
  2030. carrier during CONNECT (ttvt mode), but ignore it at other times
  2031. (packet mode, during SET LINE, etc). Compatible with pre-5A versions of
  2032. C-Kermit. This should be the default carrier mode.
  2033. Kermit's DIAL command ignores the carrier setting, but ttopen(),
  2034. ttvt(), and ttpkt() all honor the carrier option in effect at
  2035. the time they are called. None of this applies to remote mode
  2036. (the tty device is the job's controlling terminal) or to network
  2037. host connections (modem type is negative).
  2038. int
  2039. ttsndb()
  2040. Sends a BREAK signal on the tty device. On a real tty device,
  2041. send a real BREAK lasting approximately 275 milliseconds. If
  2042. this is not possible, simulate a BREAK by (for example) dropping
  2043. down some very low baud rate, like 50, and sending a bunch of
  2044. null characters. On a network connection, do the appropriate
  2045. network protocol for BREAK. Returns:
  2046. -1: on error.
  2047. 0: on success.
  2048. int
  2049. ttsndlb()
  2050. Like ttsndb(), but sends a "Long BREAK" (approx 1.5 seconds).
  2051. For network connections, it is identical to ttsndb(). Currently,
  2052. this function is used only if CK_LBRK is defined (as it is for
  2053. UNIX and VMS).
  2054. int
  2055. ttsspd(cps) int cps;
  2056. For serial devices only, set the device transmission speed to
  2057. (note carefully) TEN TIMES the argument. The argument is in
  2058. characters per second, but transmission speeds are in bits per
  2059. second. cps are used rather than bps because high speeds like
  2060. 38400 are not expressible in a 16-bit int but longs cannot be
  2061. used because keyword-table values are ints and not longs. If the
  2062. argument is 7, then the bps is 75, not 70. If the argument is
  2063. 888, this is a special code for 75/1200 split-speed operation
  2064. (75 bps out, 1200 bps in). Returns:
  2065. -1: on error, meaning the requested speed is not valid or
  2066. available.
  2067. >=0: on success (don't try to use this value for anything).
  2068. int
  2069. ttvt(speed,flow) long speed; int flow;
  2070. Puts the currently open tty device into the appropriate modes
  2071. for terminal emulation. The arguments are interpreted as in
  2072. ttpkt(). Side effects: ttvt() stores its arguments in global
  2073. variables, and sets a flag that it has been called so that
  2074. subsequent calls can be ignored so long as the arguments are the
  2075. same as in the last effective call. Other functions, such as
  2076. ttopen(), ttclose(), ttres(), ttvt(), etc, that change the tty
  2077. device in any way must unset this flag. In UNIX Kermit, this
  2078. flag is called tvtflg.
  2079. int
  2080. ttwmdm(mdmsig,timo) int mdmsig, timo;
  2081. Waits up to timo seconds for all of the given modem signals to
  2082. appear. mdmsig is a bit mask, in which a bit is on (1) or off
  2083. (0) according to whether the corresponding signal is to be
  2084. waited for. These symbols are defined in ckcdeb.h:
  2085. BM_CTS (bit 0) means wait for Clear To Send
  2086. BM_DSR (bit 1) means wait for Data Set Ready
  2087. BM_DCD (bit 2) means wait for Carrier Detect
  2088. Returns:
  2089. -3: Not implemented.
  2090. -2: This line does not have modem control.
  2091. -1: Timeout: time limit exceeded before all signals were
  2092. detected.
  2093. 1: Success.
  2094. int
  2095. ttxin(n,buf) int n; CHAR *buf;
  2096. Reads x characters from the tty device into the specified buf,
  2097. stripping parity if parity is not none. This call waits forever,
  2098. there is no timeout. This function is designed to be called only
  2099. when you know that at least x characters are waiting to be read
  2100. (as determined, for example, by ttchk()). This function should
  2101. use the same buffer as ttinc().
  2102. int
  2103. txbufr(timo) int timo;
  2104. Reads characters into the internal communications input buffer.
  2105. timo is a timeout interval, in seconds. 0 means no timeout, wait
  2106. forever. Called by ttinc() (and possibly ttxin() and ttinl())
  2107. when the communications input buffer is empty. The buffer should
  2108. be called ttxbuf[], its length is defined by the symbol TXBUFL.
  2109. The global variable txbufn is the number of characters available
  2110. to be read from ttxbuf[], and txbufp is the index of the next
  2111. character to be read. Should not be called if txbufn > 0, in
  2112. which case the buffer does not need refilling. This routine
  2113. returns:
  2114. -2: Communications disconnect
  2115. -1: Timeout
  2116. >=0: A character (0 - 255) On success, the first character that
  2117. was read, with the variables txbufn and txbufp set appropriately
  2118. for any remaining characters.
  2119. NOTE: Currently this routine is used internally only by the UNIX
  2120. and VMS versions. The aim is to make it available to all
  2121. versions so there is one single coherent and efficient way of
  2122. reading from the communications device or network.
  2123. 4.E.2.6. Miscellaneous system-dependent functions
  2124. VOID
  2125. ztime(s) char **s;
  2126. Returns a pointer, s, to the current date-and-time string in s.
  2127. This string must be in the fixed-field format associated with
  2128. the C runtime asctime() function, like: "Sun Sep 16 13:23:45
  2129. 1973\n" so that callers of this function can extract the
  2130. different fields. The pointer value is filled in by ztime, and
  2131. the data it points to is not safe, so should be copied to a safe
  2132. place before use. ztime() has no return value. As a side effect,
  2133. this routine can also fill in the following two external
  2134. variables (which must be defined in the system-dependent modules
  2135. for each platform):
  2136. long ztusec: Fraction of seconds of clock time, microseconds.
  2137. long ztmsec: Fraction of seconds of clock time, milliseconds.
  2138. If these variables are not set by zstime(), they remain at their
  2139. initial value of -1L.
  2140. int
  2141. gtimer()
  2142. Returns the current value of the elapsed time counter in seconds
  2143. (see rtimer), or 0 on any kind of error.
  2144. #ifdef GFTIMER
  2145. CKFLOAT
  2146. gftimer()
  2147. Returns the current value of the elapsed time counter in
  2148. seconds, as a floating point number, capable of representing not
  2149. only whole seconds, but also the fractional part, to the
  2150. millisecond or microsecond level, whatever precision is
  2151. available. Requires a function to get times at subsecond
  2152. precision, as well as floating-point support. That's why it's
  2153. #ifdef'd.
  2154. #endif /* GFTIMER */
  2155. int
  2156. msleep(m) int m;
  2157. Sleeps (pauses, does nothing) for m milliseconds (a millisecond
  2158. is one thousandth of a second). Returns:
  2159. -1: on failure.
  2160. 0: on success.
  2161. VOID
  2162. rtimer()
  2163. Sets the elapsed time counter to zero. If you want to time how
  2164. long an operation takes, call rtimer() when it starts and gtimer
  2165. when it ends. rtimer() has no return value.
  2166. #ifdef GFTIMER
  2167. VOID
  2168. rftimer()
  2169. Sets the elapsed time counter to zero. If you want to time how
  2170. long an operation takes, call rftimer() when it starts and
  2171. gftimer when it ends. rftimer() has no return value. Note:
  2172. rftimer() is to be used with gftimer() and rtimer() is to be
  2173. used with gtimer(). See the rftimer() description.
  2174. #endif /* GFTIMER */
  2175. int
  2176. sysinit()
  2177. Does whatever needs doing upon program start. In particular, if
  2178. the program is running in any kind of privileged mode, turns off
  2179. the privileges (see priv_ini()). Returns:
  2180. -1: on error.
  2181. 0: on success.
  2182. int
  2183. syscleanup()
  2184. Does whatever needs doing upon program exit. Returns:
  2185. -1: on error.
  2186. 0: on success.
  2187. int
  2188. psuspend()
  2189. Suspends the Kermit process, puts it in the background so it can
  2190. be continued ("foregrounded") later. Returns:
  2191. -1: if this function is not supported.
  2192. 0: on success.
  2193. 4.F. Group F: Network Support
  2194. As of version 5A, C-Kermit includes support for several networks.
  2195. Originally, this was just worked into the ttopen(), ttclos(), ttinc(),
  2196. ttinl(), and similar routines in ckutio.c. But this made it
  2197. impossible to share this code with non-UNIX versions, like VMS, AOS/VS,
  2198. OS/2, etc. So as of edit 168, network code has been separated out into
  2199. its own module and header file, ckcnet.c and ckcnet.h:
  2200. ckcnet.h: Network-related symbol definitions.
  2201. ckcnet.c: Network i/o (TCP/IP, X.25, etc), shared by most
  2202. platforms.
  2203. cklnet.c: Network i/o (TCP/IP, X.25, etc) specific to Stratus
  2204. VOS.
  2205. The routines and variables in these modules fall into two categories:
  2206. 1. Support for specific network packages like SunLink X.25 and TGV
  2207. MultiNet, and:
  2208. 2. support for specific network virtual terminal protocols like CCITT
  2209. X.3 and TCP/IP Telnet.
  2210. Category (1) functions are analogs to the tt*() functions, and have
  2211. names like netopen, netclos, nettinc, etc. Group A-D modules do not
  2212. (and must not) know anything about these functions -- they continue to
  2213. call the old Group E functions (ttopen, ttinc, etc). Category (2)
  2214. functions are protocol specific and have names prefixed by a protocol
  2215. identifier, like tn for telnet x25 for X.25.
  2216. ckcnet.h contains prototypes for all these functions, as well as symbol
  2217. definitions for network types, protocols, and network- and protocol-
  2218. specific symbols, as well as #includes for the header files necessary
  2219. for each network and protocol.
  2220. The following functions are to be provided for networks that do not use
  2221. normal system i/o (open, read, write, close):
  2222. int
  2223. netopen()
  2224. To be called from within ttopen() when a network connection is
  2225. requested. Calling conventions and purpose same as Group E
  2226. ttopen().
  2227. int
  2228. netclos()
  2229. To be called from within ttclos() when a network connection is
  2230. being closed. Calling conventions and purpose same as Group E
  2231. ttclos().
  2232. int
  2233. nettchk()
  2234. To be called from within ttchk(). Calling conventions and
  2235. purpose same as Group E ttchk().
  2236. int
  2237. netflui()
  2238. To be called from within ttflui(). Calling conventions and
  2239. purpose same as Group E ttflui().
  2240. int
  2241. netbreak()
  2242. To send a network break (attention) signal. Calling conventions
  2243. and purpose same as Group E ttsndbrk().
  2244. int
  2245. netinc()
  2246. To get a character from the network. Calling conventions same as
  2247. Group E ttsndbrk().
  2248. int
  2249. nettoc()
  2250. Send a "character" (byte) to the network. Calling conventions
  2251. same as Group E ttoc().
  2252. int
  2253. nettol()
  2254. Send a "line" (sequence of bytes) to the network. Calling
  2255. conventions same as Group E ttol().
  2256. Conceivably, some systems support network connections simply by letting
  2257. you open a device of a certain name and letting you do i/o to it.
  2258. Others (like the Berkeley sockets TCP/IP library on UNIX) require you
  2259. to open the connection in a special way, but then do normal i/o (read,
  2260. write). In such a case, you would use netopen(), but you would not use
  2261. nettinc, nettoc, etc.
  2262. VMS TCP/IP products have their own set of functions for all network
  2263. operations, so in that case the full range of netxxx() functions is
  2264. used.
  2265. The technique is to put a test in each corresponding ttxxx() function
  2266. to see if a network connection is active (or is being requested), test
  2267. for which kind of network it is, and if necessary route the call to the
  2268. corresponding netxxx() function. The netxxx() function must also
  2269. contain code to test for the network type, which is available via the
  2270. global variable ttnet.
  2271. 4.F.1. Telnet Protocol
  2272. (This section needs a great deal of updating...)
  2273. As of edit 195, Telnet protocol is split out into its own files, since
  2274. it can be implemented in remote mode, which does not have a network
  2275. connection:
  2276. ckctel.h: Telnet protocol symbol definitions.
  2277. ckctel.c: Telnet protocol.
  2278. The Telnet protocol is supported by the following variables and
  2279. routines:
  2280. int tn_init
  2281. Nonzero if telnet protocol initialized, zero otherwise.
  2282. int
  2283. tn_init()
  2284. Initialize the telnet protocol (send initial options).
  2285. int
  2286. tn_sopt()
  2287. Send a telnet option.
  2288. int
  2289. tn_doop()
  2290. Receive and act on a telnet option from the remote.
  2291. int
  2292. tn_sttyp()
  2293. Send terminal type using telnet protocol.
  2294. 4.F.2. FTP Protocol
  2295. (To be filled in...) See the source file
  2296. 4.F.3. HTTP Protocol
  2297. (To be filled in...)
  2298. 4.F.4. X.25 Networks
  2299. These routines were written SunLink X.25 and have since been adapted to
  2300. at least on one other: IBM AIXLink/X.25.
  2301. int
  2302. x25diag()
  2303. Reads and prints X.25 diagnostics
  2304. int
  2305. x25oobh()
  2306. X.25 out of band signal handler
  2307. int
  2308. x25intr()
  2309. Sends X.25 interrupt packet
  2310. int
  2311. x25reset()
  2312. Resets X.25 virtual circuit
  2313. int
  2314. x25clear()
  2315. Clear X.25 virtual circuit
  2316. int
  2317. x25stat()
  2318. X.25 status
  2319. int
  2320. setqbit()
  2321. Sets X.25 Q-bit
  2322. int
  2323. resetqbit()
  2324. Resets X.25 Q-bit
  2325. int
  2326. x25xin()
  2327. Reads n characters from X.25 circuit.
  2328. int
  2329. x25inl()
  2330. Read a Kermit packet from X.25 circuit.
  2331. 4.F.5. Adding New Network Types
  2332. Example: Adding support for IBM X.25 and Hewlett Packard X.25. First,
  2333. add new network type symbols for each one. There are already some
  2334. network types defined for other X.25 packages:
  2335. NET_SX25 is the network-type ID for SunLink X.25.
  2336. NET_VX25 is the network-type ID for VOS X.25.
  2337. So first you should new symbols for the new network types, giving them
  2338. the next numbers in the sequence, e.g.:
  2339. #define NET_HX25 11 /* Hewlett-Packard X.25 */
  2340. #define NET_IX25 12 /* IBM X.25 */
  2341. This is in ckcnet.h.
  2342. Then we need symbols to say that we are actually compiling in the code
  2343. for these platforms. These would be defined on the cc command line:
  2344. -DIBMX25 (for IBM)
  2345. -DHPX25 (for HP)
  2346. So we can build C-Kermit versions for AIX and HP-UX both with and
  2347. without X.25 support (since not all AIX and IBM systems have the needed
  2348. libraries, and so an executable that was linked with them might no
  2349. load).
  2350. Then in ckcnet.h:
  2351. #ifdef IBMX25
  2352. #define ANYX25
  2353. #endif /* IBMX25 */
  2354. #ifdef HPX25
  2355. #define ANYX25
  2356. #endif /* HPX25 */
  2357. And then use ANYX25 for code that is common to all of them, and IBMX25
  2358. or HPX25 for code specific to IBM or HP.
  2359. It might also happen that some code can be shared between two or more
  2360. of these, but not the others. Suppose, for example, that you write code
  2361. that applies to both IBM and HP, but not Sun or VOS X.25. Then you add
  2362. the following definition to ckcnet.h:
  2363. #ifndef HPORIBMX25
  2364. #ifdef HPX25
  2365. #define HPORIBMX25
  2366. #else
  2367. #ifdef IBMX25
  2368. #define HPORIBMX25
  2369. #endif /* IBMX25 */
  2370. #endif /* HPX25 */
  2371. #endif /* HPORIBMX25 */
  2372. You can NOT use constructions like "#if defined (HPX25 || IBMX25)";
  2373. they are not portable.
  2374. 4.G. Group G: Formatted Screen Support
  2375. So far, this is used only for the fullscreen local-mode file transfer
  2376. display. In the future, it might be extended to other uses. The
  2377. fullscreen display code is in and around the routine screenc() in
  2378. ckuusx.c.
  2379. In the UNIX version, we use the curses library, plus one call from the
  2380. termcap library. In other versions (OS/2, VMS, etc) we insert dummy
  2381. routines that have the same names as curses routines. So far, there are
  2382. two methods for simulating curses routines:
  2383. 1. In VMS, we use the Screen Management Library (SMG), and insert
  2384. stubs to convert curses calls into SMG calls.
  2385. 2. In OS/2, we use the MYCURSES code, in which the stub routines
  2386. actually emit the appropriate escape sequences themselves.
  2387. Here are the stub routines:
  2388. int
  2389. tgetent(char *buf, char *term)
  2390. Arguments are ignored. Returns 1 if the user has a supported
  2391. terminal type, 0 otherwise. Sets a global variable (for example,
  2392. "isvt52" or "isdasher") to indicate the terminal type.
  2393. VOID
  2394. move(int row, int col)
  2395. Sends the escape sequence to position the cursor at the
  2396. indicated row and column. The numbers are 0-based, e.g. the home
  2397. position is 0,0.
  2398. int
  2399. clear()
  2400. Sends the escape sequence to clear the screen.
  2401. int
  2402. clrtoeol()
  2403. Sends the escape sequence to clear from the current cursor
  2404. position to the end of the line.
  2405. In the MYCURSES case, code must be added to each of the last three
  2406. routines to emit the appropriate escape sequences for a new terminal
  2407. type.
  2408. clearok(curscr), wrefresh()
  2409. In real curses, these two calls are required to refresh the
  2410. screen, for example after it was fractured by a broadcast
  2411. message. These are useful only if the underlying screen
  2412. management service keeps a copy of the entire screen, as curses
  2413. and SMG do. C-Kermit does not do this itself.
  2414. 4.H. Group H: Pseudoterminal Support
  2415. (To be filled in...) But see: these comments, and the source files
  2416. ckupty.h and ckupty.c.
  2417. 4.I. Group I: Security
  2418. (To be filled in...) Meanwhile, see security.html.
  2419. APPENDIX I. FILE PERMISSIONS
  2420. I.1. Format of System-Dependent File Permissions in A-Packets
  2421. The format of this field (the "," attribute) is interpreted according
  2422. to the System ID ("." Attribute).
  2423. For UNIX (System ID = U1), it's the familiar 3-digit octal number, the
  2424. low-order 9 bits of the filemode: Owner, Group, World, e.g. 660 =
  2425. read/write access for owner and group, none for world, recorded as a
  2426. 3-digit octal string. High-order UNIX permission bits are not
  2427. transmitted.
  2428. For VMS (System ID = D7), it's a 4-digit hex string, representing the
  2429. 16-bit file protection WGOS fields (World,Group,Owner,System), in that
  2430. order (which is the reverse of how they're shown in a directory
  2431. listing); in each field, Bit 0 = Read, 1 = Write, 2 = Execute, 3 =
  2432. Delete. A bit value of 0 means permission is granted, 1 means
  2433. permission is denied. Sample:
  2434. r-01-00-^A/!FWERMIT.EXE'"
  2435. s-01-00-^AE!Y/amd/watsun/w/fdc/new/wermit.exe.DV
  2436. r-02-01-^A]"A."D7""B8#119980101 18:14:05!#8531&872960,$A20B-!7(#512@ #.Y
  2437. s-02-01-^A%"Y.5!
  2438. A VMS directory listing shows the file's protection as (E,RWED,RED,RE)
  2439. which really means (S=E,O=RWED,G=RED,W=RE), which is reverse order from
  2440. the internal storage, so (RE,RED,RWED,E). Now translate each letter to
  2441. its corresponding bit:
  2442. RE=0101, RED=1101, RWED=1111, E=0010
  2443. Now reverse the bits:
  2444. RE=1010, RED=0010, RWED=0000, E=1101
  2445. This gives the 16-bit quantity:
  2446. 1010001000001101
  2447. This is the internal representation of the VMS file permission; in hex:
  2448. A20B
  2449. as shown in the sample packet above.
  2450. The VMS format probably would also apply to RSX or any other FILES-11
  2451. system.
  2452. I.2. Handling of Generic Protection
  2453. To be used when the two systems are different (and/or do not recognize
  2454. or understand each other's local protection codes).
  2455. First of all, the book is wrong. This should not be the World
  2456. protection, but the Owner protection. The other fields should be set
  2457. according to system defaults (e.g. UNIX umask, VMS default protection,
  2458. etc), except that no non-Owner field should give more permissions than
  2459. the Owner field.
  2460. __________________________________________________________________
  2461. C-Kermit Program Logic Manual
  2462. The Kermit Project
  2463. kermit@columbia.edu
  2464. 30 June 2011