git: c4207d867c20 - main - fork.2: Add a simple use pattern

[Konstantin Belousov]

On Sat, Apr 17, 2021 at 09:13:06PM +0000, Mateusz Piotrowski wrote:
> The branch main has been updated by 0mp (doc, ports committer):
> 
> URL: https://cgit.FreeBSD.org/src/commit/?id=c4207d867c201a726aa3157e09262f72166c89c4
> 
> commit c4207d867c201a726aa3157e09262f72166c89c4
> Author:     Mateusz Piotrowski <0mp at FreeBSD.org>
> AuthorDate: 2021-04-17 21:10:48 +0000
> Commit:     Mateusz Piotrowski <0mp at FreeBSD.org>
> CommitDate: 2021-04-17 21:12:06 +0000
> 
>     fork.2: Add a simple use pattern
>     
>     It seems to be a nice idea to show how fork() is usually used in
>     practice. This may act as a guide to developers who want to quickly
>     recall how to use the fork() function.
>     
>     Reviewed by:    bcr, yuripv
>     MFC after:      1 week
>     Differential Revision:  https://reviews.freebsd.org/D27626
> ---
>  lib/libc/sys/fork.2 | 38 +++++++++++++++++++++++++++++++++++++-
>  1 file changed, 37 insertions(+), 1 deletion(-)
> 
> diff --git a/lib/libc/sys/fork.2 b/lib/libc/sys/fork.2
> index 3e55530827c5..d43ade6a483e 100644
> --- a/lib/libc/sys/fork.2
> +++ b/lib/libc/sys/fork.2
> @@ -28,7 +28,7 @@
>  .\"	@(#)fork.2	8.1 (Berkeley) 6/4/93
>  .\" $FreeBSD$
>  .\"
> -.Dd December 1, 2017
> +.Dd April 17, 2021
>  .Dt FORK 2
>  .Os
>  .Sh NAME
> @@ -99,6 +99,42 @@ to the parent process, no child process is created, and the global
>  variable
>  .Va errno
>  is set to indicate the error.
> +.Sh EXAMPLES
> +The following example shows a common pattern of how
> +.Fn fork
> +is used in practice.
> +.Bd -literal -offset indent
> +#include <err.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <unistd.h>
> +
> +int
> +main(void)
> +{
> +	pid_t pid;
> +
> +	switch (pid = fork()) {
> +	case -1:
> +		err(1, "Failed to fork");
> +	case 0:
> +		printf("Hello from child process!\en");
> +		exit(0);
> +	default:
> +		break;
> +	}
> +
> +	printf("Hello from parent process (child's PID: %d)!\en", pid);
> +
> +	return (0);
> +}
> +.Ed
> +.Pp
> +The output of such a program is along the lines of:
> +.Bd -literal -offset indent
> +Hello from parent (child's PID: 27804)!
> +Hello from child process!
> +.Ed
>  .Sh ERRORS
>  The
>  .Fn fork
Using printf around fork is not the best idea, and definitely should not
be provided as a guiding example in the man page.  Using stdio safely around
fork() requires at least flushing buffers and ensuring that opened FILEs are
in some consistent state right at fork.

It would work by chance in your example, mostly because you did not used
anything in stdio before fork, but any further changes would result in
very puzzling bugs (for beginners, who are the target of this example).