Skip to content

Commit

Permalink
docs: add README
Browse files Browse the repository at this point in the history
  • Loading branch information
@leogaudin
leogaudin committed Jun 10, 2023
1 parent d938597 commit 63143cf
Showing 1 changed file with 76 additions and 63 deletions.
139 changes: 76 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,93 +1,106 @@
# Minitalk Project
<div align="center">
<h1>🗣️ minitalk</h1>
<p>This project is a simple client-server communication system implemented using signals in C. The client sends a message to the server, and the server receives and displays the message character by character.</p>
<a href="https://wakatime.com/badge/user/db0e5671-cec5-4e7b-9d41-19a881e67f7d/project/56f4877c-3ac5-4648-9b71-95c3b46426ff"><img src="https://wakatime.com/badge/user/db0e5671-cec5-4e7b-9d41-19a881e67f7d/project/56f4877c-3ac5-4648-9b71-95c3b46426ff.svg" alt="wakatime"></a>
<br />
<img src="https://img.shields.io/badge/norminette-passing-success"/>
<a href="https://developer.apple.com/library/archive/documentation/Performance/Conceptual/ManagingMemory/Articles/FindingLeaks.html"><img src="https://img.shields.io/badge/leaks-none-success" /></a>
<img src="https://img.shields.io/badge/bonus-included-success"/>
<br />
<img src="https://img.shields.io/badge/-unknown%2F100-important?logo=42&logoColor=fff" />
</div>

## 📖 Table of Contents
<!--ts-->
* [Usage](#usage)
* [How Does Minitalk Work?](#how-does-minitalk-work)
* [Client](#client)
* [Server](#client)
* [Bonus Features](#bonus-features)
* [Credits](#dependency)
<!--te-->

## Introduction
Minitalk is a client-server application that allows the transmission of messages between two processes using signals. The client sends a message character by character to the server, which receives and prints the message. This project is part of the curriculum at 42.

## Getting Started
## Usage

### Prerequisites
- This project requires a Unix-like operating system.
- The GNU C Library (glibc) must be installed.
1. Clone the repository:

### Compilation
To compile the project, use the provided Makefile by running the following command:
```bash
git clone https://github.com/leogaudin/minitalk.git
```

2. Compile the source code using the provided Makefile:
```bash
make
```

This will generate the `client` and `server` executables.

## Usage

### Server
1. Start the server by running the `server` executable. It will display the server's process ID (PID) on the console.

2. Keep the server running in the background.

### Client
1. To transmit a message, execute the `client` executable with the following arguments:
```bash
./client <server_pid> <message>
```
- `<server_pid>`: The process ID of the server (obtained from the server's console output).
- `<message>`: The message you want to transmit to the server.

2. The client will convert the message into individual characters and send them bit by bit to the server.
> This will generate two executables: `client` and `server`.
3. The server will receive the signals and reconstruct the transmitted message.
3. Launch the server by executing the `server` binary:
```bash
./server
```

4. The server will print the received message character by character on the console.
> The server will display its process ID (PID) on the console.
5. Repeat the steps to send additional messages.
4. In a separate terminal window, launch the client by executing the client binary with the server's PID and the message you want to transmit:

## Implementation Details
```bash
./client <server_pid> <message>
```

### Client (`client.c`)
The client is responsible for transmitting the message to the server.
> Replace `<server_pid>` with the PID displayed by the server, and `<message>` with the text you want to send.
1. The `send_signal` function takes the server's PID and a character as input. It sends the character bit by bit to the server using signals.
- For each bit of the character, it sends `SIGUSR1` if the bit is 1 or `SIGUSR2` if it is 0.
- It uses the `kill` function to send the signals and `usleep` to introduce a small delay between each signal.
Example:
```bash
./client 12345 Hello
```

2. The `main` function in the client takes the server's PID and message as command-line arguments.
- It iterates through each character in the message and calls the `send_signal` function to transmit it to the server.
> This will send the message "Hello" to the server with the PID 12345.
### Server (`server.c`)
The server is responsible for receiving and printing the transmitted message.
5. The server will receive the message and display it on the console:

1. The `handle_signal` function is the signal handler for `SIGUSR1` and `SIGUSR2`.
- It maintains a static `current_char` variable to store the bits of the received character.
- It also keeps track of the current bit index.
```bash
Hello
```

2. When a signal is received, the `handle_signal` function checks if it is `SIGUSR1`.
- If it is, it assigns 1 to the least significant bit (LSB) of the `current_char`.
- If it is `SIGUSR2`, the `current_char` remains unchanged (0).
> The server will display each character as it receives them.
3. The `handle_signal` function increments the bit index.
6. You can repeat steps 4 and 5 to send multiple messages to the server.

4. If the bit index reaches 8, it means that a full character has been received.
- The function prints the character using `ft_printf` and resets the bit index and `current_char`.
- Otherwise, it shifts `current_char` to the left by 1 to make room for the next bit.
## How Does Minitalk Work?

5. The `main` function starts the server by registering the `handle_signal` function as the handler for `SIGUSR1` and `SIGUSR2`.
The communication between the client and server is achieved using signals.

6. The server then enters an infinite loop using pause, waiting for signals to arrive.
The client converts each character of the message into 8 bits (1 byte) and sends them to the server one by one.

7. Whenever a signal is received, the corresponding signal handler is called to process it.
### Client
1. The client reads the server's PID and the message from the command-line arguments.
2. It iterates over each character in the message.
3. For each character, it calls the `send_signal` function, which sends 8 signals to the server.
4. The `send_signal` function converts the character into 8 bits and sends each bit as a signal to the server. It uses `SIGUSR1` to represent a 1 bit and `SIGUSR2` to represent a 0 bit.
5. After sending each bit, the client waits for a short duration (42 microseconds) using the `usleep` function. This delay allows the server to process the received signals.

### Example
### Server
1. The server starts by displaying its PID on the console.
2. It sets up signal handlers for `SIGUSR1` and `SIGUSR2` signals using the `sigaction` function.
3. The server enters an infinite loop and waits for signals using the `pause` function.
4. When a signal is received, the corresponding signal handler (`handle_signal`) is called.
5. The `handle_signal` function extracts the bit value (0 or 1) from the received signal and appends it to the current character being received.
6. If the character is fully received (8 bits), it is displayed on the console using `ft_printf`. The bit index and current character are reset to prepare for the next character.
7. After processing the received signal, the server sends a signal back to the client. If the received signal was SIGUSR1, it sends SIGUSR1 to acknowledge the received bit. If the received signal was SIGUSR2, it sends SIGUSR2.

Here’s an example of how to use the Minitalk project:
### Bonus Features

1. Start the server by running ./server in one terminal. Note down the server’s PID displayed on the console.
2. In another terminal, execute ./client <server_pid> "Hello, World!" to send the message “Hello, World!” to the server. Replace <server_pid> with the actual PID obtained in step 1.
3. The server will receive the signals, reconstruct the message, and print it as follows:
The provided source code includes a bonus version (`client_bonus.c` and `server_bonus.c`) that adds additional functionality:

Hello, World!
* Unicode characters like 🦁 are already supported in the mandatory part.
* Sending back a read receipt can be achieved by using the `sigaction` structure, that allows to access metadata about signal transmission.
* The client displays a message on the console for each bit it sends. It prints "Received bit 1" for `SIGUSR1` and "Received bit 0" for `SIGUSR2`. This can help visualize the communication process.
* The server sends an acknowledgment signal back to the client after receiving each bit. If the received signal was `SIGUSR1`, it sends `SIGUSR1` to the client. If the received signal was `SIGUSR2`, it sends `SIGUSR2`. This allows the client to know that the server has successfully received the bit.
These additional features enhance the interactivity and feedback during the communication process.

## Credits

4. You can send more messages by repeating step 2 with different messages.
5. To stop the server, you can use Ctrl+C in the terminal where the server is running.
*🙇🏻‍♂️ This project is largely based on the work and explanations of [ealgar-c](https://github.com/ealgar-c).*

This README provides an overview of the Minitalk project, how to compile and use it, and explains the implementation details of both the client and server components. Make sure to adjust any formatting or specific details according to your needs.
Link to [ealgar-c/minitalk🗣️](https://github.com/ealgar-c/minitalk)

0 comments on commit 63143cf

Please sign in to comment.