CSC 209H: Assignment 3

Weight: 10% of course grade.

Due date: 10:00 p.m. Monday, July 24

Introduction

In this assignment, you will be writing programs that will play the game of Blackjack.

Also known as Twenty-One, the game itself is quite simple. The goal of the game is to take cards to get as close to the total of twenty-one as possible, without going over. Cards 2 through 10 are worth their face value, while jacks, queens and kings (face cards) are worth 10. An ace can be counted either as 1 or 11.

Blackjack is played between a number of players and the dealer. Each player competes only against the dealer (and not against each other). The player wins if the player's hand is closer to 21 (without going over) than the dealer's hand. If a hand totals more than 21, that player (or dealer) is said to bust, which is an automatic loss.

A "blackjack" is a two-card hand consisting of an ace and a ten-value card (not necessarily a jack). A blackjack is an automatic winner, unless both the player and the dealer hold blackjacks, which is a tie.

Rules

For this assignment, we'll simplify some of the rules of blackjack from what is typically played in casinos. In each round, each player is dealt two cards face-up, and the dealer is dealt one face-up card and one card face-down (the "hole" card). Each player, in sequential order, gets to play his hand. If the player's current hand totals less than 21, the player may choose to either HIT (add another card to his hand) or STAND (take no more cards). If a player hits and the total is over 21 (remember, an ace may count as either 11 or 1), the player has busted and loses.

Once all players have either busted or chosen to stand, the dealer plays. The dealer reveals the hole card, and draws cards until the hand totals 17 or more. (So, the dealer hits on anything less than 17, but stands on 17 or more.)

If the dealer busts, all non-busted players win. If the dealer does not bust, the dealer's hand is compared to each non-busted player's hand. If the player's total is greater than the dealer's total, that player wins. If the dealer's total is greater than the player's total, the player loses. If the player's hand and the dealer's hand have the same total, it is a "push" or tie (unless one of the hands is a blackjack). A blackjack beats anything except another blackjack.

Betting

Blackjack is inherently a gambling game, so we'll need to handle betting. Prior to each round, each player makes a bet (an integer). The minimum bet will be 1 chip. If the player loses the hand, the bet is lost. If the player ties the dealer, the player gets the bet back. If the player wins (without a blackjack), the player gets the bet back plus the value of the bet (so, on a bet of 2 chips, the player would win 2 additional chips for a total of 4). If the player wins with a blackjack, the player is paid 3:2, rounded down to an integer (so, on a bet of 2 chips, the player would win 3 additional chips).

(For the pros: no splitting, double-down, surrender, insurance, or any other such rules for this assignment.)

Cards

Cards will be represented externally as two characters: the rank of the card and its suit. The first character will be one of 2,3,4,5,6,7,8,9,T,J,Q,K,A (for ten, jack, queen, king and ace). The second character will be one of C,D,H,S (for clubs, diamonds, hearts and spades).

Internally, you may represent a card in any way you wish. Suits are not used in blackjack, so you may freely ignore them. Some functions in utils.c might be useful, and can entirely take care of handling cards for you.

Part 1 - bjplayer

In this part you are asked to write a C program that will play blackjack. There is no requirement that your program wins any hands! Your program need only play according to the rules specified here.

Your program will be named bjplayer. You will also submit a README text file briefly describing how your program works. Be sure to point out any interesting strategies you might be using!

Your program will be executed with the following arguments:

$ bjplayer num_players num_rounds num_decks chips

All command line arguments are mandatory.

Your program will read from stdin and write to stdout. It will iteratively execute the following phases:

• bet: print a positive integer (as a string) to stdout (representing the bet for this hand), followed by a newline
• inital hands: read a line from stdin consisting of 3 cards: the player's two initial cards, and the dealer's up card. The format is card1,card2|dealerup\n
• playing: print the string HIT or STAND to stdout, followed by a newline. If the player hits, you will read a line containing a single card from stdin. If the total is less than or equal to 21, this phase is repeated. If the player busts, or the player chose to stand, you should proceed to the next phase.
• result: read a line from stdin consisting of one of the strings: WIN, LOSS, TIE, BUST
• dealer's hand: a line consisting of the cards in the dealer's hand, once dealer has completed play (cards are separated by commas)

When EOF is encountered on stdin instead of reading the initial hands, your program should terminate normally. If the player is reduced to zero chips, the program should terminate normally.

Each program may assume it is playing a series of games with a single shuffle. A particularly clever program may count played cards and change its bet or its behaviour if the cards remaining in the deck are favorable.

Warning: you will not be evaluated on how clever your program is, only that it follows the specification! Do not spend so much time on your player so that you do not complete the rest of the assignment!

Tip: To aid in debugging (particularly for part 2), you might want to send diagnostic or status information to standard error. Be sure to turn off this diagnostic output before handing in your assignment.

Example

The following may be an execution of such a program.

stdin	  stdout
	  1
4C,6S|6H  HIT
QH	  STAND
WIN
6H,8S,JD

The player is playing a single hand, and wins the hand since the dealer busts. The player would win one additional chip (if the player began with just one chip remaining, the player would have two chips after this hand).

Hints and Clarifications

• This should be a fairly straight-forward exercise. Don't spend too much time on this part, until you've completed part 2. You might want to start with a player that stands every time.
• Because your program uses a text interface on stdin and stdout, you should be able to pretend to be a dealer and play with your program.
• You might want to prefix your diagnostic output with your process id (the getpid() function), particularly while doing the second part of this assignment.
• To ensure your output to stdout is being written immediately, you might want to use the fflush() function following a print call.

Part 2 - bjdealer

In this part you will write a C program named bjdealer that will act as the dealer in a game of blackjack. The competitors will be executions of bjplayer programs.

Your program should support being run in the following manner:

$ bjdealer [-s random_seed] num_rounds num_decks chips list-of-players

Following the -s option (if it exists) is an unsigned long integer N, the seed to the pseudo-random number generator (you may wish to use strtoul() to convert the argument to an unsigned long). If -s does not appear, the generator should be seeded from /dev/urandom (functions in utils.c might help).

The remaining arguments are mandatory. The num_rounds specifies the number of rounds to play, and must be greater than 0. The num_decks is the number of standard decks to play with, and must be between 2 and 8. The chips is the number of chips every player starts with, and must be greater than 0.

The list-of-players will be a list of path names of bjplayer programs, possibly (and probably) with duplicates. For example, a list might be bjplayer bjp2 ../other/bjplayer bjplayer bjplayer for a game with 5 players. There must be at least 1 player specified, and no more than 8 players.

Your program will do the following:

• Create one child process per player. The child process will exec the specified program (once the standard input and standard output are set up appropriately to communicate with the dealer).
• Create a playing deck consisting of num_decks standard decks of 52 cards. This deck should be shuffled randomly (routines in utils.c might help you with this). The playing deck should contain 52 * num_decks cards.
• For each round, deal two cards to each (currently executing) player program and one up card for the dealer. In order from the first player to the last, interact with the player (as described above) to determine the player's hand. Once all players have busted or stood, determine the dealer's hand (stand 17+, hit under 17) and inform each player of whether the result for that player is a WIN, LOSS, TIE, or BUST, and inform each player of the dealer's hand.

The playing deck is shuffled once at the start of play, and the top card is drawn from the deck each time a card is needed. The deck is typically not reshuffled between rounds, nor are cards returned to the deck once they have been used. If, however, before a round begins there are strictly less than 52 cards remaining in the playing deck, all cards are collected and the playing deck is reshuffled (just as at the beginning of play). To indicate this in-play shuffle to the players, the dealer sends a SIGUSR1 signal to each player process. The player program must handle this signal, as the default signal action is termination.

The bjdealer program must communicate with its child processes using pipes. In the case that a player ceases to execute (or otherwise closes the pipe), your bjdealer program should forevermore ignore that player (cards may still be dealt if you wish, but your program should not wait for any further responses).

[Update 23 Jul 2006] Once the specified number of rounds have been played (or all players have gone broke), your dealer program should print a report of how many chips each player ends with. The following is one such report:

Game outcome:
Player 1 is broke!
Player 2 finished the game with 2 chips

Important: Be sure to clean up any processes that may be left behind before logging out of your machine. The ps and top commands can help you find any lingering processes.

Hints and Clarifications

• Start now! Try to get something very simple working first, then get the pipes set up to communicate with one child process, then continue adding functionality step by step.
• You must use pipes to communicate between processes for this assignment. Do not use sockets or other advanced IPC methods.
• Since pipes are half-duplex (one-way) communication, you will need two pipes to communicate with each child process.
• The bjplayer programs only know about stdin and stdout. You will need to use dup2() to reassign the file descriptors associated with the pipes. The defined constants STDIN_FILENO and STDOUT_FILENO refer to these file descriptors.
• If you are having trouble reading over the pipe from a child process, the output might be getting buffered by your program. The fflush() function will make sure printf output is flushed to the pipe.
• You can throw away the diagnostic output from your children by redirecting stderr (file descriptor 2) to /dev/null under a Bourne shell.
• You should clean up any zombie children processes using one of the wait functions.
• You must check the return values from each library function call and take appropriate action based on these return values (such as printing an error message, exiting with error, or continuing normally).
• For full marks, your bjdealer program C code must be well-documented, follow good programming style, and be easily understandable by the marker.

Learning Objectives

• Creating and controlling processes under UNIX (fork, wait, etc.).
• Executing programs using C (exec).
• Basic interprocess communication (pipes) in C.
• Understanding file descriptors in UNIX.

What to hand in

You will commit to the a3 directory of your CSC209 repository the following files:

• Your C source files for bjplayer.
• Your C source files for bjdealer.
• Any additional files needed by your programs (header files, utils.c, utils.h, etc.)
• Makefile, containing commands to compile your bjplayer and bjdealer programs simply by running make
• README, briefly describing your bjplayer program.

You are strongly encouraged to take advantage of the version control system and commit your work frequently so that you can keep track of your progress. Please note that perfectly fine (and even recommended) that you keep any additional files related to this assignment (such as files and scripts used for testing) under version control. The markers will simply ignore such files.