1.. zephyr:code-sample:: sockets-socketpair
2   :name: Socketpair
3   :relevant-api: bsd_sockets
4
5   Implement communication between threads using socket pairs.
6
7Overview
8********
9
10The sockets/socketpair sample application for Zephyr demonstrates a
11multi-threaded application communicating over pairs of unnamed,
12connected UNIX-domain sockets. The pairs of sockets are created with
13socketpair(2), as you might have guessed. Such sockets are compatible
14with the BSD Sockets API, and therefore the purpose of this sample
15is also to reinforce that it is possible to develop a sockets
16application portable to both POSIX and Zephyr.
17
18The source code for this sample application can be found at:
19:zephyr_file:`samples/net/sockets/socketpair`.
20
21Requirements
22************
23
24None
25
26Building and Running
27********************
28
29Build the Zephyr version of the sockets/echo application like this:
30
31.. zephyr-app-commands::
32   :zephyr-app: samples/net/sockets/socketpair
33   :board: <board_to_use>
34   :goals: build
35   :compact:
36
37After the sample starts, several client threads are spawned. Each client
38thread sends a fixed number of messages to the server (main).
39
40.. code-block:: console
41
42    *** Booting Zephyr OS build v3.3.0-rc1-97-g432ff20a72e1 ***
43    setting-up
44    Alpha: socketpair: 4 <=> 3
45    Bravo: socketpair: 6 <=> 5
46    Charlie: socketpair: 8 <=> 7
47    main: read 'Alpha' on fd 4
48    main: read 'Bravo' on fd 6
49    main: read 'Charlie' on fd 8
50    main: read 'Alpha' on fd 4
51    main: read 'Bravo' on fd 6
52    main: read 'Charlie' on fd 8
53    main: read 'Alpha' on fd 4
54    main: read 'Bravo' on fd 6
55    main: read 'Charlie' on fd 8
56    tearing-down
57    SUCCESS
58
59Running application on POSIX Host
60=================================
61
62The same application source code can be built for a POSIX system, e.g.
63Linux.
64
65To build:
66
67.. code-block:: console
68
69    $ make -f Makefile.host
70
71To run:
72
73.. code-block:: console
74
75    ./socketpair_example
76    setting-up
77    Alpha: socketpair: 3 <=> 4
78    Bravo: socketpair: 5 <=> 6
79    Charlie: socketpair: 7 <=> 8
80    main: read 'Alpha' on fd 3
81    main: read 'Bravo' on fd 5
82    main: read 'Charlie' on fd 7
83    main: read 'Alpha' on fd 3
84    main: read 'Alpha' on fd 3
85    main: read 'Bravo' on fd 5
86    main: read 'Charlie' on fd 7
87    main: read 'Bravo' on fd 5
88    main: read 'Charlie' on fd 7
89    tearing-down
90    SUCCESS
91
92As can be seen, the behavior of the application is approximately the same as
93the Zephyr version.
94