cs146a Project 1: Simple TCP Client

Introduction

You will create a simple network TCP network client with functionality similar to a stripped-down plain-TCP telnet. Your client will send text specified on the command line to a server, and then output the response received.

Clients and Servers

We will use the term client to mean an application which initiates connections to servers and makes requests. Your web browser and instant message program are examples of clients. We will use server to mean an application which accepts connections from clients. Servers service requests from clients and send back responses.

Network Connections

You will learn about the socket abstraction for building network applications. A socket hides the protocol layer from the programmer, exposing instead a read/write interface that should be familiar if you have read from and written to files. In fact, sockets use the file descriptor interface.

You will use TCP to make the connection between client and server. TCP is a stream-oriented, reliable-transport protocol. This means that once a connection is established, requests and responses can be reliably sent and recieved using the connection's socket. We'll learn more about TCP when we study communication abstractions and networking.

Resources

• Using TCP Through Sockets by David Mazières, Frank Dabek, and Eric Petererson
• C for Java Programmers

Project Requirements

Your client will do the following when invoked:

1. Create a blocking TCP socket and connect it to a specified host
2. Send the input text given on the command line to the host over the socket, followed by an additional carriage return ("\r\n")
3. Read all data returned from the server and print it to stdout (the output must be output completely verbatim without any formatting changes)
4. After all output offered by the server has been received and printed, your client must exit (returning control to the shell)

A blocking client will wait indefinitely for a response from a server. A full-strength TCP client implementation is typically non-blocking, i.e., it handles asynchronous events by polling sockets to see if more data can be sent or received. A problem with blocking clients is that they can appear to hang if a server refuses to reply to its request; you can ignore this problem for now. We will learn how to write asynchronous network applications later in the term.

Invocation

Your client program will be named sc, and will be invoked on the command line like this:

$ ./sc host port command

• host    : Either a hostname (e.g. "www.brandeis.edu") or an IP address ("129.64.99.138")
• port    : Port number of application to access on server (e.g., "80" for HTTP)
• command : Any string you wish to send over the TCP connection before waiting for a response

For example:

$ ./sc www.brandeis.edu 80 "GET /"

Where it Must Run

We recommend that you develop on a Linux machine. You can log into any of the Brandeis CS department public machines to work, or you can work in the berry patch. You are also free to develop on your own computer, but be aware that in order to receive credit your assignment must compile and run on one of the RHEL machines in the berry patch.

Additional Requirements

Please read these requirements carefully!

• Your program must accept both host names and IP addresses for the "host" parameter
• Your program must handle input commands that are longer than your socket output buffer (i.e., you may not limit the length of the command string)
• Your program must handle short writes to the server (i.e., you must keep writing if only part of your output buffer is sent to the server)
• Your program must handle responses that are longer than your socket input buffer (i.e., you must read and print all response data while preventing buffer overflows)
• Your program must append a carriage return line feed ("\r\n") to the input string that it sends to the server
• Your program should handle user errors gracefully. For example, if the user provides the wrong number of arguments you should alert them by printing an error message to stderr and return an error code (e.g., return 1 instead of 0). If the user inputs no arguments, then you should print a brief message to stderr describing how to invoke your program.

Getting Started

Download and unpack sc.tar.gz. To do this you can use the following command:

$ tar xvfz sc.tar.gz

You should see be able to see the extracted files by doing something like the following at the command line:

$ ls
.
..
sc/

$ cd sc
$ ls
.
..
Makefile
sc.c

To build sc, execute the following on the command line while in the sc directory:

$ make

This will build the sc binary, which you can run as described above. The skeleton sc.c does nothing, you will have to add to it all the required content to solve the assignment. As you are developing, you can rebuild sc simply by typing make on the command line again.

Tips and Suggestions

• You can test your output against the output from telnet. For example, you should see identical output from these two commands:

  $ ./sc www.brandeis.edu 80 "GET /"

  $ telnet www.brandeis.edu 80
  Trying 129.64.99.138...
  Connected to arachne.unet.brandeis.edu.
  Escape character is '^]'.
  GET /

• This tool will not work with HTTP versions higher than 0.9 unless you manually embed an additional carriage return in the request command; you will probably find it easier to just use "GET /" which indicates version 0.9 to the server.
• Google is an obvious choice to test with, but it's a bit finnicky about how it parses HTTP requests (it doesn't seem to like HTTP/0.9). You might have more luck with testing against www.brandeis.edu or example.com.
• Be aware that your tests load a server, so try to test against different servers instead of the same one over and over.
• We will check with TCP-based protocols other than HTTP. You should test with others as well (for example, finger is a simple protocol that you should be able to use with your sc application).
• Don't forget to carefully follow the examples in the "Using TCP Through Sockets" handout.

Collaboration

• You may discuss the assignment with other students in the course
• You may use the Internet for general help with socket programming
• You may not look at any solutions by other students from the current or previous years, and you may not look for solutions to similar problems on the Internet
• You may not turn in any code written by another student, nor may you share your code with any other student

How to Hand In

Submission instructions have appeared in the FAQ.