GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  ZSYS (3)

.ds Aq ’

NAME

zsys - system-level methods

CONTENTS

SYNOPSIS

#define UDP_FRAME_MAX   255         //  Max size of UDP frame

// Callback for interrupt signal handler typedef void (zsys_handler_fn) (int signal_value);

// Initialize CZMQ zsys layer; this happens automatically when you create // a socket or an actor; however this call lets you force initialization // earlier, so e.g. logging is properly set-up before you start working. // Not threadsafe, so call only from main thread. Safe to call multiple // times. Returns global CZMQ context. CZMQ_EXPORT void * zsys_init (void);

// Optionally shut down the CZMQ zsys layer; this normally happens automatically // when the process exits; however this call lets you force a shutdown // earlier, avoiding any potential problems with atexit() ordering, especially // with Windows dlls. CZMQ_EXPORT void zsys_shutdown (void);

// Get a new ZMQ socket, automagically creating a ZMQ context if this is // the first time. Caller is responsible for destroying the ZMQ socket // before process exits, to avoid a ZMQ deadlock. Note: you should not use // this method in CZMQ apps, use zsock_new() instead. // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT void * zsys_socket (int type, const char *filename, size_t line_nbr);

// Destroy/close a ZMQ socket. You should call this for every socket you // create using zsys_socket(). // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT int zsys_close (void *handle, const char *filename, size_t line_nbr);

// Return ZMQ socket name for socket type // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT char * zsys_sockname (int socktype);

// Create a pipe, which consists of two PAIR sockets connected over inproc. // The pipe is configured to use the zsys_pipehwm setting. Returns the // frontend socket successful, NULL if failed. CZMQ_EXPORT zsock_t * zsys_create_pipe (zsock_t **backend_p);

// Set interrupt handler; this saves the default handlers so that a // zsys_handler_reset () can restore them. If you call this multiple times // then the last handler will take affect. If handler_fn is NULL, disables // default SIGINT/SIGTERM handling in CZMQ. CZMQ_EXPORT void zsys_handler_set (zsys_handler_fn *handler_fn);

// Reset interrupt handler, call this at exit if needed CZMQ_EXPORT void zsys_handler_reset (void);

// Set default interrupt handler, so Ctrl-C or SIGTERM will set // zsys_interrupted. Idempotent; safe to call multiple times. // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT void zsys_catch_interrupts (void);

// Return 1 if file exists, else zero CZMQ_EXPORT bool zsys_file_exists (const char *filename);

// Return size of file, or -1 if not found CZMQ_EXPORT ssize_t zsys_file_size (const char *filename);

// Return file modification time. Returns 0 if the file does not exist. CZMQ_EXPORT time_t zsys_file_modified (const char *filename);

// Return file mode; provides at least support for the POSIX S_ISREG(m) // and S_ISDIR(m) macros and the S_IRUSR and S_IWUSR bits, on all boxes. // Returns a mode_t cast to int, or -1 in case of error. CZMQ_EXPORT int zsys_file_mode (const char *filename);

// Delete file. Does not complain if the file is absent CZMQ_EXPORT int zsys_file_delete (const char *filename);

// Check if file is stable CZMQ_EXPORT bool zsys_file_stable (const char *filename);

// Create a file path if it doesnt exist. The file path is treated as a // printf format. CZMQ_EXPORT int zsys_dir_create (const char *pathname, ...);

// Remove a file path if empty; the pathname is treated as printf format. CZMQ_EXPORT int zsys_dir_delete (const char *pathname, ...);

// Move to a specified working directory. Returns 0 if OK, -1 if this failed. CZMQ_EXPORT int zsys_dir_change (const char *pathname);

// Set private file creation mode; all files created from here will be // readable/writable by the owner only. CZMQ_EXPORT void zsys_file_mode_private (void);

// Reset default file creation mode; all files created from here will use // process file mode defaults. CZMQ_EXPORT void zsys_file_mode_default (void);

// Return the CZMQ version for run-time API detection; returns version // number into provided fields, providing reference isnt null in each case. CZMQ_EXPORT void zsys_version (int *major, int *minor, int *patch);

// Format a string using printf formatting, returning a freshly allocated // buffer. If there was insufficient memory, returns NULL. Free the returned // string using zstr_free(). CZMQ_EXPORT char * zsys_sprintf (const char *format, ...);

// Format a string with a va_list argument, returning a freshly allocated // buffer. If there was insufficient memory, returns NULL. Free the returned // string using zstr_free(). CZMQ_EXPORT char * zsys_vprintf (const char *format, va_list argptr);

// Create UDP beacon socket; if the routable option is true, uses // multicast (not yet implemented), else uses broadcast. This method // and related ones might _eventually_ be moved to a zudp class. // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT SOCKET zsys_udp_new (bool routable);

// Close a UDP socket // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT int zsys_udp_close (SOCKET handle);

// Send zframe to UDP socket, return -1 if sending failed due to // interface having disappeared (happens easily with WiFi) // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT int zsys_udp_send (SOCKET udpsock, zframe_t *frame, inaddr_t *address);

// Receive zframe from UDP socket, and set address of peer that sent it // The peername must be a char [INET_ADDRSTRLEN] array. // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT zframe_t * zsys_udp_recv (SOCKET udpsock, char *peername);

// Handle an I/O error on some socket operation; will report and die on // fatal errors, and continue silently on "try again" errors. // *** This is for CZMQ internal use only and may change arbitrarily *** CZMQ_EXPORT void zsys_socket_error (const char *reason);

// Return current host name, for use in public tcp:// endpoints. Caller gets // a freshly allocated string, should free it using zstr_free(). If the host // name is not resolvable, returns NULL. CZMQ_EXPORT char * zsys_hostname (void);

// Move the current process into the background. The precise effect depends // on the operating system. On POSIX boxes, moves to a specified working // directory (if specified), closes all file handles, reopens stdin, stdout, // and stderr to the null device, and sets the process to ignore SIGHUP. On // Windows, does nothing. Returns 0 if OK, -1 if there was an error. CZMQ_EXPORT int zsys_daemonize (const char *workdir);

// Drop the process ID into the lockfile, with exclusive lock, and switch // the process to the specified group and/or user. Any of the arguments // may be null, indicating a no-op. Returns 0 on success, -1 on failure. // Note if you combine this with zsys_daemonize, run after, not before // that method, or the lockfile will hold the wrong process ID. CZMQ_EXPORT int zsys_run_as (const char *lockfile, const char *group, const char *user);

// Returns true if the underlying libzmq supports CURVE security. // Uses a heuristic probe according to the version of libzmq being used. CZMQ_EXPORT bool zsys_has_curve (void);

// Configure the number of I/O threads that ZeroMQ will use. A good // rule of thumb is one thread per gigabit of traffic in or out. The // default is 1, sufficient for most applications. If the environment // variable ZSYS_IO_THREADS is defined, that provides the default. // Note that this method is valid only before any socket is created. CZMQ_EXPORT void zsys_set_io_threads (size_t io_threads);

// Configure the number of sockets that ZeroMQ will allow. The default // is 1024. The actual limit depends on the system, and you can query it // by using zsys_socket_limit (). A value of zero means "maximum". // Note that this method is valid only before any socket is created. CZMQ_EXPORT void zsys_set_max_sockets (size_t max_sockets);

// Return maximum number of ZeroMQ sockets that the system will support. CZMQ_EXPORT size_t zsys_socket_limit (void);

// Configure the default linger timeout in msecs for new zsock instances. // You can also set this separately on each zsock_t instance. The default // linger time is zero, i.e. any pending messages will be dropped. If the // environment variable ZSYS_LINGER is defined, that provides the default. // Note that process exit will typically be delayed by the linger time. CZMQ_EXPORT void zsys_set_linger (size_t linger);

// Configure the default outgoing pipe limit (HWM) for new zsock instances. // You can also set this separately on each zsock_t instance. The default // HWM is 1,000, on all versions of ZeroMQ. If the environment variable // ZSYS_SNDHWM is defined, that provides the default. Note that a value of // zero means no limit, i.e. infinite memory consumption. CZMQ_EXPORT void zsys_set_sndhwm (size_t sndhwm);

// Configure the default incoming pipe limit (HWM) for new zsock instances. // You can also set this separately on each zsock_t instance. The default // HWM is 1,000, on all versions of ZeroMQ. If the environment variable // ZSYS_RCVHWM is defined, that provides the default. Note that a value of // zero means no limit, i.e. infinite memory consumption. CZMQ_EXPORT void zsys_set_rcvhwm (size_t rcvhwm);

// Configure the default HWM for zactor internal pipes; this is set on both // ends of the pipe, for outgoing messages only (sndhwm). The default HWM is // 1,000, on all versions of ZeroMQ. If the environment var ZSYS_ACTORHWM is // defined, that provides the default. Note that a value of zero means no // limit, i.e. infinite memory consumption. CZMQ_EXPORT void zsys_set_pipehwm (size_t pipehwm);

// Return the HWM for zactor internal pipes. CZMQ_EXPORT size_t zsys_pipehwm (void);

// Configure use of IPv6 for new zsock instances. By default sockets accept // and make only IPv4 connections. When you enable IPv6, sockets will accept // and connect to both IPv4 and IPv6 peers. You can override the setting on // each zsock_t instance. The default is IPv4 only (ipv6 set to 0). If the // environment variable ZSYS_IPV6 is defined (as 1 or 0), this provides the // default. Note: has no effect on ZMQ v2. CZMQ_EXPORT void zsys_set_ipv6 (int ipv6);

// Set network interface name to use for broadcasts, particularly zbeacon. // This lets the interface be configured for test environments where required. // For example, on Mac OS X, zbeacon cannot bind to 255.255.255.255 which is // the default when there is no specified interface. If the environment // variable ZSYS_INTERFACE is set, use that as the default interface name. // Setting the interface to "*" means "use all available interfaces". CZMQ_EXPORT void zsys_set_interface (const char *value);

// Return network interface to use for broadcasts, or "" if none was set. CZMQ_EXPORT const char * zsys_interface (void);

// Set log identity, which is a string that prefixes all log messages sent // by this process. The log identity defaults to the environment variable // ZSYS_LOGIDENT, if that is set. CZMQ_EXPORT void zsys_set_logident (const char *value);

// Set stream to receive log traffic. By default, log traffic is sent to // stdout. If you set the stream to NULL, no stream will receive the log // traffic (it may still be sent to the system facility). CZMQ_EXPORT void zsys_set_logstream (FILE *stream);

// Sends log output to a PUB socket bound to the specified endpoint. To // collect such log output, create a SUB socket, subscribe to the traffic // you care about, and connect to the endpoint. Log traffic is sent as a // single string frame, in the same format as when sent to stdout. The // log system supports a single sender; multiple calls to this method will // bind the same sender to multiple endpoints. To disable the sender, call // this method with a null argument. CZMQ_EXPORT void zsys_set_logsender (const char *endpoint);

// Enable or disable logging to the system facility (syslog on POSIX boxes, // event log on Windows). By default this is disabled. CZMQ_EXPORT void zsys_set_logsystem (bool logsystem);

// Log error condition - highest priority CZMQ_EXPORT void zsys_error (const char *format, ...);

// Log warning condition - high priority CZMQ_EXPORT void zsys_warning (const char *format, ...);

// Log normal, but significant, condition - normal priority CZMQ_EXPORT void zsys_notice (const char *format, ...);

// Log informational message - low priority CZMQ_EXPORT void zsys_info (const char *format, ...);

// Log debug-level message - lowest priority CZMQ_EXPORT void zsys_debug (const char *format, ...);

// Self test of this class CZMQ_EXPORT void zsys_test (bool verbose);

// Global signal indicator, TRUE when user presses Ctrl-C or the process // gets a SIGTERM signal. CZMQ_EXPORT extern volatile int zsys_interrupted; // Deprecated name for this variable CZMQ_EXPORT extern volatile int zctx_interrupted;

DESCRIPTION

The zsys class provides a portable wrapper for system calls. We collect them here to reduce the number of weird #ifdefs in other classes. As far as possible, the bulk of CZMQ classes are fully portable.

Please add @discuss section in ../src/zsys.c.

EXAMPLE

From zsys_test method.

zsys_catch_interrupts ();

// Check capabilities without using the return value int rc = zsys_has_curve ();

if (verbose) { char *hostname = zsys_hostname (); zsys_info ("host name is %s", hostname); free (hostname); zsys_info ("system limit is %zu ZeroMQ sockets", zsys_socket_limit ()); } zsys_set_io_threads (1); zsys_set_max_sockets (0); zsys_set_linger (0); zsys_set_sndhwm (1000); zsys_set_rcvhwm (1000); zsys_set_pipehwm (2500); assert (zsys_pipehwm () == 2500); zsys_set_ipv6 (0);

// Test pipe creation zsock_t *pipe_back; zsock_t *pipe_front = zsys_create_pipe (&pipe_back); zstr_send (pipe_front, "Hello"); char *string = zstr_recv (pipe_back); assert (streq (string, "Hello")); free (string); zsock_destroy (&pipe_back); zsock_destroy (&pipe_front);

// Test file manipulation rc = zsys_file_delete ("nosuchfile"); assert (rc == -1);

bool rc_bool = zsys_file_exists ("nosuchfile"); assert (rc_bool != true);

rc = (int) zsys_file_size ("nosuchfile"); assert (rc == -1);

time_t when = zsys_file_modified ("."); assert (when > 0);

int mode = zsys_file_mode ("."); assert (S_ISDIR (mode)); assert (mode & S_IRUSR); assert (mode & S_IWUSR);

zsys_file_mode_private (); rc = zsys_dir_create ("%s/%s", ".", ".testsys/subdir"); assert (rc == 0); when = zsys_file_modified ("./.testsys/subdir"); assert (when > 0); assert (!zsys_file_stable ("./.testsys/subdir")); rc = zsys_dir_delete ("%s/%s", ".", ".testsys/subdir"); assert (rc == 0); rc = zsys_dir_delete ("%s/%s", ".", ".testsys"); assert (rc == 0); zsys_file_mode_default (); assert (zsys_dir_change (".") == 0);

int major, minor, patch; zsys_version (&major, &minor, &patch); assert (major == CZMQ_VERSION_MAJOR); assert (minor == CZMQ_VERSION_MINOR); assert (patch == CZMQ_VERSION_PATCH);

string = zsys_sprintf ("%s %02x", "Hello", 16); assert (streq (string, "Hello 10")); free (string);

char *str64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz1234567890,."; int num10 = 1234567890; string = zsys_sprintf ("%s%s%s%s%d", str64, str64, str64, str64, num10); assert (strlen (string) == (4 * 64 + 10)); free (string);

// Test logging system zsys_set_logident ("czmq_selftest"); zsys_set_logsender ("inproc://logging"); void *logger = zsys_socket (ZMQ_SUB, NULL, 0); assert (logger); rc = zmq_connect (logger, "inproc://logging"); assert (rc == 0); rc = zmq_setsockopt (logger, ZMQ_SUBSCRIBE, "", 0); assert (rc == 0);

if (verbose) { zsys_error ("This is an %s message", "error"); zsys_warning ("This is a %s message", "warning"); zsys_notice ("This is a %s message", "notice"); zsys_info ("This is a %s message", "info"); zsys_debug ("This is a %s message", "debug"); zsys_set_logident ("hello, world"); zsys_info ("This is a %s message", "info"); zsys_debug ("This is a %s message", "debug");

// Check that logsender functionality is working char *received = zstr_recv (logger); assert (received); zstr_free (&received); } zsys_close (logger, NULL, 0);

AUTHORS

The czmq manual was written by the authors in the AUTHORS file.

RESOURCES

Main web site: \m[blue] \m[]

Report bugs to the email <\m[blue]zeromq-dev@lists.zeromq.org\m[][1]>

COPYRIGHT

Copyright (c) 1991-2012 iMatix Corporation -- http://www.imatix.com Copyright other contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution.

NOTES

1. zeromq-dev@lists.zeromq.org  mailto:zeromq-dev@lists.zeromq.org
Search for    or go to Top of page |  Section 3 |  Main Index


CZMQ 3&.0&.1 ZSYS (3) 06/01/2015

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.