Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rename process.h -> subprocess.h and all the functions. #13

Merged
merged 1 commit into from Jan 1, 2020
Merged

Rename process.h -> subprocess.h and all the functions. #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
57 changes: 29 additions & 28 deletions README.md
View file
Open in desktop
@@ -1,33 +1,33 @@
# 🐜 process.h
# 🐜 subprocess.h

[![Build status](https://ci.appveyor.com/api/projects/status/0sm37thiavt9juee?svg=true)](https://ci.appveyor.com/project/sheredom/process-h)
[![Build Status](https://travis-ci.org/sheredom/process.h.svg)](https://travis-ci.org/sheredom/process.h)
[![Build status](https://ci.appveyor.com/api/projects/status/0sm37thiavt9juee?svg=true)](https://ci.appveyor.com/project/sheredom/subprocess-h)
[![Build Status](https://travis-ci.org/sheredom/subprocess.h.svg)](https://travis-ci.org/sheredom/process.h)

A simple one header solution to launching processes and interacting with them
for C/C++.

## Usage

Just `#include "process.h"` in your code!
Just `#include "subprocess.h"` in your code!

The current supported compilers are gcc, clang and msvc.

The current supported platforms are Linux, macOS and Windows.

## Design

Process is a single header cross-platform library that allows users to launch
processes, interact with the stdin, stdout, and stderr of the process, and wait
for the process to complete.
Subprocess is a single header cross-platform library that allows users to launch
sub-processes, interact with the stdin, stdout, and stderr of the process, and
wait for them to complete.

### Launching a Process

To launch a process you call `process_create` like so:
To launch a process you call `subprocess_create` like so:

```c
const char *command_line[] = {"echo", "\"Hello, world!\"", NULL};
struct process_s process;
int result = process_create(command_line, 0, &process);
struct subprocess_s subprocess;
int result = subprocess_create(command_line, 0, &subprocess);
if (0 != result) {
// an error occurred!
}
Expand All @@ -36,60 +36,61 @@ if (0 != result) {
You specify an array of string for the command line - terminating the array with
a `NULL` element.

If the process is created successfully then 0 is returned from `process_create`.
If the process is created successfully then 0 is returned from
`subprocess_create`.

### Writing to the Standard Input of a Process

To write to the standard input of a child process you call `process_stdin` to
To write to the standard input of a child process you call `subprocess_stdin` to
get the FILE handle to write with, passing a previously created process, like
so:

```c
FILE* p_stdin = process_stdin(&process);
FILE* p_stdin = subprocess_stdin(&process);
fputs("Hello, world!", p_stdin);
```

Care must be taken to not write to the stdin after any call to `process_join` or
`process_destroy`.
Care must be taken to not write to the stdin after any call to `subprocess_join`
or `subprocess_destroy`.

### Reading from the Standard Output of a Process

To read from the standard output of a child process you call `process_stdout` to
get the FILE handle to read with, passing a previously created process, like
To read from the standard output of a child process you call `subprocess_stdout`
to get the FILE handle to read with, passing a previously created process, like
so:

```c
FILE* p_stdout = process_stdout(&process);
FILE* p_stdout = subprocess_stdout(&process);
char hello_world[32];
fgets(hello_world, 32, p_stdout);
```

Care must be taken to not read from the stdout after any call to
`process_destroy`.
`subprocess_destroy`.

### Reading from the Standard Error of a Process

To read from the standard error of a child process you call `process_stderr` to
get the FILE handle to read with, passing a previously created process, like
To read from the standard error of a child process you call `subprocess_stderr`
to get the FILE handle to read with, passing a previously created process, like
so:

```c
FILE* p_stderr = process_stderr(&process);
FILE* p_stderr = subprocess_stderr(&process);
char hello_world[32];
fgets(hello_world, 32, p_stderr);
```

Care must be taken to not read from the stderr after any call to
`process_destroy`.
`subprocess_destroy`.

### Waiting on a Process

To wait for a previously created process to finish executing you call
`process_join` like so:
`subprocess_join` like so:

```c
int process_return;
int result = process_join(&process, &process_return);
int result = subprocess_join(&process, &process_return);
if (0 != result) {
// an error occurred!
}
Expand All @@ -101,10 +102,10 @@ don't care about the process' return code.

### Destroying a Process

To destroy a previously created process you call `process_destroy` like so:
To destroy a previously created process you call `subprocess_destroy` like so:

```c
int result = process_destroy(&process);
int result = subprocess_destroy(&process);
if (0 != result) {
// an error occurred!
}
Expand All @@ -118,7 +119,7 @@ process for instance.

The current list of todos:

* Add the ability to [set environment variables of the child process](https://github.com/sheredom/process.h/issues/1)
* Add the ability to [set environment variables of the child process](https://github.com/sheredom/subprocess.h/issues/1)
as suggested by [@graphitemaster](https://github.com/graphitemaster).
* Add the ability to specify if a child process should die if the parent process
is terminated.
Expand Down