---

Easy C++ Manual

Copyright © ProAction and APDL, 2001

EasyC Make

If you are developing a large application which uses a number of source files which in turn are dependant on a number of header files, it is very time consuming to re-compile all files after each change that you make. Clearly you need only recompile those files that have changed or whose dependants have changed. To do this manually is prone to mistakes e.g. you might change a header file but forget to recompile one of the source files that is dependant upon it.

The Make facility resolves all these problems by using a 'make file' which lists all the source files and their dependencies. You need only click on a button for it to make your program. Only those files that have changed or whose dependencies have changed (such as header files) are recompiled and then everything is linked. The Make facility recognises which files have changed by checking their date and time stamps.

Easy C has a facility to create a make file automatically for you. You need only tell it which source files are needed by your application, and it will work out the dependencies and create a make file.

Dhrystone

The best way to illustrate the use of the Make facility is to use a real example. On the Easy C disc in directory $.Programs is a directory called Dhrystone containing a popular test program for C compilers. This directory contains all the files associated with the Dhrystone project, including directory c containing the source files dhry_1 and dhry_2, and directory h containing the header file dhry. Both source files 'include' h.dhry, and are therefore dependent upon it.

Please note that you should create a new directory for each project that you wish to make e.g. Dhrystone. It should contain c, o and h directories and the make file for that project. Do not mix projects in a single directory.

Creating the 'make file'

For the Dhrystone example, drag the source files c.dhry_1 and c.dhry_2 into the source window. If there are any files already in the source or object windows, remember to clear them by holding down Ctrl whilst dragging. Now click on Create to create the make file. When complete, the pathname of the make file is placed in the icon beneath the source and object windows.

The make file it creates is called Makefile and is placed in the same directory as the c and o directories. If a make file already exists in this directory, you will be asked for confirmation before it is overwritten.

Normally the object window should be empty when you create a make file. However, if your application needs to link in a separate object file, you should drag it into the object window before using Create.

Please note that when creating a make file, all source files must be in the same c directory, otherwise an error will be reported. Any additional object files you require, must be in the corresponding o directory.

Using Make

Once Dhrystone has been 'made', if you try and make it a second time the message dhry_1 is up to date will be displayed. If you modify any of the source or header files, or delete the object or executable files, clicking on Make will intelligently recompile anything that has changed or is missing, and then link the program again. A quick way of testing this is to 'stamp' one of the source files using the Stamp option on the source window menu, then click on Make.

Make options

The Make option on the main Easy C menu displays a dialogue box from which the make facility may be configured.

Target

This is used to specify which target you wish to make. In a standard make file there is only one target, so this option can normally be ignored. However, it is possible to edit the make file directly and add other targets, which may be used to make special versions of the program. In this case you should enter the the target name in the icon provided.

Ignore

If this option is selected, the make facility will continue compiling and linking after any errors are reported.

Silent

This option controls whether the make facility echoes in the error window the commands that it generates to compile and link programs. If Silent is selected, the commands are not echoed.

Trace

If Trace is selected, the make facility echoes the compile and link commands tin the error window, but does not execute them. This feature is useful for checking that the make facility is generating the correct sequence of commands. The Silent option described above must not be selected for the Trace option to work.

Use setup

If this option is selected the make facility will use the settings from the Setup dialogue box. This means that the settings in this dialogue box will affect the make operation. For example, if List is selected in the Setup dialogue box, a listing will be generated during the compile part of the make operation. This is the default situation, and will be satisfactory for most purposes.

However, there may be situations where you do not wish to change the settings on the Setup dialogue box, but do want the make file to compile or link using a specified set of qualifiers. To do this you will need to de-select Use setup. Normally the setup options are passed to the make facility using the macros CFLAGS and LDFLAGS. If Use setup is not selected, these macros will be blank, so you should set them at the start of the make file with your own settings. For more information, see the sample make file given on the next page.

Make file format

# Lines starting with # are comments.
# Makefile generated by Easy C
#
# This makefile builds the following files:
#   c.dhry_1
#   c.dhry_2
# The next line defines a macro OBJS which lists all the 
# objects needed by the program. 
OBJS = o.dhry_1 o.dhry_2
# If c.dhry_1 and c.dhry_2 are modified, they are recompiled
# automatically using default rule cc $(CFLAGS) $* -desk.
# The macro CFLAGS is set by the Setup dialogue box, but may
# be redefined if required.
# The next line defines the target dhry_1 which consists of
# the objects specified by the OBJS. You may add other targets
# if you wish e.g. to make special versions of the program.
# The action needed to make the target is to link the objects.
# The macro LDFLAGS is set by the Setup dialogue box, but may 
# be redefined if required.
dhry_1 : $(OBJS)
         $(LINK) $(OBJS) $(LDFLAGS) -desk
# The next two lines state the the files dhry_1 and dhry_2 
# need to be recompiled if the header files are modified.
# The recompilation is done automatically by default rules.
o.dhry_1 : h.dhry
o.dhry_2 : h.dhry
#
# End of generated makefile, add other dependencies here
#

You may add commands to the make file to carry out special tasks, for example to delete the object files after linking. However, to do this you must tell the command line interpreter where the files are on disc. This is done using the special macro $(MPATH) which expands to the pathname of the directory containing the c and o directories. To delete all object files after linking, add this line after the link line and resave the make file:

wipe $(MPATH).o.* ~c

We have yet to test the make facility fully with C++, and so would welcome any feedback (good or bad).

Let's take a look at a simple C program called HelloW:

/* HelloW - print hello, world */
#include <stdio.h>
int main(void)
}

There are several points to note here:

  C does not use line numbers.

  Lower case characters are used for C keywords and (conventionally) for user-defined words such as variable names and function names.

  A number of non-alphabetic characters such as curly braces (), hash sign (#) and asterisk (*) have special meanings in C.

Taking the program line by line, we find the following:

Line 1 in the source code above is enclosed in comment delimiters. Anything which appears between the /* and the */ is ignored by the compiler. Good programmers use this facility to explain how their code works.

Line 2 starts with the # character. This makes it a preprocessor directive, and is the first phase of the compilation. It tells the preprocessor to find a header file called stdio.h and treat it as part of this program. This file contains information relating to the standard input and output routines, and hence its name stdio. On finding this directive, the C compiler looks for a file stdio in directory h. This naming convention is the opposite way round to normal Acorn conventions, but allows portability between C compilers running under different operating systems.

Line 3 is the name of the function. All C programs must have a function called main(), and execution of the program starts here. The words int and void will be explained in due course.

Line 4 is an opening brace ( printf() is NOT a C command, but a call to a library function called printf(), which prints the string enclosed in quotes. The character pair \n represents 'new line', and note how this is also included within the quotes. Note also how the statement ends with a semi-colon.

Line 6 marks the end of the function, and in this case the end of the program.

This source code is used as input to the C compiler. The preprocessor copies in any #included files, and the expanded file is input to the compiler proper which will (compilation errors permitting) produce an object file which must be linked to produce a program. To run the compiled program, double-click on HelloW to display the message hello, world.

HelloW is a very simple program; it uses no variables and there is no flow control. The expanded program HelloW2 below, incorporates both of these features.

/* HelloW2 - hello, world expanded version */
#include <stdio.h>
int main(void)

  for (x = 0; x < 10; x = x + 1)
    printf("hello, world %d\n", x);
}

The next line features a construction dear to any Basic programmer's heart - the FOR/NEXT loop.

The printf() function now has a more complicated structure than hitherto, containing as it does two arguments: the string "hello, world %d\n" known as the conversion string, and the variable x. The string contains literal text which is printed as it appears, plus formatting information to control the conversion (i.e. the format) of x. The %d tells the function to output its next argument as a decimal integer at this point on the printed line.

Unlike Basic's PRINT statement, printf() is a complicated beast and will be discussed in more detail as we proceed.

Iteration - the for loop

In C, for() works in very much the same way as the Basic equivalent, but is much more flexible. The general format is:

for ( expr1; expr2; expr3 ) statement

FOR N%=0 TO 9 STEP 1
PRINT "hello, world "N%
NEXT

for (x = 0, y = 1023; y >= 0 && point(x,y) == 0; x++, y--)

x = 0, y = 1023 assigns starting values to x and y. The comma separator may be used as both assignments formpart of expr1.

y >= 0 && point(x,y) == 0 can be expressed as 'while y is greater than or equal to 0 and the function point(x,y) returns the value 0'. The double ampersand && is the logical AND operator. In C, == serves as the equality test (IS equal to), as opposed to the single = (BECOMES equal to), for assigning values. The function call point(x,y) is evaluated after the test on y, and only if it is TRUE.

Lastly, x++, y-- means add 1 to x and subtract 1 from y (see below)

Optional parameters

While just the STEP clause is optional in Basic, everything is optional in for(). If you examine a few C programs you will often see 'empty' for() loops, where all the work is done in the 'reinitialise' expression, for example:

for ( m = 1; n > 0; m *= n--)
  ;

for( ; m < 10; ) /* no initialise or reinitialise */
for( ; ; )
  /* start of an infinite loop */

Incrementing and decrementing variables by one occurs so often that it gets its own operators; ++ and --. They can go before the variable (prefix) or after it (postfix). Prefix increment means 'add 1 to the current value, then use it'; postfix means 'use the current value then increment it'. For example:

x = 7;
  /* x is initialised */
y = 4 * ++x;
  /* x is incremented first, so y = 32 */
z = y--;
  /* z becomes 32, y becomes 31 */

The notation *= used above may be familiar to Basic V programmers who can use the related += and -=. In general, the notation:

A <op>= B

A = A <op> B

The root of the problem

This section describes a C program to calculate the square root of a number. We present the program here in its entirety before discussing its individual features. In particular, the example illustrates the use of some of C's flow control commands, and the use of variables.

/* Root - calculate the square root of a number */

#include <stdio.h>
#define ACCURACY 1.0E-6
double sqt(float);
int main(void)

  printf("give me a number; ");
  scanf("%f", &n);
  while(n != 0)
  
    printf(" square = %f", n*n);
    if(n > 0)
      printf(" root = %f \n", sqt(n));
    else
      printf("Negative - no real root\n");
    printf("give me a number; ");
    scanf("%f", &n);
  }
}


double sqt(float num)

  acc=ans=num/2.0;
  while(ans > 0 && acc > ACCURACY) 
  
    acc=num - (ans*ans);
    if(acc < 0)
      acc = -acc;
  }
  return ans;
}

The fourth line is a function prototype; it tells the compiler that the function sqt() exists in the program which returns a value of type double, and takes one parameter of type float. Double stands for 'double precision floating point'. Specifying a prototype allows the compiler to check that all calls to the function have the right number and type of parameters. For the purpose of this example the function has been called sqt() to avoid a name clash with the function sqrt(), which is supplied as standard with all implementations of C.

As a function itself, main() has a return type of int (normally for returning an integer error code). It has no parameters, so you must put void where the arguments would normally go.

After the opening brace which marks the start of the program proper, the variable n of type float is defined. This is followed by a simple printf() to ask the user for input, and a call to scanf(), which is the C equivalent of Basic's INPUT. scanf() takes as its arguments a conversion string (%f in the above example) and the address(es) of where the inputted data is to be placed; &n means 'the address of n'. We'll be looking at addresses and pointers in detail later. Strictly speaking, scanf() fetches the data from the standard input stream, but this will normally be the keyboard.

Then a new iterative construct called while(), which is similar to WHILE in Basic. The expression in brackets after is evaluated and if it is TRUE (or non-zero) the group of statements is executed. This process repeats until the expression evaluates as FALSE (or zero). The line while(n != 0) means while n is NOT equal to 0, so the loop is only executed if a nonzero value is entered.

On the next two lines, the value entered and its square are printed. Then the value of n is tested using the if() statement. It works much like the Basic equivalent; if the expression evaluates as TRUE (non-zero), the statement (or group of statements) is executed, otherwise the statement(s) following the optional else are executed. Processing continues from the statement after the else statement. In this case, if n is negative, a message is printed, otherwise we print the value returned by the function sqt() with n as its parameter (%f is the floating point equivalent of %d, by the way). To evaluate this, C passes a copy of the value held in n (call by value, an important property of C), executes the statements in sqt() and comes back with the calculated answer. The loop ends with another prompt for input, and processing continues until the user enters zero. The program terminates at the closing brace of main().

sqt() is a separate function, and starts as all functions must, with its return type, its name, and any parameter declarations (naturally, the definition of a function must agree with its prototype at the start of the program). In this case the return type is double, its name is sqt(), and its one parameter num is of type float. In our example, num will contain a copy of n. At the start of sqt() some more variables are defined and initialised. These variables are local to the function, and are called into existence for the duration of each call. The variable ans, for example, doesn't exist as far as main() is concerned. Nor does it retain its value between calls. Note the technique for assigning a value to more than one variable.

The first statement of sqt() is another while loop. In this case, the loop will repeat as long as ans is greater than zero AND our accuracy requirements are not met (note the && for the logical AND in C, as opposed to the single & for bitwise AND). The test for zero is to avoid a divide by zero within the loop. Unlike Basic, C can't trap this for you tidily. At the end of the loop, acc is made positive, in an operation equivalent to Basic's ABS function.

The sqt() function uses an iterative method for obtaining a root, and this consists of refining a guess at the square root of num until the required accuracy is attained. Try out the arithmetic with a calculator if you like; the arithmetic operators and brackets within the loop mean the same as in Basic. When either condition is satisfied, the function sends the answer back with return(ans). The value so obtained is passed to printf() for display upon the screen.

If you compile and run the program you will find a limitation C shares with Basic; floating point numbers are held to an accuracy of about nine digits, which causes inaccuracies in the least significant digits of large numbers. This may be avoided by checking that the user's input is both positive and less than a certain threshold, by changing the if statement in main() to read:

if(n > 0 && n <= MAXNUM)
  printf(" root = %f \n", sqt(n));
else
  printf("Negative or too big - can't do\n");

We'll return to sqt in the future, and refine it to reduce its limitations.

Character handling

REM Basic put "B" in new$
num1%=ASC("A"): num2%=num1%+1
new$=STR$(num2%)

/* C put "B" in new */
int num1, num2;
char new;
num1='A'; 
num2=++num1;
new=num2;

/* put "B" in new - version 2 */
char new='A';
new++;

It could be said that C's characters operate in much the same way as Basic's byte indirection while strings, being arrays of characters, are like Basic's $ indirection. This is where an area is set aside in the program to hold (in our case) a string:

DIM mess 50       : REM reserve 50 bytes for string
$mess="Hello mum" : REM insert data
PRINT $mess       : REM behaves like a string variable
mess?5=13         : REM insert return at 6th char
PRINT $mess       : REM result would be "Hello"

char str[50];             /* reserve 50 chars */
strcpy(str, "Hello mum"); /* copy message in */
printf("%s\n", str);      /* print our message */
str[5]='\0';              /* insert null character */
printf("%s\n", str);      /* print result, "Hello" */

The nth element of an array is accessed as str[n-1]. However, there is another useful notation which exploits one of C's most powerful tools. C is a high-level language which allows complicated operations to be programmed in a small amount of human-readable code. However, it shares some characteristics with assembly languages, one of which is the ability to use the address of something, as well as its value. The address of an array is held in a special variable called a pointer. Pointers, like ordinary variables, must have types; in the example above the type is char. In fact, str itself is a pointer which holds the address of str[0]. The address of str[1] may be expressed as str+1, and so on.

The arguments passed to printf() and strcpy() are actually pointers to char. You can declare free-standing pointers like this:

int n;   /* ordinary variable */
int *ip; /* pointer to int */

ip = &n;              /* ip points to n,
                         & means 'the address of' */

*ip = 5;              /* the same as 'n = 5;'
                         '*' means the "value at the location pointed to by" */
nsquared= *ip * *ip;  /* multiply 5 times 5 */
printf("%d", *ip);    /* print 5 */

str[5]='\0';

*(str + 5) = '\0';

char str[512];
char *temp;                     /* pointer to char */
scanf("%s", str);               /* str is the address of */
for(temp = str; *temp; temp++)  /*the start of the array */
  ;
printf("this string is %d chars long\n", temp - str);

The only legal arithmetic operation involving two pointers is subtraction and the result is only defined when they point to the same array. The result of such a subtraction is the number of elements lying between the two pointers, plus 1. So if p1 and p2 point to adjacent elements in an array, the expression p2 - p1 evaluates to 1.

Pointers and arrays

int two_dim [12] [31];

int monthtotal(int daily_figs[])

  for(n = 0, total = 0; n < 31; n++)
  total += daily_figs[n];
  return total;
}

int jan_figures[31];
int year_1990 [12] [31];
int decade_80_89[10] [12] [31];
jan_total=monthtotal(jan_figures);
for(n = 0; n < 12; n++)
  printf("Month %d total = %d\n", n, monthtotal(year_1990[n]));
for(y = 0; y < 10; y++)

  for(n=0; n<12; n++)
    printf("Month %d total = %d\n", n,
              monthtotal(decade_80_89[y][n]));
}

In passing, you may have spotted the arithmetic expression 1980 + y in one printf() statement. As with Basic's PRINT expression arguments are evaluated before the call to printf() actually takes place. In general, wherever C expects an object, it will be quite happy with an expression which has a result of that type.

The function monthtotal above could be made more useful if it didn't always have to add 31 elements. A more generally useful version would add as many elements as we liked, any time we called it, and I suspect it would use pointer notation. Before we start, however, some design considerations.

How do we specify which elements to add? The array could terminate with an agreed end-of-array value, just as strings always end in the NULL character. This would be awkward, as almost any value might reasonably appear in an integer array. One could use the implementation-defined maximum integer value, INT_MAX which is #defined in limits.h, but what if you want to add a part total, for example a weekly total within the monthly figures above? You would have to insert INT_MAX in your array, call the function and then restore the original value. A second approach is to specify how many elements to add, passing this as an argument to the function. This imposes fewer restrictions on the input, and is probably the best solution for our purposes. Observe:

/* arraytotal - accumulate n elements from an array of ints */
int arraytotal(int *a, int n)

  while( n-- > 0)
  total += *(a++);
  return total;
}

Calling the function is done in exactly the same fashion as before, except that we must specify the number of elements to add:

jan_total=arraytotal(jan_figures, 31);
for(n=0; n<12; n++)
  printf("Month %d total = %d\n", n,
            arraytotal(year_1990[n], 31));
week1_figs = arraytotal(jan_figures, 7);

week2_figs = arraytotal(jan_figures + 7, 7);

year_total = arraytotal(year_1990, 31*12);

Files

A file is viewed as a stream of characters, hence my references to the standard input stream and so earlier in the chapter. All input and output is actually done through streams. When a C program is run, three streams are immediately opened - the standard input (stdin), standard output (stdout) and standard error ( stderr) streams. stdin is normally assigned to the keyboard, stdout and stderr to the screen, but can be redirected, for example, to take input from a file. More of this later.

The Basic programmer will feel almost at home with the fopen() command:

fp = fopen(filename, mode);

infile = fopen("$.scores", "r+");       /* open file '$.scores' for update */

FILE *infile;

Once the file has been opened, there are a number of ways of getting data into and out of it, including:

fgetc(), fscanf(), fread(), fgets()  various input functions
fputc(), fprintf(), fwrite(), fputs()  various output functions
ftell(), fseek(), rewind()  manipulate file pointer

fgetc() and fputc() are very much like BGET# and BPUT#, which you'll no doubt have come across in your Basic programming. We're going to use them to read and write strings in Basic file format. This will be useful if, like me, you have huge amounts of data generated by Basic programs and your future development strategy involves C.

Back to basics first. In Basic, as we have already discussed, a string consists of zero to 255 bytes preceded by two other bytes. The Basic file format reflects this:

Byte    0  1
  
2
  
3
  
4
  
5
  
6
  
7
  
8
  
9

Hex
    
00
  
08
  
64
  
72
  
61
  
77
  
6B
  
63
  
61
  
42

Alpha
  
-
  
-
  
d
  
r
  
a
  
w
  
k
  
c
  
a
  
B

The object of the first exercise is to write a function which will read a string from a file into a character array. The sequence of operations is as follows:

1.  Fetch the string length, l.

2.   Fetch l characters into our array, last one first.

3.  Terminate said array with a null character.

For now we'll assume the file is opened and closed in another function such as main().

/* read_bstring - read a string from a Basic-format file and place in str */
void read_bstring(FILE *in, char *str)

  n=fgetc(in);  /* zero */
  n=fgetc(in);  /* string length */
  str[n--]='\0'; /* insert terminator */
  while(n >= 0)
  *(str + n--) = (char)fgetc(in);
}

Of course, no physical operation such as reading files can be foolproof; faulty discs and corrupt data must be catered for. The function feof() returns TRUE if end-of-file is reached, and the function ferror() returns TRUE if a file error has occurred. These could be incorporated into the while statement thus:

while(n >= 0 && !feof(in) && !ferror(in))

if(n == -1)   /** valid exit from 'while':
  return str;
else
  return 0;

Here is a complete program Bstring, which alls read_bstring():

/* Bstring - read and display a file full of Basic-format strings */
#include <stdio.h>
#include <stdlib.h>
char *read_bstring(FILE *, char *);
int main()

 char b_string[256];
 in=fopen("Bstrings", "r");
 if(!in)
   exit(1);
 }
 while(read_bstring(in, b_string))
 printf("%s\n", b_string);
 if(!feof(in))
   printf("Some sort of file error.");
 fclose(in);
}

The only other odd lines are the if after fopen() and the while beneath it. Both of these evaluate something which will be NULL if an error has occurred; the if reads as 'if file-pointer in is not set', and the while reads as 'while read_bstring returns a non-null value'. This is quite common in C programs.

Introducing structures

First of all, the notation: to define a structure you simply list all the constituent parts in braces, like this:

struct example 
  char address[4][30];
  int age;
  float height, weight;
  };

struct example details;

details.age

details.age = this_year - year_of_birth;
strcpy(details.name, "Peter Pan");
scanf("%s", details.address[i]);

Structures are often used in arrays. The notation is a logical extension of the simple arrays we've already met:

struct example details[10];     /* defines 10 structures */
details[n].age = days_old / 365;
scanf("%s", details[n].address[i]);

Naturally enough, you can also use pointers to access structures. This leads to some fun and games in the notation department:

struct example details[10], *ex;  /* define an array and a pointer */
ex = &details[n];
(*ex).weight = weight_in_ounces / 16;

To get round this a special operator, known as the structure pointer operator is used. In our example:

(*ex).weight

ex->weight 

Naturally, you can have pointers within a structure, but what surprises many people is that a structure can contain pointers to the structure itself. One important application of this idea is in the linked list. In essence, the structure has three components:

struct line_data
  struct line_data *prev; /* pointer to prev line */
  struct line_data *next; /* pointer to next line */
  };

p->prev->next = p->next; 
p->next->prev = p->prev;

struct line_data *first;   /* set and maintained
                              during the program */

while(p->prev != NULL)
  p = p->prev;
p=first;
do
  p = p->next;
  }
while(p != NULL);

struct example 
  char address[4][30];
  int age;
  float height, weight;
  struct example *older, *younger;
  };

Formatted input and output

The functions under discussion consists of fprintf() and fscanf(), which transfer data to and from files, and sprintf() and sscanf(), which format data within the program's memory. Variable argument variants of these (vprintf() and so on), are also available, but will not be discussed here.

In general, printf(), scanf() etc. take a variable number of parameters one of which is known as a format control string. This effectively tells the function how many arguments have been passed to it, and controls the way in which they are processed. Because of this, its important that the number and type of arguments agrees with the format string, or dire consequences may result. The prototypes for these functions are:

int printf(char *format, ...);
int fprintf(FILE *fp, char *format, ...);
int sprintf(char *str, char *format, ...);
int scanf(char *format, ...);
int fscanf(FILE *fp, char *format, ...); 
int sscanf(char *str, char *format, ...);

The format string may contain any sequence of characters. These are simply copied to the output stream until a % or \ is encountered. The backslash introduces an escape sequence - an otherwise unprintable character, such as Newline (\n), Formfeed (\f), and so on. The percent sign marks the beginning of a conversion string. When printf() encounters a % it converts the next argument according to the characters following the percent sign. You've already met %s for strings (strictly, pointers of type char) and %d for decimal integers.

Other conversion types are:

Character  Meaning

x    Hexadecimal integer, using lower case 
a - fX    Hexadecimal integer, using upper case 
A - Ff    Floating point number
e    Floating point number in the form n.n...nEmm
g    Select %f or %e whichever gives the shortest output
%    Print a percent sign

n is the minimum field width. If nhas a leading zero, zero suppression is NOT performed (strictly speaking, the field is padded with zeros rather than spaces);

m is the precision (for floating point numbers) or the maximum number of characters to be printed from a string, or the minimum number of digits for an integer;

l is the lower-case letter L, used to signify that the variable is of type long (when used with ints) or double (when used with floats).

x is the conversion character as above.

The optional minus sign indicates left justification of the converted value. Even strings are usually right-justified within their field!

Here are a few examples; each group is preceded by the definition of the variable printed. The colons show the exact size of the field, an idea I've borrowed from the standard work on the language, The C Programming Language by Kernighan and Ritchie.

int x = 13579;

1.:%d:        :13579: 2.:%06d:      :013579: 3.:%-8.3d:      :13579 : 4.:%08.13d:      :0000000013579:

Line 1 shows the default format. In line 2 the minimum field size is specified and zero suppression is cancelled. The field is left justified in line 3, and line 4 shows how the precision overrides the minimum field width.

float one_seventh = 100000.0 / 7.0

1. :%f:        :14285.714286: 2. :%06.9f:      :14285.714285714: 3. :%9.12f:      :14285.714285714286: 4. :%-29.22f:    :14285.7142857142862000000000 : 5. :%.4f:      :14285.7143:

The definition requires explanation here. The numeric constants must have the decimal point otherwise C treats the division as of type int, which would yield exactly 14285 - the result is truncated, not rounded. Note how the field in line 4 is 29 characters wide including the decimal point and the trailing space, and that rounding does take place at line 5.

The answers are accurate to 12 decimal places (a total of 17 significant figures) which is sufficient for most purposes. The symbolic constants FLT_DIG, DBL_DIG and LDBL_DIG, #defined in float.h, give the 'digits of precision' that can be relied on for types float, double and long double respectively, which allows you to check the value prevailing at run time, and act accordingly. In Easy C they are all reliable to 15 significant figures.

char str[13] = "Twelve chars";

1. :%s:        :Twelve chars: 2. :%15.10s:  :   Twelve cha: 3. :%-15.10s:    :Twelve cha : 4. :%10s:      :Twelve chars: 5. :%.10s:      :Twelve cha:

Note the right justification at line 2, and the difference between line 4 (where the minimum field width is specified) and line 5, where the 'accuracy' is specified. If you want to truncate a string from the left (giving elven chars, for example) you should pass the appropriate pointer to printf() - in this case (str+2).

The fact that C will not truncate a numeric field to a specified size is both a blessing and a curse; it can play havoc with tables of figures, for example, but it does mean that no data is lost. It is possible to align columns by exploiting the fact that printf() returns the number of characters it has output, and another conversion character, *, which may appear either in the width or precision area. This returns the value of the next argument which is then used for the specification. The examples above were tabulated using this facility.

The left-hand part was printed thus:

x=printf("%2d :%s:", n, fmt);
/* n=1 to 5, converted by '%2d'
fmt= (for example) "%10s" converted by '%s' */

printf("%*s:", 20-x, " ");
/* the correct number of spaces */
printf(fmt, str);
/* str contains "Twelve chars"  */
printf(":\n");
/* end of the line              */

Here's a routine which exploits the variability of the field width. The object was to print totals held in the array total[ ] at the foot of columns of figures; the offset of the right-most digit in each column was stored in array wd[ ]. max_n holds the highest subscript used in the arrays.

for(n=max_n; n >= 0; n-)
  printf("%*d\r", wid[n], total[n]);

Formatted input - scanf()

The formatted input command scanf() works along broadly similar lines to printf() . The major difference is that the arguments to scanf() must be pointers to the variables which will hold the data. This is a good place to start looking if your C programs don't work! Almost everyone forgets sooner or later. The address of a variable var is given by &var or by a pointer to which the address has been assigned. We could have used scanf() in write_bstring() in the previous section; the inner do loop would be replaced by:

scanf("%s", &bstring[0]);

scanf("%s", bstring);

Any non-conversion characters (such as the colons in the printf() examples above) must be matched on the input stream. If such a match fails scanf() terminates. This can obviously cause problems with keyboard input.

scanf() returns the number of items successfully matched and assigned. If end-of-file is reached during a conversion, scanf() returns the value EOF - this is #defined in stdio.h as a value which cannot be confused with a character or item count (usually -1, but test for EOF for portability!)

Why should you expect EOF in keyboard input? In the first place, many operating systems allow the input stream to be redirected - that is, input may be coming from a file (see below). Naturally, when the input file is exhausted you would want the program to be able to detect it. Secondly, you can simulate EOF at the keyboard by entering Ctrl-D. This also works on Unix and MS-DOS by the way. Finally, this allows the whole scanf() 'family' to behave in similar ways under analogous circumstances - the designers of C have sought everywhere to exclude special cases as far as possible.

Redirecting input and output

*myprog <keystrokes >printout

*myprog <keystrokes >printout 2>errors

*myprog 0<keystrokes 1>printout 2>&1

*myprog 0<keystrokes >&printout

It is useful, when developing programs, to have some way of following progress on screen, so I would not recommend redirecting stderr until you are satisfied your program works properly, or unless you want to preserve the output for a later postmortem.

Command line arguments

*myprog arg1 arg2

Up to now, when example programs have appeared in this tutorial, the function main() has been followed by empty parentheses or the word void. However, main() can have two arguments. The first is an argument count, the second an array of char pointers, each pointing to a word on the command line. By convention, these two arguments are known as argc and argv respectively. The full prototype of main now reads:

<type> main(int argc, char *argv[])

argc will always be at least 1, in the case where the only word on the command line is the program name. Thus, the contents of argv[0] will always be the program name as entered at the keyboard. This allows you to detect if the directory path was used, if you really want to know (and I dare say there's scope for a spot of software protection here). A word is defined as a string of characters bounded by unquoted white space. Thus:

myprog hello mum  /* argc = 3 */

myprog "hello mum"  /* argc = 2 */

Here's a brief example of a program which takes arguments:

/* Calc.c  - prints the result of arithmetic */
/* expression in arguments 1-3 e.g. 75 / 15 */
/* Written by Dec McSweeney 1991 */
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
int main(int argc, char *argv[])

if(argc != 4)
   exit(1);
   }
op1 = atoi(argv[1]);
   /* function atoi(str) returns int value of string */
op2 = atoi(argv[3]);
switch(*argv[2])
      printf("%d\n", op1 + op2);
      break;
   case '-':
      printf("%d\n", op1 - op2);
      break;
   case '*':
      printf("%d\n", op1 * op2);
      break;
   case '/':
      printf("%d\n", op1 / op2);
      break;
   default:
      fprintf(stderr, "Unknown operation");
      break;
   }
}

The arguments above are positional, that is they must appear in a fixed sequence and their meaning to the program is indicated by their position. More normally, at least some of the arguments will not be order-dependent and in the case of a program with many options could be quite numerous - think about writing a C version of the RISC OS *COPY command.

The usual way to handle such a situation is to process each argument in turn using a for loop:

for(n=1; n<argc; n++)
   }

Some useful functions

In a multi-user operating system such as UNIX, or a multi-program environment such as RISC OS, it is important that programs do not take up more memory than necessary. If your word processor is to be used for a short letter, it doesn't need enough memory to store a novel. In the same way, it is frustrating if a program imposes unnecessary limitations on the user. One popular word processor runs on the IBM PC (a 640K machine), but will only cope with documents of up to 32K!

The easiest way to cope with this problem is to provide the program with memory when it needs it, and to claim it back when the program finishes with it. The functions malloc() and free() provide this facility. The full prototype of malloc is:

void *malloc(size_t s);

char *str;
size_t array_size;  /* set array_size to the required value before malloc */
str = (char *)malloc(array_size);

/* A portable call to claim space for 1000 ints */
/* The size of int varies from machine to machine */
int *numbers;
numbers=(int *)malloc(1000 * sizeof(int));

The structures discussed earlier in this chapter are ideally suited to the use of malloc(). A typical structure representing a block of text in a word processor might look like this:

struct block 
   struct *block prev;
   struct *block next;
   };
struct *block bptr;

bptr->next = (struct block *)malloc(sizeof(struct block));
/* link the new block to the chain */
bptr->next->prev = bptr;
bptr=bprt->next;
bptr->next = NULL;  /* the end of the chain */

size_t block_size;

bptr->text = (char *)malloc(block_size);

free(bptr->text);

/* unlink from the chain */ 
bptr->next->prev = bptr->next; 
bptr->prev->next = bptr->prev; free(bptr);

new_block = (char *)realloc(bptr->text, new_size);
if(new_block != NULL)
   bptr->text = new_block;

Furthermore, Acorn's implementation provides memory from the amount allocated in the program's original Wimpslot. Once this is used up, malloc() will return null pointers (implying no more memory), no matter how much there may actually be.

Bit variables

One approach is to use #define to set up bit-values. Returning to the *COPY example, options could be defined as powers of 2, corresponding to a bit:

#define FORCE_OVERWRITE 1
#define DELETE_SOURCE 2
#define VERBOSE 4
         /* ... and so on  */
int options;

options |= VERBOSE;     /*  '|' is the bitwise OR */

options &= ~VERBOSE;    /*  '&' is the bitwise AND */

To test such a flag, you would write:

if((options & VERBOSE) == 0)
         /* i.e. if VERBOSE is off */

struct 
   unsigned int delete_source : 1;
   unsigned int verbose : 1;
   } copy_options;

copy_options.verbose = 1;
if(copy_options.delete_source == 0)

Using SWIs

A header file, kernel.h, contains function prototypes, #defines and other relevant data for making SWI calls, but there are possibly better alternatives in other libraries, such as DeskLib (a freeware WIMP library).

Information is passed to and from SWI routines in the registers 0-9. These are defined as a structure _kernel_swi_regs in the kernel.h file. In your program you should include the following lines:

#include <kernel.h>
_kernel_swi_regs my_regs;

myregs.r[4] = 1099;

char message[50];
struct line_data edit_line;
my_regs.r[0] = (int)message;
my_regs.r[0] = (int)&edit_line;

my_regs.r[0] = (int) "This is a literal";

_kernel_swi(int swi_number, _kernel_swi_regs *in, _kernel_swi_regs *out)

#include <swis.h>
_kernel_swi(os_ReadVarVal, &my_regs, &my_regs);

/* Date.c - print any portion of Time message in any specified */
/* format (see PRM). Example: date "%WE, %MO the %DY%ST"       */
/* would print "Tuesday, December the 25th"                    */
/* Written by Dec McSweeney                                    */
#include <stdio.h>
#include <stdlib.h>
#include <kernel.h>
#include <swis.h>
int main(int argc, char *argv[])

char outstring[50];
int n;
_kernel_swi_regs r;
/** First a call to OS_Word 14, 3 - read clock as 5-byte value  **/
/** r0 = 14, r1 = address of parameter block (to hold result)   **/
/** on entry, 1st byte of r1 is set to 3 (the "reason code")    **/
 
r.r[0]=14;
r.r[1]=(int)pblock;
pblock[0] = 3;
_kernel_swi(OS_Word, &r, &r);
/** on exit, pblock holds the 5-byte time - compare with a Basic **/
/** command "SYS 07, 14, pblock TO , pblock"                     **/
/** first we show the contents of pblock....                     **/
for(n=0; n < 5; n++)  printf("%02X ", pblock[n]); printf("\n");
/** Now, we call SWI &C1 to convert. argv[1] is the char array   **/
/** holding the format string. For this call the 5-byte block is **/
/** addressed via r0, the output string via r1, the format       **/
/** string via r3. The length of output array is in r2.          **/
r.r[0]=r.r[1];
r.r[1]=(int)outstring;
r.r[2]=50;
r.r[3]=(int)argv[1]; _kernel_swi(OS_ConvertDateAndTime, &r, &r);
printf("%s\n", outstring);
exit(0);
}

*date "%WE, %MO the %DY%ST"

Programming in C++ is largely similar to programming in the C language itself. On occasion, you'll see helpful, big, tutorial books available in WH Smiths; promising to guide you through C++ in considerably more detail than you need for your Acorn computer. Recognising this, we've prepared a first steps tutorial, and recommend that you refer to the Dummies series of books for any further information.

We're only covering the initial elements of a C++ program, though: and using the examples given within the C++ tutorial on the disc.

Getting output onto the screen

Our example, in this case, repeats the output of John Doe three times, counting through the index value until index is equal to three.

#include "iostream.h"

main()

      cout << "John Doe 1 Jan 1955\n\n";
   }
}

This book is currently in its third edition: we're looking for a Wimp C++ tutorial for our fourth edition, and welcome any input from purchase of Easy C++. Should you wish to become involved, please contact us via the address given on page 2.

We are planning a book on C programming, with a particular emphasis on cross platform coding (e.g. Acorn to PC to Mac). If you'd like to enquire as to availability, please contact APDL again at the address given on page 2. The expected price is £25.99.

All C programs linked to the library STDClib have access to the full range of standard ANSI functions. EasyC is supplied with all 15 header files which declare these ANSI functions. The most useful of these are declared in the 5 header files listed below, and are described in detail in this chapter:

  ctype.h
  stdlib.h
  math.h
  string.h
  stdio.h

  assert.h
  setjmp.h
  errno.h
  signal.h
  float.h
  stdarg.h
  limits.h
  stddef.h
  locale.h
  time.h

APDL and ProAction