<commit_before>czmq(7)
=======


NAME
----
czmq - high-level C binding for ZeroMQ


SYNOPSIS
--------
----
#include <czmq.h>

cc ['flags'] 'files' -lzmq -lczmq ['libraries']
----


DESCRIPTION
-----------

Classes
~~~~~~~

These classes provide the main socket and message API:

* linkczmq:zsock[3] - working with ZeroMQ sockets (high-level)
* linkczmq:zstr[3] - sending and receiving strings
* linkczmq:zmsg[3] - working with multipart messages
* linkczmq:zframe[3] - working with single message frames
* linkczmq:zactor[3] - Actor class (socket + thread)
* linkczmq:zloop[3] - event-driven reactor
* linkczmq:zpoller[3] - trivial socket poller class
* linkczmq:zproxy[3] - proxy actor (like zmq_proxy_steerable)
* linkczmq:zmonitor[3] - monitor events on ZeroMQ sockets

These classes support authentication and encryption:

* linkczmq:zauth[3] - authentication actor for ZeroMQ servers
* linkczmq:zcert[3] - work with CURVE security certificates
* linkczmq:zcertstore[3] - work with CURVE security certificate stores

These classes provide generic containers:

* linkczmq:zhash[3] - simple generic hash container
* linkczmq:zhashx[3] - extended generic hash container
* linkczmq:zlist[3] - simple generic list container
* linkczmq:zlistx[3] - extended generic list container

These classes wrap-up non-portable functionality:

* linkczmq:zbeacon[3] - LAN discovery and presence
* linkczmq:zclock[3] - millisecond clocks and delays
* linkczmq:zdir[3] - work with file-system directories
* linkczmq:zdir_patch[3] - work with directory differences
* linkczmq:zfile[3] - work with file-system files
* linkczmq:zsys[3] - system-level methods
* linkczmq:zuuid[3] - UUID support class
* linkczmq:ziflist[3] - list available network interfaces

And these utility classes add value:

* linkczmq:zchunk[3] - work with memory chunks
* linkczmq:zconfig[3] - work with textual config files
* linkczmq:zrex[3] - work with regular expressions
* linkczmq:zgossip[3] - decentralized configuration management

These classes are deprecated:

* linkczmq:zctx[3] - working with ZeroMQ contexts
* linkczmq:zsocket[3] - working with ZeroMQ sockets (low-level)
* linkczmq:zsockopt[3] - get/set ZeroMQ socket options
* linkczmq:zthread[3] - working with system threads
* linkczmq:zauth_v2[3] - authentication for ZeroMQ servers
* linkczmq:zbeacon_v2[3] - LAN discovery and presence
* linkczmq:zmonitor_v2[3] - socket event monitor
* linkczmq:zproxy_v2[3] - zmq_proxy wrapper

Scope and Goals
~~~~~~~~~~~~~~~

CZMQ has these goals:

* To wrap the ØMQ core API in semantics that are natural and lead to shorter, more readable applications.
* To hide the differences between versions of ØMQ.
* To provide a space for development of more sophisticated API semantics.

Ownership and License
~~~~~~~~~~~~~~~~~~~~~

CZMQ is maintained by the ZeroMQ community at github.com/zeromq. Its other authors and contributors are listed in the AUTHORS file.

The contributors are listed in AUTHORS. This project uses the MPL v2 license, see LICENSE.

Contributing
~~~~~~~~~~~~

To submit an issue use the issue tracker at http://github.com/zeromq/czmq/issues. All discussion happens on the  zeromq-dev list or #zeromq IRC channel at irc.freenode.net.

The proper way to submit patches is to clone this repository, make your changes, and use git to create a patch or a pull request. See http://www.zeromq.org/docs:contributing. All contributors are listed in AUTHORS.

All classes are maintained by a single person, who is the responsible editor for that class and who is named in the header as such. This is usually the originator of the class. When several people collaborate on a class, one single person is always the lead maintainer and the one to blame when it breaks.

The general rule is, if you contribute code to CZMQ you must be willing to maintain it as long as there are users of it. Code with no active maintainer will in general be deprecated and/or removed.

USING CZMQ
----------

Building and Installing
~~~~~~~~~~~~~~~~~~~~~~~

CZMQ uses autotools for packaging. To build from git (all example commands are for Linux):
----
    git clone git://github.com/zeromq/czmq.git
    cd czmq
    sh autogen.sh
    ./configure
    make all
    sudo make install
    sudo ldconfig
----

You will need the pkg-config, libtool, and autoreconf packages. Set the LD_LIBRARY_PATH to /usr/local/libs unless you install elsewhere.

After building, you can run the CZMQ selftests:
----
    cd src
    ./czmq_selftest
----

Linking with an Application
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Include `czmq.h` in your application and link with CZMQ. Here is a typical gcc link command:
----
    gcc -lczmq -lzmq myapp.c -o myapp
----

You should read `czmq.h`. This file includes `zmq.h` and the system header files that typical ØMQ applications will need. The provided 'c' shell script lets you write simple portable build scripts:
----
    c -lczmq -lzmq -l myapp
----

The Class Model
~~~~~~~~~~~~~~~

CZMQ consists of classes, each class consisting of a .h and a .c. Classes may depend on other classes.

`czmq.h` includes all classes header files, all the time. For the user, CZMQ forms one single package. All classes start by including `czmq.h`. All applications that use CZMQ start by including `czmq.h`. `czmq.h` also defines a limited number of small, useful macros and typedefs that have proven useful for writing clearer C code.

All classes (with some exceptions) are based on a flat C class system and follow these rules (where 'zclass' is the class name):

* Class typedef: `zclass_t`
* Constructor: `zclass_new`
* Destructor: `zclass_destroy`
* Property methods: `zclass_property_set`, `zclass_property`
* Class structures are private (defined in the .c source but not the .h)
* Properties are accessed only via methods named as described above.
* In the class source code the object is always called `self`.
* The constructor may take arbitrary arguments, and returns NULL on failure, or a new object.
* The destructor takes a pointer to an object reference and nullifies it.

Return values for methods are:

* For methods that return an object reference, either the reference, or NULL on failure.
* For methods that signal success/failure, a return value of 0 means sucess, -1 failure.

Private/static functions in a class are named `s_functionname` and are not exported via the header file.

All classes (with some exceptions) have a test method called `zclass_test`.

Design Ideology
---------------

The Problem with C
~~~~~~~~~~~~~~~~~~

C has the significant advantage of being a small language that, if we take a little care with formatting and naming, can be easily interchanged between developers. Every C developer will use much the same 90% of the language. Larger languages like C++ provide powerful abstractions like STL containers but at the cost of interchange. 

The huge problem with C is that any realistic application needs packages of functionality to bring the language up to the levels we expect for the 21st century. Much can be done by using external libraries but every additional library is a dependency that makes the resulting applications harder to build and port. While C itself is a highly portable language (and can be made more so by careful use of the preprocessor), most C libraries consider themselves part of the operating system, and as such do not attempt to be portable.

The answer to this, as we learned from building enterprise-level C applications at iMatix from 1995-2005, is to create our own fully portable, high-quality libraries of pre-packaged functionality, in C. Doing this right solves both the requirements of richness of the language, and of portability of the final applications.

A Simple Class Model
~~~~~~~~~~~~~~~~~~~~<commit_msg>Problem: typo in CZMQ manpage<commit_after>czmq(7)
=======


NAME
----
czmq - high-level C binding for ZeroMQ


SYNOPSIS
--------
----
#include <czmq.h>

cc ['flags'] 'files' -lzmq -lczmq ['libraries']
----


DESCRIPTION
-----------

Classes
~~~~~~~

These classes provide the main socket and message API:

* linkczmq:zsock[3] - working with ZeroMQ sockets (high-level)
* linkczmq:zstr[3] - sending and receiving strings
* linkczmq:zmsg[3] - working with multipart messages
* linkczmq:zframe[3] - working with single message frames
* linkczmq:zactor[3] - Actor class (socket + thread)
* linkczmq:zloop[3] - event-driven reactor
* linkczmq:zpoller[3] - trivial socket poller class
* linkczmq:zproxy[3] - proxy actor (like zmq_proxy_steerable)
* linkczmq:zmonitor[3] - monitor events on ZeroMQ sockets

These classes support authentication and encryption:

* linkczmq:zauth[3] - authentication actor for ZeroMQ servers
* linkczmq:zcert[3] - work with CURVE security certificates
* linkczmq:zcertstore[3] - work with CURVE security certificate stores

These classes provide generic containers:

* linkczmq:zhash[3] - simple generic hash container
* linkczmq:zhashx[3] - extended generic hash container
* linkczmq:zlist[3] - simple generic list container
* linkczmq:zlistx[3] - extended generic list container

These classes wrap-up non-portable functionality:

* linkczmq:zbeacon[3] - LAN discovery and presence
* linkczmq:zclock[3] - millisecond clocks and delays
* linkczmq:zdir[3] - work with file-system directories
* linkczmq:zdir_patch[3] - work with directory differences
* linkczmq:zfile[3] - work with file-system files
* linkczmq:zsys[3] - system-level methods
* linkczmq:zuuid[3] - UUID support class
* linkczmq:ziflist[3] - list available network interfaces

And these utility classes add value:

* linkczmq:zchunk[3] - work with memory chunks
* linkczmq:zconfig[3] - work with textual config files
* linkczmq:zrex[3] - work with regular expressions
* linkczmq:zgossip[3] - decentralized configuration management

These classes are deprecated:

* linkczmq:zctx[3] - working with ZeroMQ contexts
* linkczmq:zsocket[3] - working with ZeroMQ sockets (low-level)
* linkczmq:zsockopt[3] - get/set ZeroMQ socket options
* linkczmq:zthread[3] - working with system threads
* linkczmq:zauth_v2[3] - authentication for ZeroMQ servers
* linkczmq:zbeacon_v2[3] - LAN discovery and presence
* linkczmq:zmonitor_v2[3] - socket event monitor
* linkczmq:zproxy_v2[3] - zmq_proxy wrapper

Scope and Goals
~~~~~~~~~~~~~~~

CZMQ has these goals:

* To wrap the ØMQ core API in semantics that are natural and lead to shorter, more readable applications.
* To hide the differences between versions of ØMQ.
* To provide a space for development of more sophisticated API semantics.

Ownership and License
~~~~~~~~~~~~~~~~~~~~~

CZMQ is maintained by the ZeroMQ community at github.com/zeromq. Its other authors and contributors are listed in the AUTHORS file.

The contributors are listed in AUTHORS. This project uses the MPL v2 license, see LICENSE.

Contributing
~~~~~~~~~~~~

To submit an issue use the issue tracker at http://github.com/zeromq/czmq/issues. All discussion happens on the  zeromq-dev list or #zeromq IRC channel at irc.freenode.net.

The proper way to submit patches is to clone this repository, make your changes, and use git to create a patch or a pull request. See http://www.zeromq.org/docs:contributing. All contributors are listed in AUTHORS.

All classes are maintained by a single person, who is the responsible editor for that class and who is named in the header as such. This is usually the originator of the class. When several people collaborate on a class, one single person is always the lead maintainer and the one to blame when it breaks.

The general rule is, if you contribute code to CZMQ you must be willing to maintain it as long as there are users of it. Code with no active maintainer will in general be deprecated and/or removed.

USING CZMQ
----------

Building and Installing
~~~~~~~~~~~~~~~~~~~~~~~

CZMQ uses autotools for packaging. To build from git (all example commands are for Linux):
----
    git clone git://github.com/zeromq/czmq.git
    cd czmq
    sh autogen.sh
    ./configure
    make all
    sudo make install
    sudo ldconfig
----

You will need the pkg-config, libtool, and autoreconf packages. Set the LD_LIBRARY_PATH to /usr/local/libs unless you install elsewhere.

After building, you can run the CZMQ selftests:
----
    cd src
    ./czmq_selftest
----

Linking with an Application
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Include `czmq.h` in your application and link with CZMQ. Here is a typical gcc link command:
----
    gcc -lczmq -lzmq myapp.c -o myapp
----

You should read `czmq.h`. This file includes `zmq.h` and the system header files that typical ØMQ applications will need. The provided 'c' shell script lets you write simple portable build scripts:
----
    c -lczmq -lzmq -l myapp
----

The Class Model
~~~~~~~~~~~~~~~

CZMQ consists of classes, each class consisting of a .h and a .c. Classes may depend on other classes.

`czmq.h` includes all classes header files, all the time. For the user, CZMQ forms one single package. All classes start by including `czmq.h`. All applications that use CZMQ start by including `czmq.h`. `czmq.h` also defines a limited number of small, useful macros and typedefs that have proven useful for writing clearer C code.

All classes (with some exceptions) are based on a flat C class system and follow these rules (where 'zclass' is the class name):

* Class typedef: `zclass_t`
* Constructor: `zclass_new`
* Destructor: `zclass_destroy`
* Property methods: `zclass_property_set`, `zclass_property`
* Class structures are private (defined in the .c source but not the .h)
* Properties are accessed only via methods named as described above.
* In the class source code the object is always called `self`.
* The constructor may take arbitrary arguments, and returns NULL on failure, or a new object.
* The destructor takes a pointer to an object reference and nullifies it.

Return values for methods are:

* For methods that return an object reference, either the reference, or NULL on failure.
* For methods that signal success/failure, a return value of 0 means success, -1 failure.

Private/static functions in a class are named `s_functionname` and are not exported via the header file.

All classes (with some exceptions) have a test method called `zclass_test`.

Design Ideology
---------------

The Problem with C
~~~~~~~~~~~~~~~~~~

C has the significant advantage of being a small language that, if we take a little care with formatting and naming, can be easily interchanged between developers. Every C developer will use much the same 90% of the language. Larger languages like C++ provide powerful abstractions like STL containers but at the cost of interchange. 

The huge problem with C is that any realistic application needs packages of functionality to bring the language up to the levels we expect for the 21st century. Much can be done by using external libraries but every additional library is a dependency that makes the resulting applications harder to build and port. While C itself is a highly portable language (and can be made more so by careful use of the preprocessor), most C libraries consider themselves part of the operating system, and as such do not attempt to be portable.

The answer to this, as we learned from building enterprise-level C applications at iMatix from 1995-2005, is to create our own fully portable, high-quality libraries of pre-packaged functionality, in C. Doing this right solves both the requirements of richness of the language, and of portability of the final applications.

A Simple Class Model
~~~~~~~~~~~~~~~~~~~~
{'fraction_non_alphanumeric': 0.0892109500805153, 'fraction_numerical': 0.007214170692431562, 'mean_word_length': 4.232895180316818, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3336064', 'n_tokens_mistral': 4439, 'n_tokens_neox': 4228, 'n_words': 2060}