> For the complete documentation index, see [llms.txt](https://computerscienceeducation.gitbook.io/co-lab-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://computerscienceeducation.gitbook.io/co-lab-manual/assignments/mandatory-assignments/a2-subroutines-and-i-o.md).

# A1: Subroutines and I/O

{% hint style="info" %}
**CMake target**: `a1` 

```bash
cmake --build .build --target a1
```

{% endhint %}

Most programs you have written in your life likely make heavy use of abstraction by using functions (in the context of Assembly known as *subroutines*). Furthermore, in various applications, it is often essential to obtain input from the user. This assignment will build and test your knowledge of both subroutines and I/O.

***

## Assignment

Write a program that reads a number from the user, calls a subroutine to increment the number, and prints the returned value.

### Subroutine

The subroutine should have the signature:

```c
int64_t my_inc(int64_t n)
```

It takes a single (64-bit signed) number as its argument and returns the number incremented by 1. The subroutine itself should not print the incremented number but simply return it.

{% hint style="warning" %}
Your function must **follow all calling conventions**, including a proper prologue and epilogue, such that it can even be called from outside of your main program and still offer the expected functionality.
{% endhint %}

{% hint style="success" %}
Note that **overflow is considered a natural limitation**. You should not handle cases of overflow explicitly.
{% endhint %}

### Main Program

Your `main` program should use `scanf` to read a number from the terminal, pass the number to the `my_inc` subroutine, and print the returned value such that the final output looks like this:

```
Enter a number: <x>
The incremented number is: <x+1>
```

where `<x>` represents the input the user types into the terminal (it does not need to be printed again) and `<x+1>` represents the incremented number.

{% hint style="success" %}
Make sure that your `main` program still returns with the **correct exit code** (0) and not the value read from the user.
{% endhint %}

***

## Recommended Approach

1. Implement an "empty" `my_inc` subroutine that, with the proper prologue and epilogue, directly returns. Implement the `main` routine in such a way that it calls the subroutine before returning.
2. Extend your `main` program with calls to `printf` for printing the prompt and `scanf` for reading a number from the user.
3. Pass the number as the first argument in the call to `my_inc`.
4. Extend your subroutine such that it increments and returns the argument.
5. Finally, add the required print statement to your `main` program to print the result.

{% hint style="info" %}
**Hint:** Now may be a good time to start working with the debugger.

You are using multiple library functions in combination. If things go wrong (which they likely will) it may help to check for the results of the individual parts of your program (e.g., the call to `scanf`) or trace the program flow - which is greatly facilitated by a debugger.

If you have never used a debugger before or need a quick refresher on how to work with it, there is an introductory guide in the [Appendix](/co-lab-manual/appendix/how-to-use-a-debugger.md).
{% endhint %}

***

## Required Knowledge

In order to fulfil this assignment, you will need to further extend your toolbox:

* You should know how to reserve space for and access [Local Variables](/co-lab-manual/reference-documentation/subroutines/writing-subroutines.md#local-variables) as part of your `main` routine (such that you can allocate space for and retrieve the number read by `scanf`).
* As you need to obtain input from the user, you should know how to [Read from the Terminal](/co-lab-manual/reference-documentation/input-output/reading-from-the-terminal.md).