C NOTES: QUICK REFERENCE

Books
BASICS of LANGUAGE
SPECIAL TOPICS
FAQs

BOOKS:
- 0. I love this small book Jump Start to C Programming \& The Unix Interface by Derek Kiong Beng Kee, Prentice Hall (Singapore), 1995. I will cite this as [Jumpstart]
- 1. Of course, there is the classic The C Programming Language by Brian W. Kernighan and Dennis M. Ritchie, Prentice Hall, 1988.
BASICS OF LANGUAGE
My First Program
- Using your favorite editor, type the following lines into a file called "hello.c".
```
	//filename: hello.c
	//=========================================================
	main () {
	   printf("Hello World!\n");
	}
	//=========================================================
	
```
- This program just prints a message on your screen.
- To compile it just call "gcc hello.c". Here, I am assuming the Gnu gcc compiler, but replace it with whatever compiler your system has.
- The compilation will produce an output file called "a.out" on unix systems ("a.exe" in cygwin).
- Now, just invoke "a.out" or "a.exe" to run the program.
- Do you understand every element in the above program? If now, read on...
Comment Lines
- The single line variety //
- The multi-line variety /*...*/
Main(), argc, argv, envp and Command line arguments
- Every C program begins execution in the main() program.
- Hence a stand alone program MUST define a main() program.
- The exception is when your program is to be compiled and separately linked to another program that has the main program. E.g., your program is to be put into the library.
- You can define main() with no arguments. But it has three optional arguments as well.
- Two main optional arguments to main() are argc and argv, illustrated in the following:
```
	//=========================================================
	main ( argc, argv)
        	int argc; char **argv;
	{
  	   char *PROGNAME = *(argv++);
	   if (argc > 2)
	     { fprintf (stderr, "format: %s [input file]\n", PROGNAME );
     	     exit ( -1 );
	   }
	   if (argc == 2 && (input = fopen ( *argv, "r")) == NULL)
	      { fprintf ( stderr, "%s: cannot open %s for reading\n",
			PROGNAME, *argv );
	     exit ( -1 );
	   }
	}
	//=========================================================
	
```
- argc is the number of command line arguments when your program is invoked, and argv is an array containing these command line arguments. NOTE that the name of your program (i.e., the executable code) is regarded as the FIRST argument, i.e., it is stored in argv[0]. So argc is always positive.
- Main() takes a third optional argument:
```
	//=========================================================
	main ( argc, argv, envp)
        	int argc; char *argv[]; char **envp;
		// Note that **char and *char[] are equivalent
	{...
	}
	//=========================================================
	
```
Constants
- You can use the #define statement. Typically, such constant names are in all caps.
```
		#define PI 3.1415
	
```
- Another way is to write
```
		const float pi = 3.1415;
	
```
Boolean Tests and Expression
- Note that there is no built-in type called "bool".
- The "if(c){...}" paradigm in C can be confusing!
- Q: When is {...} executed?
  A: Iff c is non-zero! WHY? Traditionally, TRUE=1 and FALSE=0. Thus this convention generalizes to TRUE !=0.
- Q: suppose c is a return code/status from a subroutine. Is c=0 considered "normal" or "error"?
  A: it is context dependent.
- E.g., 0 as error: if you open a file, a return code of 0 seems to be error (otherwise you get the file descriptor). If you write to a file, a return code of 0 seems to be error as well (otherwise you get the number of bytes written).
- E.g., 0 as normal: when processes terminate, they usually call exit(status) where status=0 means normal termination. So this convention is opposite of the previous example.
SPECIAL TOPICS
Macros
- Defining a macro with arguments:
```
		#define macro_name(arg1, arg2, ...) string_definition
		
```
- Note there is no blanks between the name of macro and left parenthesis enclosing the argument.
- There is no ";" at the end of the string definition.
- Use the \-escape to get multiline macros.
- E.g.
```
		#define SQUARE(x) x * x
		while (count <= 5)
		{
		  printf("%d\t%d\n", count, SQUARE(count));
		  count = count+1;
		}
	
```
- Remark: this macro is not foolproof (standard error). We get unexpected result if we call, e.g., SQUARE(i+j). The standard solution is:
```
		#define SQUARE(x) ((x) * (x))
	
```
Runtime Libraries
- Standard libraries are in /usr/lib and perhaps in /usr/lang/lib. E.g. libc.a, libmp.a, etc, may be found here.
- Sometimes you would like to look under gcc libraries: e.g., /usr/export/local/lib/gcc-lib/sun4-sunos4/2.2.2/include/math.h is the only place where I could find math.h explicitly and discover that the powering function pow(b,e)=b^e are defined only for doubles.
- Be sure to use the "-l???" directive when you call gcc, which is passed to ld. For instance, if you have the line
```
		#include 
	
```
  in your file.c, then you should call
```
		% gcc file.c -lm ...
	
```
  NOTE: the order of placement of "-lm" is important! E.g., %gcc -lm file.c ... will not work here.
- If you need to specify non-standard paths (perhaps for your own libraries), you can specify it with the -L??? option. E.g., if my libraries are found in /home/yap/lib, then I can issue:
```
		% gcc file.c -L/home/yap/lib -lm -lmyLib ...
	
```

What is a shared library? Traditionally, when you call a library routine, the library code is incorporated into your compiled program.
It would be better if these code could be dynamically loaded at run time: the 2 benefits are that your compiled code could be MUCH smaller, and this dynamically loaded code can be shared by other users using the same routine!
If you get runtime (or compile time) errors with "ld", you should check the environment variable LD_LIBRARY_PATH. E.g., My current value of this variable is
```
		LD_LIBRARY_PATH=/usr/local/lib:\
			/usr/openwin/lib:\
			/usr/motif/lib:\
			/opt/SUNWspro/lib:\
			/usr/unsupported/installers/chenli/lib
	
```
The last one (../chenli/lib) is needed for openGL and glut libraries.

What runtime libraries do you need for an executable file "foo"? Type

		>ldd foo

and this information will be displayed. E.g., on solaris:

   > yap@jinai[173]% ldd rotate2
   >         libGL.so => /usr/unsupported/packages/opengl/Mesa/lib/libGL.so
   >         libGLU.so => /usr/unsupported/packages/opengl/Mesa/lib/libGLU.so
   >         libXmu.so.6.0 =>         /usr/local/lib/libXmu.so.6.0
   >         libXi.so.6.0 =>  /usr/local/lib/libXi.so.6.0
   >         libXext.so.6.4 =>        /usr/local/lib/libXext.so.6.4
   >         libX11.so.6.1 =>         /usr/local/lib/libX11.so.6.1
   >         libm.so.1 =>     /usr/lib/libm.so.1
   >         libsocket.so.1 =>        /usr/lib/libsocket.so.1
   >         libnsl.so.1 =>   /usr/lib/libnsl.so.1
   >         libc.so.1 =>     /usr/lib/libc.so.1
   >         libSM.so.6.0 =>  /usr/local/lib/libSM.so.6.0
   >         libICE.so.6.3 =>         /usr/local/lib/libICE.so.6.3
   >         libpthread.so.1 =>       /usr/lib/libpthread.so.1
   >         libXt.so.6.0 =>  /usr/local/lib/libXt.so.6.0
   >         libdl.so.1 =>    /usr/lib/libdl.so.1
   >         libmp.so.2 =>    /usr/lib/libmp.so.2
   >         /usr/platform/SUNW,Ultra-5_10/lib/libc_psr.so.1
   >         libthread.so.1 =>        /usr/lib/libthread.so.1
   > yap@jinai[174]% 
   >

Debugging Tools and Hints: objdump, ldd, etc If you could not compile your program or have mysterious errors, try one of the following options:
1. To look inside compiled libraries (*.a files), do for example:
```
	
		> objdump -t /lib/libc.a | grep "fork"
	
```
  This will print all the library routines that has name containing "fork".
  [Objdump is available in Solaris and Cygwin]
2. What runtime libraries do you need for an executable file "foo"? Type
```
		> ldd foo
	
```
  and this information will be displayed.
3. What is gcc actually doing? Try the verbose modes (-v) to see:
```
		> gcc -v test.c
	
```
4. Another version of this, useful for seeing the arguments as discrete units, and which does not actually compile, is
```
		> gcc -### test.c
	
```
  where "###" is literally what you type! Each argument is written in a quoted string.
5. Where would gcc find this library? E.g., the standard c library is called "libc.a". But where is the path? To find out, do:
```
		> gcc -print-file-name=libc.a
	
```
  On my cygwin, it prints:
```
		/usr/lib/gcc-lib/i686-pc-cygwin/3.3.3/../../../libc.a
	
```
  which is really /usr/lib/libc.a.
6. Which directories would gcc search? Try this:
```
		> gcc -print-search-dirs   2>&1 | tee x
	
```
  The following output is stored in file "x", which you can examine:
```
	install: /usr/lib/gcc-lib/i686-pc-cygwin/3.3.3/
	programs: =/usr/lib/gcc-lib/i686-pc-cygwin/3.3.3/
		:/usr/lib/gcc-lib/i686-pc-cygwin/3.3.3/
		:/usr/lib/gcc-lib/i686-pc-cygwin/:...
	libraries: =/usr/lib/gcc-lib/i686-pc-cygwin/3.3.3/:
		/usr/lib/gcc/i686-pc-cygwin/3.3.3/:...
	
```
7. If you want to know the path for a particular library, say "libs.a". You type
```
		> gcc -print-file-name=libc.a test.c
	
```
  and gcc will print the full absolute path name of the library that would be used for linking. It does nothing else! See man gcc for more options.
8. Check out the environmental variables used by gcc:
```
		GCC_EXEC_PREFIX
		COMPILER_PATH
		LIBRARY_PATH
		LANG
	
```
9. If you could not find a standard library like "/usr/libc.a" you could try to give the prefix using "-B" flag:
```
		> gcc -print-file-name=libc.a

		/usr/lib/gcc-lib/i686-pc-cygwin/3.3.3/../../../libc.a

		> gcc -B/usr -print-file-name=libc.a

		/lib/libc.a
	
	Note that the -B flag changed the search path for "libc.a".
	
	NOTE: in cygwin, the directories
	/usr/lib and /lib are identical.  E.g., create a dummy file
	in /usr/lib, and it shows in /lib; delete in one and it
	is also deleted in the other!
   
```

Files

Simple example of opening a file:

	#define INFILE	"scores.txt"

	FILE *fhandle;
	fhandle = fopen(INFILE, "r");
	if (fhandle == NULL)
	{
	  perror(INFILE);
	  exit(EXIT_FAILURE);
	}

System Calls

A system call looks just like a function call. The man pages will tell you want files to include (e.g., #include ).
Generally, system calls return the value -1 to indicate failure.

The most recent error code is stored in the external variable "errno". This code can be used to index the external string array "sys_errlist" to obtain a concise description of the error:

	//============================================
	#include 
	#include 

	...
	int code = system_call();
	if (code == -1) {
		extern int errno;
		extern char * sys_errlist[];
		printf("%s\n", sys_errlist[errno]);
		exit(1);
	}
	...
	//============================================

Ref [Jumpstart] gives the following code, which it says is equivalent to the library function "perror()":

	//============================================
	void report_err(char * prefix)
	{
	   extern int errno;
	   extern int sys_nerr;    // size of array sys_errlist
	   extern char *sys_errlist[];

	   if (prefix != NULL)
	   	printf("%s: ", prefix);
	   if (0 < errno && errno < sys_nerrr)
	   	printf("%s\n ", sys_errlist[errno]);
	   else
	   	printf("unknown error\n");
	   exit(1);
	}
	//============================================

FAQs

GO TO TOP Please send comments to yap at cs dot nyu dot edu.

C NOTES: QUICK REFERENCE

BASICS OF LANGUAGE

SPECIAL TOPICS

FAQs