home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / CPM / BDSC / BDSC-3 / STDLIB.DQC / STDLIB.DOC
Text File  |  2000-06-30  |  20KB  |  390 lines
  1.  
  2.                         BDS C Standard Library Summary
  3.                          v1.46 Edition --  March, 1982
  4.  
  5.                                   Leor Zolman
  6.                                   BD Software
  7.                                 33 Lothrop st.
  8.                         Brighton, Massachussetts 02135
  9.  
  10.  
  11.      This document contains an alphabetic summary of ALL general-purpose utiliy
  12. functions  included  in the BDS C package spread among several different source
  13. files.  Note that there  are  quite  a few more functions listed here than than
  14. apppear in the BDS C User's Guide; some  functions  were  intentionally omitted
  15. from the User's Guide for portability reasons, and many others  have  come into
  16. existence since the last revision of the User's Guide.  
  17.  
  18.      The summary is organized by columns.  
  19.  
  20. The  first column shows the type of the result returned by the function.    The
  21. second column shows the calling syntax and parameter types (if not int).  
  22.  
  23. The next  column  shows a code naming the source file in which the function may
  24. be found;  the codes are as follows:  
  25.  
  26.         C1      for STDLIB1.C
  27.         C2      for STDLIB2.C
  28.         D2      for DEFF2.CSM
  29.         D2A     for DEFF2A.CSM
  30.         FLT     for FLOAT.C
  31.         DIO     for DIO.C
  32.  
  33. The next column tells  the  page  number  in  the  BDS C User's Guide where the
  34. function is documented, if the function appears in the User's Guide at all. For
  35. any  function  that  isn't documented in the User's Guide,  there  is  probably
  36. documentation available  in  the  source  listing for that function (the source
  37. location is given in the preceding column.) 
  38.  
  39. The  final  column  contains references to a set  of  footnotes  following  the
  40. function list. If a function has an entry in the NOTE column, the corresponding
  41. footnote (or notes) should  be  examined  for  additional information about the
  42. function.  
  43.  
  44.  
  45. TYPE     FUNCTION                                                 FILE PG NOTES
  46. ----     --------                                                 ---- -- -----
  47.  
  48. int      abs(a,b) int a,b;                                         C1   32
  49. char *   alloc(nbytes) unsigned nbytes;                            C1   37 14
  50. char *   atof(op1,s) char op1[5], *s;                              FLT     1
  51. int      atoi(str) char *str;                                      C1   44
  52. int      bdos(c,de)                                                D2   30 2
  53. char     bios(n,c)                                                 D2   30
  54. int      call(addr,a,h,b,d) unsigned addr;                         D2   32
  55. char     calla(addr,a,h,b,d) unsigned addr;                        D2   32
  56. int      close(fd)                                                 D2   46
  57.          clrplot()                                                 D2A  54
  58. char *   codend()                                                  D2   36
  59. int      creat(filename) char *filename;                           D2   46
  60. char     csw()                                                     D2   30
  61.          dioflush()                                                DIO
  62.          dioinit(&argc,argv) int *argc; char **argv;               DIO
  63.  
  64. BDS C Library Summary, v1.46            1
  65.  
  66.  
  67. char *   endext()                                                  D2   36
  68. int      exec(filename) char *filename;                            D2   34 3
  69. int      execl(filename,arg1, arg2, ..., NULL) char *filename;     D2   35 3
  70. int      execv(filename,argvector) char *filename, **argvector;    D2   35 3,16
  71.          exit(n)                                                   D2   30
  72. char *   externs()                                                 D2   36
  73.          fabort(fd)                                                D2   47 17
  74. char *   fcbaddr(fd)                                               D2   53
  75. int      fclose(iobuf) FILE *iobuf;                                C1   51
  76. int      fcreat(filename, iobuf) char *filename; FILE *iobuf;      C1   50
  77. int      fflush(iobuf) FILE *iobuf;                                C1   51 7
  78. int      fgets(str,iobuf) char *str; FILE *iobuf;                  C2   52 6,11
  79. int      fopen(filename,iobuf) char *filename; FILE *iobuf;        C1   48
  80. char *   fpadd(res,op1,op2) char res[5], op1[5], op2[5];           FLT     1
  81. int      fpcomp(op1, op2) char op1[5], op2[5];                     FLT
  82. char *   fpdiv(res,op1,op2) char res[5],op1[5],op2[5];             FLT     1
  83. char *   fpmult(res,op1,op2) char res[5],op1[5],op2[5];            FLT     1
  84. int      fprintf(format, arg1, arg2, ...) char *format;            C2   51 4,9
  85. char *   fpsub(res,op1,op2) char res[5],op1[5],op2[5];             FLT     1
  86. int      fputs(str,iobuf) char *str; FILE *iobuf;                  C2   53 6,12
  87.          free(allocptr) unsigned allocptr;                         C1   37 14
  88. int      fscanf(iob,fmt,&arg1,&arg2,...) FILE *iob; char *fmt;     C2   52 4,10
  89. char *   ftoa(s1,op1) char *s1; char op1[5];                       FLT
  90. int      getc(iobuf) FILE *iobuf;                                  C1   49 8
  91. int      getchar()                                                 D2   38 20
  92. int      getline(str,maxlen) char *str;                            D2A     18
  93. char *   gets(str) char *str;                                      D2   40 5
  94. int      getval(strptr) char **strptr;                             C1   45
  95. int      getw(iobuf) FILE *iobuf;                                  C1   50
  96. int      index(str,substr) char *str, *substr;                     D2A     18
  97.          initb(array,string) char array[], *string;                C1   44
  98.          initw(array,string) int array[]; char *string;            C1   44
  99. char     inp(port)                                                 D2   31
  100. int      isalpha(c) char c;                                        C1   41
  101. int      isdigit(c) char c;                                        C1   42
  102. int      islower(c) char c;                                        C1   42
  103. int      isspace(c) char c;                                        C1   42
  104. int      isupper(c) char c;                                        C1   41
  105. char *   itoa(str, n) char *str;                                   FLT
  106. char *   itof(op1, n) char op1[5];                                 FLT     1
  107. int      kbhit()                                                   D2   39
  108.          line(c,x1,y1,x2,y2) char c;                               D2A  54
  109. int      longjmp(jbuf) char jbuf[JBUFSIZE];                        D2A
  110. int      max(n1,n2)                                                C1   32
  111. int      min(n1,n2)                                                C1   32
  112.          movmem(source,dest,count) char *source, *dest;            D2   34
  113. int      nrand(n [,prompt] or [,n1,n2,n3]) char * prompt;          D2   33
  114. int      open(filename,mode) char *filename; int mode;             D2   46
  115.          outp(port,val) char port, val;                            D2   31
  116.          pause()                                                   D2   31
  117. char     peek(port) char port;                                     D2   31
  118.          plot(x,y,c) char c;                                       D2A  54
  119. char     poke(addr, val) unsigned addr; char val;                  D2   31
  120.          printf(format, arg1, arg2, ...) char *format;             C2   40 4,9
  121. int      putc(c,iobuf) char c; FILE *iobuf;                        C1   50
  122.          putch(c) char c;                                          D2   39
  123.          putchar(c) char c;                                        D2   39 20
  124.          puts(str) char *str;                                      C2   40
  125.          putw(w,iobuf) int w; FILE *iobuf;                         C1   51
  126.          qsort(base,nel,width,cmp) char *base; int (*cmp)();       C1   34
  127. int      rand()                                                    D2   33
  128.  
  129. BDS C Library Summary, v1.46            2
  130.  
  131.  
  132. unsigned rcfsiz(fd)                                                D2A
  133. int      read(fd, buffer, nsecs) char *buffer;                     D2   47
  134. int      rename(oldname, newname) char *oldname, *newname;         D2   46
  135. int      rread(fd, buffer, nsecs) char *buffer;                    D2A     15
  136. int      rseek(fd, offset, origin)                                 D2A     15
  137. int      rsrec(fd)                                                 D2A     15
  138.          rsvstk(n)                                                 D2   38
  139. int      rtell(fd)                                                 D2A     15
  140. int      rwrite(fd, buffer, nsecs) char *buffer;                   D2A     15
  141. char *   sbrk(nbytes)                                              D2   37
  142. int      scanf(format, &arg1, &arg2, ...) char *format;            C2   42 4,10
  143. int      seek(fd, offset, origin)                                  D2
  144.          setfcb(fcbaddr, filename) char *filename;                 D2   53
  145. int      setjmp(jbuf) char jbuf[JBUFSIZE];                         D2A
  146.          setmem(addr, count, byte) char *addr; char byte;          D2   33
  147.          setplot(base,xsize,ysize)                                 D2A  53
  148.          sleep(ntenths)                                            D2   31
  149.          sprintf(str,format,arg1,arg2,...) char *str, *format;     C2   42 4,9
  150.          srand(n)                                                  D2   32
  151.          srand1(str) char *str;                                    D2   32
  152. int      sscanf(str,format,&arg1,&arg2,...) char *str, *format;    C2   42 10
  153.          strcat(s1, s2) char *s1, *s2;                             C1   43
  154. int      strcmp(s1, s2) char *s1, *s2;                             C1   43
  155.          strcpy(s1, s2) char *s1, *s2;                             C1   43
  156. int      strlen(str) char *str;                                    C1   44
  157.          swapin(filename,addr) char *filename; unsigned addr;      C2   36
  158. int      tell(fd)                                                  D2   48
  159. char     tolower(c) char c;                                        C1   42
  160. char *   topofmem()                                                D2   36 19
  161. char     toupper(c) char c;                                        C1   42
  162.          txtplot(string,x,y,ropt) char *string;                    D2A  54
  163.          ungetc(c,iobuf) char c; FILE *iobuf;                      C1   50
  164.          ungetch(c) char c;                                        D2   39
  165.          unlink(filename) char *filename;                          D2   46
  166. int      write(fd, buffer, nsects) char *buffer;                   D2   47
  167.  
  168.  
  169. NOTES:  
  170.  
  171.  
  172. 1.   This floating point function returns a pointer  to a 5-byte floating point
  173.      object, represented in a character array of length 5.  
  174.  
  175. 2.   The "bdos" function returns HL equal to the value  left  there by the BDOS
  176.      itself.  Under  standard  CP/M,  8-bit  values are returned in  L  with  H
  177.      cleared, and 16-bit values are returned in  HL.  Other "CP/M-like" systems
  178.      do not always follow this convention, though, and  the "bdos" function may
  179.      take rewriting in order to work with certain system  calls  under  systems
  180.      such as "SDOS".  
  181.  
  182. 3.   Unless an error occurs, this function should never return at all.  
  183.  
  184. 4.   Note   that   all  the  upper-level  formatted  I/O  functions  ("printf",
  185.      "fprintf", "scanf",  and  "fscanf")  now  use  "_spr" and "_scn" for doing
  186.      conversions. While this leads to very modularized  source  code,  it  also
  187.      means  that calls to "scanf" and "fscanf" must process ALL the information
  188.      on a line  of  text  if  the  information is not to be lost; if the format
  189.      string runs out and there is still  text left in the line being processed,
  190.      the text will be lost (i.e., the NEXT  scanf  or fscanf call will NOT find
  191.      it.) 
  192.  
  193.  
  194. BDS C Library Summary, v1.46            3
  195.  
  196.  
  197.      An alternate version of "_spr" (the low-level output  formatting function)
  198.      is  given  in  the file FLOAT.C for use with floating point  numbers;  see
  199.      FLOAT.C for details. Since "_spr" is used by "printf", this really amounts
  200.      to an alternate version of "printf." 
  201.  
  202.      Also note that temporary  work  space  is  declared  within  each  of  the
  203.      high-level  functions  as  a  one-dimensional  character array. The length
  204.      limit  on  this  array  is  presently  set to 132 by the   define  MAXLINE
  205.      statement  in  BDSCIO.H;  if you intend to  create  longer  lines  through
  206.      printf, fprintf,  scanf,  or  fscanf calls, be SURE to raise this limit by
  207.      changing the  define statement.  
  208.  
  209. 5.   Note that the "gets" function (which  simply  buffers up a line of console
  210.      input at a given buffer location) terminates the  line  with  a  null byte
  211.      ('\0') WITHOUT any CR or LF.  
  212.  
  213. 6.   The  conventional  CP/M  text  format calls for each line in a file to  be
  214.      terminated by a carriage-return/linefeed  combination.  In  the world of C
  215.      programming,  though,  we like to just use a single linefeed (known  as  a
  216.      "newline") to terminate  lines.  AND  SO,  the  functions  which deal with
  217.      reading  and  writing text lines from disk files to memory and  vice-versa
  218.      ("fgets", "fputs")  take  special pains to convert CR-LF combinations into
  219.      single '\n' characters when  reading from disk ("fgets"), and convert '\n'
  220.      characters to CR-LF combinations  when  writing  TO  disk  ("fputs"). This
  221.      allows the C programmer to do things in style, dealing only  with a single
  222.      line  terminator  while  the text is in memory, while maintaining  compat-
  223.      ibility with the CP/M text  format for disk files (so that, for example, a
  224.      text file can be "type"d under the CCP.) 
  225.  
  226. 7.   Remember to put out a CPMEOF  (control-Z  or 0x1a) byte at the end of TEXT
  227.      files being written out to disk.  
  228.  
  229. 8.   Watch out when reading in text files using  "getc".  While  a text file is
  230.      USUALLY terminated with a control-Z, it MAY NOT BE if the file  ends on an
  231.      even  sector boundary (although respectable editors will now usually  make
  232.      sure the  control-Z  is  always  there.)  This  means  that  there are two
  233.      possible return values from "getc" which can signal an End-of file: CPMEOF
  234.      (0x1a)  or  ERROR (-1, or 255 if you assign it to a char variable)  should
  235.      the CPMEOF be missing.  
  236.  
  237. 9.   Since the "_spr"  function  is  used  to  form the output string, and then
  238.      "puts"  is used to actually print it out, care  must  be  taken  to  avoid
  239.      generating  null  (zero)  bytes  in  the  output,  since  such a byte will
  240.      terminate printing of the string by puts. Thus, a statment such as:  
  241.      
  242.                      printf("%c foo",'\0');
  243.  
  244.      would not actually print anything at all.  
  245.  
  246. 10.  The "%s" termination character has been changed from "any white  space" to
  247.      the character following the "%s" specification in the format string.  That
  248.      is, the call 
  249.      
  250.                      sscanf(string, "%s:", &str);
  251.  
  252.      would  ignore  leading  white  space  (as  is  the  case  with  all format
  253.      conversions),  and  then  read in ALL subsequent text (including newlines)
  254.      into the buffer "str" until a COLON or null byte is encountered.  
  255.  
  256. 11.  fgets  is  a  little  tricky due  to  the  CP/M  convention  of  having  a
  257.      carriage-return AND a linefeed character at the end of every text line. In
  258.  
  259. BDS C Library Summary, v1.46            4
  260.  
  261.  
  262.      order to make text easier  to  deal  with  from  C programs, this function
  263.      (fgets) automatically strips off the CR from any CR-LF  combinations  that
  264.      come in from the file. Any CR characters not immediately followed by a  LF
  265.      are left intact. The LF is included as part of the string, and is followed
  266.      by  a  null  byte.  There is no limit to how long a line can be here; care
  267.      should be taken  to make sure the string pointer passed to fgets points to
  268.      an area large enough  to  accept  the largest expected line length (a line
  269.      must be terminated by a newline (LF)  character  before  it  is considered
  270.      terminated).  
  271.  
  272.      The  value  NULL,  NOT  EOF, is returned on end-of-file, whether it  be  a
  273.      physical end-of-file (attempting  to read past last sector of the file) OR
  274.      a logical end-of-file (encountered a control-Z.) 
  275.  
  276. 12.  The "fputs" function writes a string  out  to  a buffered output file. The
  277.      '\n' character is expanded into a CR-LF combination,  in  keeping with the
  278.      CP/M convention. If a null ('\0') byte is encountered before  a newline is
  279.      encountered,  then  there  will  be  NO  automatic  termination  character
  280.      appended to the line, thus allowing partial lines to be written.  
  281.  
  282. 13.  When  managing  overlays,  the  "swapin"  function may be used by the root
  283.      segment to swap in overlay code segments from  disk.  The provided version
  284.      does NOT check to make sure that the code yanked  in  doesn't overlap some
  285.      data areas that may lie above the swapping area in memory.  
  286.  
  287. 14.  The  storage allocation routines were taken from chapter  8  of  K&R,  but
  288.      simplified  to  ignore  the storage allignment problem and not bother with
  289.      the "morecore" hack (a call  to  "sbrk"  under  CP/M is a relatively CHEAP
  290.      operation,  and  can  be done on every call to "alloc"  without  degrading
  291.      efficiency.) Note that compilation of "alloc" and "free" is disabled until
  292.      the " define ALLOC_ON 1"  statement  is  un-commented  in  the header file
  293.      ("BDSCIO.H"). This is done so that the external storage required  by alloc
  294.      and free isn't declared unless the user actually needs the alloc and  free
  295.      functions.  
  296.  
  297. 15.  The  random-record  file  I/O  functions  are  a  direct  interface to the
  298.      random-record BDOS functions provided by CP/M versions 2.0  and above, but
  299.      not available for pre-2.0 CP/M systems. Because of the non-portability  of
  300.      these functions, they have not been heavily advertised in the BDS C User's
  301.      Guide  (i.e.,  they  are  not  mentioned  at  all). The "rread", "rwrite",
  302.      "rseek"  and  "rtell"  functions  work  just  like the  functions  "read",
  303.      "write", "seek" and "tell", respectively, except  that  they do things via
  304.      the  random-record  fields  of  the  file's FCB. The "rsrec" and  "rcfsiz"
  305.      function simply take a file descriptor  of  an open file and perform their
  306.      namesake  BDOS  operation on the given file, but  in  addition  they  also
  307.      return the value  computed.  Thus, "rcfsiz" may be used to quickly compute
  308.      the size of a file under CP/M 2.x.  
  309.  
  310. 16.  The  "execv" function no longer  prints  out  "Broken  Pipe"  upon  error;
  311.      instead, it has the more conventional behavior of returning -1 (ERROR) and
  312.      letting the user perform diagnostics.  
  313.  
  314. 17.  "fabort"  should  not be used under systems like MPM-II in which all files
  315.      MUST be closed, whether they are open for input or output, in order not to
  316.      run out of file descriptors and hang the system.  
  317.  
  318. 18.  New for v1.46 (see the v1.46 documentation addenda sheet for details.) 
  319.  
  320. 19.  Modified for v1.46  to  detect  when  "NOBOOT"  has  been  invoked  on the
  321.      currently  executing program, and return an adjusted value for the end  of
  322.      available user-memory.  
  323.  
  324. BDS C Library Summary, v1.46            5
  325.  
  326.  
  327. 20.  When the DIO  package  is  linked  in  to a program, alternate versions of
  328.      "getchar" and "putchar", whose sources are in DIO.C, get used.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389. BDS C Library Summary, v1.46            6
  390.