.title printf Formatted print routine .ident /000008/ ; ;+ ; ; Index Formatted output ; ; Usage ; ; printf(format, arg1, ...) ; char *format; ; ; fprintf(iov, format, arg1, ...) ; FILE *iov; ; char *format; ; ; char * ; sprintf(buffer, format, arg1, ...); ; char *buffer; ; char *format; ; ; $$prnt(format, argvec, iov) ; char *format; ; int *argvec[]; ; FILE *iov; ; ; Description ; ; printf() converts, formats, and prints its arguments, under control ; of the first argument, writing output via putchar(). fprintf() ; writes its output to the indicated file. sprintf() writes its ; output to the indicated string buffer. $$prnt() is the internal ; print formatter which is called by printf, etc. ; ; sprintf() returns a pointer to the EOS at the end of the output ; buffer. This is not necessarily transportable. ; ; The format argument is a character string which contains two ; types of objects: plain characters, which are simply copied ; to the output stream, and conversion specifications, each of ; which causes conversion and printing of the next successive ; argument to printf. ; ; Each conversion specification is introduced by the character %. ; Following the %, there may be ; ; - an optional minus sign "-" which specifies left ; adjustment of the converted argument in the indicated ; field. ; ; - an optional digit string specifying field width; if ; the converted argument has fewer characters than the ; field width, it will be blank-padded on the left (or ; right, if the left-adjustment indicator has been ; given) to make up the field width. If the field ; width is specified as '*' or '?', the next argument ; is used. (Note: '?' is obsolete.) If the width is ; specified with a leading zero, zeros are used for ; padding instead of blanks. This zero does NOT imply ; an octal field width. For example, assume the value ; 123 is to be printed: ; %d "123" ; %5d " 123" ; %-5d "123 " ; %05d "00123" ; ; - an optional period "." which serves to separate the ; field width from the next digit string; ; ; - an optional digit string (precision) which specifies ; the number of digits to appear after the decimal ; point for e- and f-conversion, or the maximum number ; of characters to be printed from a string. If the ; precision is specified as '*' or '?', the next ; argument is used. ; ; - a character which indicates the type of conversion ; to be applied. ; ; The conversion characters and their meanings are ; ; d Signed-decimal ; u Unsigned-decimal ; o Octal ; X Hexadecimal, 10-15 are represented by A-F ; x Hexadecimal, 10-15 are represented by a-f ; ; The integer argument is converted to decimal, ; octal, or hexadecimal notation respectively. ; Any of the conversion characters may be ; preceeded by 'l' to signal "long" integer ; argument. Note that the Unix usage of capital ; letters to represent long arguments is not ; supported. ; ; Note ; ; In order to eliminate the very large ; floating point conversion routines from ; most programs, a program which requires ; floating point conversion must request ; the double to ascii conversion routine ; explicitly. The following sequences ; show how this is done: ; ; RSX: TKB task=source,LB:DTOA,LB:C/LB ; RT11: LINK source,C:DTOA,C:SUPORT,C:CLIB/BOT:2000 ; ; If this is not done, any use of the %f ; %e, or %g conversions will result in an ; error message. On RSTS/E, the library ; build procedure creates RTDTOA.OBJ and ; RXDTOA.OBJ in the library account. ; ; ** Floating point support has not yet ** ; ** been fully implemented. The float ** ; ** or double value must be the last ** ; ** or only argument to printf. Only ** ; ** single-precision conversion is ** ; ** presently available. ** ; ; f The argument is converted to decimal notation ; in the style "[-]ddd.dd" where the number of d's ; after the decimal point equals the precision ; specification for the argument. If precision is ; missing, 6 digits are given; if explicitly 0, no ; digits and no decimal point are printed. The ; argument should be float or double. "%lf" or ; "%F" must be used to signal "long (i.e. double) ; argument." This is a restriction of Decus C. ; ; e The float or double argument is converted in the ; style "[-]d.ddde+-dd" where there is one digit ; before the decimal point and the number after is ; equal to the precision specified for the ; argument; if the precision is missing, 6 digits ; are produced. "%le" or "%E" must be used to ; signal "long (i.e. double) argument." This is a ; restriction of Decus C. ; ; g Floating point: "%f" format if suitable, else ; "%e" format. "%lg" or "%G" must be used to ; signal "long (i.e. double) argument." This is a ; restriction of Decus C. ; ; c The argument character is printed. (Note that ; 'lc' takes a long integer argument.) ; ; r Remote format. The next printf() argument is ; the format. Note that this is not a subroutine. ; The current format is not processed further. For ; example: ; ; bug(args) ; { ; error("Error at %r", &args); ; } ; ; This routine might be called as follows: ; ; bug("Error %d at %s\n", val, name); ; ; %r is not transportable to all implementations ; of the standard library. It does not word on ; Vax-11 C, for example. $$prnt may be used ; as shown below for similar functionality. ; ; s The argument is taken to be a string (character ; pointer) and characters from the string are ; printed until a null character or until the ; number of characters indicated by the precision ; specification is reached; however if the ; precision specification is 0 or missing all ; characters up to null are printed. ; ; If no recognizable character appears after the %, that character ; is printed; thus % may be printed by the use of the string %%. ; In no case does a non-existant or small field width cause truncation ; of a field; padding takes place only if the specified field ; width exceeds the actual width. Characters generated by printf() ; are printed by calling putchar(). ; ; $$prnt() is the internal print formatter called by all ; "top-level" print functions. It is functionally identical ; to the Unix and Vax-11 C _doprnt() library routine. Unfortunately, ; the leading '_' conflicts with RSX-11M file services library ; routine conventions, requiring the use of the Decus C unique ; "$$" prefix. If your programs wish to call $$prnt, ; a potentially transportable procedure would be: ; ; #ifdef decus ; $$prnt(format, args, iov); ; #else ; _doprnt(format, args, iov); ; #endif ; ; You should assume, however, that _doprnt() is not necessarily ; present on all implementations of the "standard library." ; ; Bugs ; ; e, f, and g conversion only work for single-precision floating ; point. Use of "%lf" etc. is not transportable and may change. ; It may also cause problems in the C compiler (as the standard ; says that subroutine calls take double (not short floating) ; arguments. ; ;- ; ; Edit history ; 000001 02-Jul-82 MM Totally redone. ; 000002 03-Aug-82 MM .doprnt -> $$prnt ; .psect c$code printf:: jsr r5,csv$ ; Link environments mov stdout,-(sp) ; filedes mov #C$PMTR+2,-(sp) ; offset to first arg add r5,(sp) ; -> first arg mov C$PMTR+0(r5),-(sp) ; format call $$prnt ; $$prnt(format, args, fildes) ;02 jmp cret$ ; exit .end