Introduction

Project Overview

You will begin by developing the infrastructure for linking a client and server, and then add functionality built on this infrastructure in successive assignments.

Project Management

This Assignment

For this assignment, you are to implement a server program to which client programs can connect. The server will recognize several command line options, will manage a log file in which it will record its activity, and will accept connections from clients. But it will not actually do anything having to do with its role as a command processor yet.

You will also implement a simple client program that you will be able to use to test your server.

The Server

The server is to recognize the following command line options:

The Log File

You can determine the current time and date using the time(2) kernel call, and you can create timestamp strings using the strftime(3) function. You can use the localtime(3) function to convert the time_t value returned by time(2) into a struct tm * required by strftime(3).

The table below gives the prototypes and requirements for the three functions that are required to be defined in logfile.cc.

int
openLog( const char *pathname,
         const char *msg,
         bool        overwrite );

int
writeLog( const char *event_name,
          const char *msg );

int
closeLog( const char *msg );

Server Features

• Process command line arguments
• Set up to accept connections on the well-known port
• Open the log file
• Wait for a client to connect. When a client connects:
  • Write a message containing the connecting client's host name to the log file
  • Read whatever the client writes to the server, and write it to the log file as it arrives. (See below for what the client does.)
  • When the client closes its end of the socket, the server closes its end and waits for another client to connect.
• The server is to continue running until it either receives a SIGINT signal, a SIGTERM signal, or a message from a client consisting only of the string, "SHUT" (four characters). In any case, the server is to call closeLog() before exiting. The argument to closeLog() is to be "Normal Shutdown" if a SHUT message is received from a client, or "Signal Received" if SIGINT is received. How to manage this feature is covered in the How to Implement the Server section below. Process Termination is covered in Section 7.3 of the Stevens textbook, and signals are covered in Chapter 10.

How to Implement the Server

Step 1. Set up the project.

When you look at the Skeleton Makefile, you will see that it redefines the CXXFLAGS variable to include the reference, $(DEBUG_FLAG). The idea behind doing this is that if DEBUG_FLAG is not set in your environment when you run make to compile your code, this reference will have no effect because undefined variables expand to nothing. But if you set this variable to -DDEBUG, either in your shell or on the make command line, then the C Preprocessor will run with the symbol DEBUG defined. (You can type "DEBUG_FLAG=-DDEBUG make" to do this.) For example, to check the result of option processing, you could insert code that looks like this in main():

#ifdef DEBUG
  printf( "Logfile: %s (%s)\n"
          "Port:    0x%04X (%d)\n",
          logfilePath, (overwriteLogfile ? "overwrite" : "append" ),
          wellKnownPort, wellKnownPort );
#endif

Don't lose track of the fact that learning how to use the project management tools (make and rcs) is a key goal of this assignment. Use this assignment to help make sure you are fully comfortable with these tools.

Assuming lnx0006 and spinoza are both available, be sure your code runs correctly on both systems before going on to the next step. (This rule applies to each step of the development process.) Be sure "make clean" leaves you with a clean project directory. Be sure you have run "make depend" before you check in your Makefile. Be sure "make" with no arguments builds qserver from a clean project directory. (The make command automatically checks out everything it needs, including the Makefile, when there is an RCS subdirectory.)

Step 2. Implement the Log File Functions

Step 3. Accept Connections From Clients.

    gethostname( thisHostName, MAX_HOST_NAME );
    hp = gethostbyname( thisHostName );
    memset( &server_sockaddr, 0, sizeof( server_sockaddr ) );
    server_sockaddr.sin_family = AF_INET;
    memcpy( &server_sockaddr.sin_addr, hp->h_addr_list[0], hp->h_length );
    server_sockaddr.sin_port = htons( wellKnownPort );
    server_fd = socket(AF_INET, SOCK_STREAM, 0);
    bind(  server_fd,
           (struct sockaddr *) &server_sockaddr,
            sizeof (server_sockaddr) );
    listen( server_fd, BACKLOG );
    socklen_t saSize = sizeof client_sockaddr;
    client_fd = accept( server_fd,
                    (struct sockaddr *) &client_sockaddr, &saSize );

A way to test your server at this point is to use a Sample Client Java application. You can get copies of both the Java and class files from ~vickery/SampleClient.java and ~vickery/SampleClient.class on Spinoza. There is also an executable version of this version of the server available at ~vickery/bin/qserver-1.1 on spinoza if you would like to run it to make sure you understand what it is supposed to be doing.

At this point, your server should accept a connection from a client, write a message to its log file, and exit. Check the log file to make sure the connection message got written properly.

If your server encounters any errors before it makes its first call to accept(), it should write an error message to stderr and call exit() with a status code of 1 (the standard value to use when a program exits because of an error). Once it is ready to accept connections, it should open the log file, with the second argument to the openLog() function being a string in the form:

  qserver (<pid>) accepting connections at <host>:<port>

You can use the following code to write connection messages to the log file:

    hp = gethostbyaddr( (const char *)&client_sockaddr.sin_addr, 4, AF_INET );
    writeLog( "CONNECT", hp->h_name );

Step 4. Handle SIGINT and Normal Exit

1. If the server is running in the foreground, and you type Control-C in the server's console window. This will send an INT signal to the server.
2. If you give the command "kill <pid>" substituting the server's actual process id for <pid>. This will send a TERM signal to the server.
3. If one of the clients writes a "SHUT" message to the server.

There are a number of ways you could meet these requirements, but I am specifying the technique you are to use for this assignment as follows:

• Write a function definition that matches the following function prototype:

        void f(int, char *);

  Use a meaningful function name instead of "f".

  This is the function that will be called just before the server exits, no matter which of the three events listed above was the cause for exiting.

  The first argument to this function will be the status code used in a call to exit(). We will arrange to use a special value for this argument if the program is exiting because of a signal. The second argument is a string, which we will use as described next.

  This function is to test the value of the first parameter. If it is zero or above, call closeLog() passing the second input parameter as the argument to closeLog(). If the first parameter is negative, call closeLog() with the string "Signal Received" as the argument. (Optional: Put the signal number in the string, such as "Signal 2 Received.")

• Set up so that the function described above will be called when the program calls exit() using the GNU on_exit() function. This function is not part of ANSI C/C++, thus making your program less portable than if you used the ANSI function atexit(). But it is very valuable, and since the GNU C/C++ runtime library is open source, its use seems justified here. See the man page for how to code invoke on_exit(). It should be called after the logfile has been opened and before the server starts accepting connections from clients.

• Write a function definition that matches the following function prototype:

        void f( int );

  Use a meaningful function name instead of "f".

  This is the "signal handler" function that will be called whenever a TERM or INT signal is sent to the process. It simply calls exit() with a status code of minus 1. Calling exit() causes the function you registered using on_exit() to be called automatically before the process actually exits. How to code that function was covered above.

• At the same time you call on_exit(), also call signal() two times, once so that your signal handler will be called for SIGINT, and once so it will be called for SIGTERM.

Step 5. Reading From Clients

The idea of a socket connection is that it is a full-duplex (two-way) pipe connecting the client and server. Whatever the client writes to its end of the socket pair, the server can read from its end; likewise, whatever the server writes to its end, the client can read from its end. There is no way for the server to read what it has written, and there is no way for the client to read what it has written.

An important point to remember is that stream sockets are, as their name implies, used to send streams of bytes between clients and servers. For example, depending on network conditions, the server could receive a "SHUT" message with a single call to read() if the client executed either of the following two sequences of function calls:

      write( fd, "SHUT", 4 );

      write( fd, "S",  1  );
      write( fd, "HU", 2  );
      write( fd, "T",  1  );

But in this assignment, you do need to convert the bytes you read into strings so you can work with the text received using standard string functions. To do this, you need to append '\0' to the end of whatever characters are read from the socket:

      int numBytes = read( fd, buf, sizeof buf );
      buf[ numBytes ] = '\0';

Once the server accepts a connection from a client, it enters an endless loop in which it reads from the socket, and writes to the logfile. It exits this loop when the client closes its end of the socket or when a client sends a SHUT message.

If the client closes its end of the socket (for example, by exiting), the server's call to read() will return a value of 0 (numBytes would be zero in the code above). The server must also close its end of the socket (using close()) before looping back to accept another client connection. If you fail to do this, the fd will remain open, and the server will eventually crash with too many open fds.

The Client

1. Process command line options.
2. Connect to the server.
3. Repeat:
   • Read a line of text from the user using fgets().
   • Write the line to the server using write().

-p | --port	The server's port number to connect to.
-h | --host	The server's host name.
-? | --help	Print a usage message and exit.
-v | --version	Print the client's version number and exit.

Here is semi-pseudocode for connecting to the server:

      hp = gethostbyname( serverName )
      server_sockaddr.sin_family = AF_INET;
      memcpy( &server_sockaddr.sin_addr, hp->h_addr, hp->h_length )
      server_sockaddr.sin_port = htons( serverPort )
      server_fd = socket( AF_INET, SOCK_STREAM, 0 )
      connect( server_fd, (struct sockaddr *) &server_sockaddr,
                                               sizeof server_sockaddr )

Once the call to connect() completes successfully, you can use server_fd as the first argument in your call to write().

The client exits the loop at the end of its algorithm either when reaching the end of file on stdin or when the server closes its end of the socket. End of file on stdin will happen if the user types Control-D at the beginning of a line. You can test for it using feof(). The client won't know that the server has closed its end of the socket until it tries to write to it, which means that the user has to type something in to get to the second part of the read/write loop. The only reason the server should close its end of the socket before the client exits is if the user typed "SHUT," so you can make your client a little smarter by having it exit automatically if the user types "SHUT" (after first writing the message to the server!).

Final Testing and Submitting the Assignment

You need to test your code carefully. Be sure your Makefile is set up correctly by using the touch command to modify the modification times of the header, source, and object files and observing the commands that make generates in each case.

Be sure "make depend" and "make clean" are working correctly. Be sure that "make clean" followed by "make depend" works properly.

Be sure you have entered meaningful log messages each time you checked in your various files. (If not, the messages can be changed, but it's a lot of bother. See the -m option of the rcs command. Don't worry about minor typos.) Double-check that all RCS keywords have been expanded properly in your .h and .cc files as well as your Makefile.

You can check for yourself that there are no long lines or tab characters in your code on both spinoza or lnx0006. Give the following command:

      ~vickery/bin/chk_format Makefile *.h *.cc

Be sure your code compiles and runs correctly on both spinoza and lnx0006. You should be able to run the server on either one and run clients on the other. Be sure you can run an endless sequence of clients, with the server exiting only when one of them sends a SHUT message or if one of the two signals is delivered to it.

Check the contents of your logfile to be sure it is formatted properly and contains the correct information. Be sure the -o command line option works properly for the server.

When your assignment is ready, clean your project directory, create a tar file of it, and email the tar file to me at my babbage account, vickery@babbage.cs.qc.edu.

The due date is midnight, April 16. If you don't have the project completed by then, send what you have done at that time so you can get partial credit. The assignment will count approximately 10% of your course grade.

Solution

• Makefile
• qserver.h
• qserver.cc
• logfile.cc
• qclient.h
• qclient.cc