Every tutorial must start with "hello world" program and libjf can not violate this golden rule. |
All the examples showed in this book are available in doc/tutorial/examples sub-directory distributed with software package.
Example 2-1. hello_world.c
1 #include <jf_file.h>;
2 int main()
3 {
4 int rc;
5 jf_file_t jf;
6 size_t write;
7 rc = jf_file_open(&jf, NULL, "jf_tut_foo", "w", NULL);
8 if (JF_RC_OK != rc)
9 return 1;
10 rc = jf_file_printf(&jf, &write, "%s", "Hello world!\n");
11 if (JF_RC_OK != rc)
12 return 1;
13 rc = jf_file_commit(&jf);
14 if (JF_RC_OK != rc)
15 return 1;
16 rc = jf_file_close(&jf);
17 if (JF_RC_OK != rc)
18 return 1;
19 printf("Hello world program is OK!\n");
20 return 0;
21 }
Hello world code explanation
to use libjf a program must include at least jf_file.h header file
declare object jf of type jf_file_t: jf is a "journaled file object"
open (create & open) for write ("w") a journaled
file of name jf_tut_foo and associate it to
object jf; second argument
(NULL) indicates a private journal
must be used, fifth argument (NULL) tells
default parameters must be used
write to journaled file some stuff; second argument is used to
retrieve the number of bytes stored to journaled file, other
arguments mimic fprintf function
commit changes previously operated on journaled file jf
close journaled file
To compile hello_world.c sample code and link it against libjf I suggest you to use libtool and its magic:
libtool --mode=link gcc -Wall -I/opt/libjf/include -L/opt/libjf/lib -ljf \
-o hello_world hello_world.c
options:
source code must be compiled and linked
use GNU C compiler
activate all C compiler warnings
specify where libjf include files must be searched
specify where libjf archive/shared object must be searched
specify the name of the library must be linked to the produced executable
name of the executable will be produced
name of the source code file will be compiled
This version of "hello world" program is not so bad, isn't it? All the stuff around the 6 described rows is an old tale: error checking and user feedback. You should note these essential points:
libjf API (Application Programming Interface) is consistent to an object oriented model: the first argument is the object the function (method) is working on
most libjf
functions (methods) return a return code of type int;
file jf/jf_errors.h enumerates the value set:
JF_RC_OK is the "OK return code",
values greater than JF_RC_OK are
"warning return codes", values lesser than
JF_RC_OK are "error return codes"
object types are not pointers, but functions (methods) expects
references to objects: user application can choose to allocate
objects
on stack (like in hello_world.c example) or on
heap (using malloc/free
functions); object sizes are not large enough to become a source of
issues in today supercomputer powered PCs era
all changes must be committed before a journaled file is closed: uncommitted changes are backed out ("implicit rollback")
If you correctly compiled hello_world.c, in current directory you should be able to see hello_world executable:
tiian@linux:~/tutorial> ls -la hello_world*
-rwxr-xr-x 1 tiian users 10079 2005-08-10 22:10 hello_world
-rw-r--r-- 1 tiian users 578 2005-08-10 18:51 hello_world.c
to execute it type this command:
./hello_world
the program should print these sentence on your terminal:
Hello world program is OK!
And two files should appears in current directory:
tiian@linux:~/tutorial> ls -la jf_tut_foo*
-rw-r--r-- 1 tiian users 13 2005-08-10 22:52 jf_tut_foo
-rw-r--r-- 1 tiian users 8311 2005-08-10 22:52 jf_tut_foo.jf
jf_tut_foo is the journaled file with the content
hello_world program stored and committed:
tiian@linux:~/tutorial> cat jf_tut_foo
Hello world!
jf_tut_foo.jf is the journal file implicitly
created by libjf
because hello_world program does not specify a
journal
file. The journal is a binary file you can browse with utility
jf_report; try this command from your terminal:
tiian@linux:~/tutorial> jf_report -dt -j jf_tut_foo.jf
but this is a more intriguing tale can not be revealed at
"hello world" step!