PageRenderTime 13ms CodeModel.GetById 2ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/doc/zmq_getsockopt.txt

https://github.com/unixcrh/libzmq
Plain Text | 531 lines | 412 code | 119 blank | 0 comment | 0 complexity | 0edcc0def2fb34a2e915e6e0de2808a7 MD5 | raw file
  1zmq_getsockopt(3)
  2=================
  3
  4
  5NAME
  6----
  7
  8zmq_getsockopt - get 0MQ socket options
  9
 10
 11SYNOPSIS
 12--------
 13*int zmq_getsockopt (void '*socket', int 'option_name', void '*option_value', size_t '*option_len');*
 14
 15
 16DESCRIPTION
 17-----------
 18The _zmq_getsockopt()_ function shall retrieve the value for the option
 19specified by the 'option_name' argument for the 0MQ socket pointed to by the
 20'socket' argument, and store it in the buffer pointed to by the 'option_value'
 21argument. The 'option_len' argument is the size in bytes of the buffer pointed
 22to by 'option_value'; upon successful completion _zmq_getsockopt()_ shall
 23modify the 'option_len' argument to indicate the actual size of the option
 24value stored in the buffer.
 25
 26The following options can be retrieved with the _zmq_getsockopt()_ function:
 27
 28
 29ZMQ_TYPE: Retrieve socket type
 30~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 31The 'ZMQ_TYPE' option shall retrieve the socket type for the specified
 32'socket'.  The socket type is specified at socket creation time and
 33cannot be modified afterwards.
 34
 35[horizontal]
 36Option value type:: int
 37Option value unit:: N/A
 38Default value:: N/A
 39Applicable socket types:: all
 40
 41
 42ZMQ_RCVMORE: More message data parts to follow
 43~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 44The 'ZMQ_RCVMORE' option shall return True (1) if the message part last
 45received from the 'socket' was a data part with more parts to follow. If there
 46are no data parts to follow, this option shall return False (0).
 47
 48Refer to linkzmq:zmq_send[3] and linkzmq:zmq_recv[3] for a detailed description
 49of multi-part messages.
 50
 51[horizontal]
 52Option value type:: int
 53Option value unit:: boolean
 54Default value:: N/A
 55Applicable socket types:: all
 56
 57
 58ZMQ_SNDHWM: Retrieves high water mark for outbound messages
 59~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 60The 'ZMQ_SNDHWM' option shall return the high water mark for outbound messages
 61on the specified 'socket'. The high water mark is a hard limit on the maximum
 62number of outstanding messages 0MQ shall queue in memory for any single peer
 63that the specified 'socket' is communicating with. A value of zero means no
 64limit.
 65
 66If this limit has been reached the socket shall enter an exceptional state and
 67depending on the socket type, 0MQ shall take appropriate action such as
 68blocking or dropping sent messages. Refer to the individual socket descriptions
 69in linkzmq:zmq_socket[3] for details on the exact action taken for each socket
 70type.
 71
 72[horizontal]
 73Option value type:: int
 74Option value unit:: messages
 75Default value:: 1000
 76Applicable socket types:: all
 77
 78
 79ZMQ_RCVHWM: Retrieve high water mark for inbound messages
 80~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 81The 'ZMQ_RCVHWM' option shall return the high water mark for inbound messages on
 82the specified 'socket'. The high water mark is a hard limit on the maximum
 83number of outstanding messages 0MQ shall queue in memory for any single peer
 84that the specified 'socket' is communicating with. A value of zero means no
 85limit.
 86
 87If this limit has been reached the socket shall enter an exceptional state and
 88depending on the socket type, 0MQ shall take appropriate action such as
 89blocking or dropping sent messages. Refer to the individual socket descriptions
 90in linkzmq:zmq_socket[3] for details on the exact action taken for each socket
 91type.
 92
 93[horizontal]
 94Option value type:: int
 95Option value unit:: messages
 96Default value:: 1000
 97Applicable socket types:: all
 98
 99
100ZMQ_AFFINITY: Retrieve I/O thread affinity
101~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102The 'ZMQ_AFFINITY' option shall retrieve the I/O thread affinity for newly
103created connections on the specified 'socket'.
104
105Affinity determines which threads from the 0MQ I/O thread pool associated with
106the socket's _context_ shall handle newly created connections.  A value of zero
107specifies no affinity, meaning that work shall be distributed fairly among all
1080MQ I/O threads in the thread pool. For non-zero values, the lowest bit
109corresponds to thread 1, second lowest bit to thread 2 and so on.  For example,
110a value of 3 specifies that subsequent connections on 'socket' shall be handled
111exclusively by I/O threads 1 and 2.
112
113See also linkzmq:zmq_init[3] for details on allocating the number of I/O
114threads for a specific _context_.
115
116[horizontal]
117Option value type:: uint64_t
118Option value unit:: N/A (bitmap)
119Default value:: 0
120Applicable socket types:: N/A
121
122
123ZMQ_IDENTITY: Set socket identity
124~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
125The 'ZMQ_IDENTITY' option shall retrieve the identity of the specified 'socket'.
126Socket identity is used only by request/reply pattern. Namely, it can be used
127in tandem with ROUTER socket to route messages to the peer with specific
128identity.
129
130Identity should be at least one byte and at most 255 bytes long. Identities
131starting with binary zero are reserved for use by 0MQ infrastructure.
132
133[horizontal]
134Option value type:: binary data
135Option value unit:: N/A
136Default value:: NULL
137Applicable socket types:: all
138
139
140ZMQ_RATE: Retrieve multicast data rate
141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142The 'ZMQ_RATE' option shall retrieve the maximum send or receive data rate for
143multicast transports using the specified 'socket'.
144
145[horizontal]
146Option value type:: int
147Option value unit:: kilobits per second
148Default value:: 100
149Applicable socket types:: all, when using multicast transports
150
151
152ZMQ_RECOVERY_IVL: Get multicast recovery interval
153~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
154The 'ZMQ_RECOVERY_IVL' option shall retrieve the recovery interval for
155multicast transports using the specified 'socket'.  The recovery interval
156determines the maximum time in milliseconds that a receiver can be absent from a
157multicast group before unrecoverable data loss will occur.
158
159[horizontal]
160Option value type:: int
161Option value unit:: milliseconds
162Default value:: 10000
163Applicable socket types:: all, when using multicast transports
164
165
166ZMQ_SNDBUF: Retrieve kernel transmit buffer size
167~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
168The 'ZMQ_SNDBUF' option shall retrieve the underlying kernel transmit buffer
169size for the specified 'socket'. A value of zero means that the OS default is
170in effect. For details refer to your operating system documentation for the
171'SO_SNDBUF' socket option.
172
173[horizontal]
174Option value type:: int
175Option value unit:: bytes
176Default value:: 0
177Applicable socket types:: all
178
179
180ZMQ_RCVBUF: Retrieve kernel receive buffer size
181~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182The 'ZMQ_RCVBUF' option shall retrieve the underlying kernel receive buffer
183size for the specified 'socket'. A value of zero means that the OS default is
184in effect. For details refer to your operating system documentation for the
185'SO_RCVBUF' socket option.
186
187[horizontal]
188Option value type:: int
189Option value unit:: bytes
190Default value:: 0
191Applicable socket types:: all
192
193
194ZMQ_LINGER: Retrieve linger period for socket shutdown
195~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
196The 'ZMQ_LINGER' option shall retrieve the linger period for the specified
197'socket'.  The linger period determines how long pending messages which have
198yet to be sent to a peer shall linger in memory after a socket is closed with
199linkzmq:zmq_close[3], and further affects the termination of the socket's
200context with linkzmq:zmq_term[3]. The following outlines the different
201behaviours:
202
203* The default value of '-1' specifies an infinite linger period. Pending
204  messages shall not be discarded after a call to _zmq_close()_; attempting to
205  terminate the socket's context with _zmq_term()_ shall block until all
206  pending messages have been sent to a peer.
207
208* The value of '0' specifies no linger period. Pending messages shall be
209  discarded immediately when the socket is closed with _zmq_close()_.
210
211* Positive values specify an upper bound for the linger period in milliseconds.
212  Pending messages shall not be discarded after a call to _zmq_close()_;
213  attempting to terminate the socket's context with _zmq_term()_ shall block
214  until either all pending messages have been sent to a peer, or the linger
215  period expires, after which any pending messages shall be discarded.
216
217[horizontal]
218Option value type:: int
219Option value unit:: milliseconds
220Default value:: -1 (infinite)
221Applicable socket types:: all
222
223
224ZMQ_RECONNECT_IVL: Retrieve reconnection interval
225~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226The 'ZMQ_RECONNECT_IVL' option shall retrieve the initial reconnection interval
227for the specified 'socket'.  The reconnection interval is the period 0MQ shall
228wait between attempts to reconnect disconnected peers when using
229connection-oriented transports. The value -1 means no reconnection.
230
231NOTE: The reconnection interval may be randomized by 0MQ to prevent
232reconnection storms in topologies with a large number of peers per socket.
233
234[horizontal]
235Option value type:: int
236Option value unit:: milliseconds
237Default value:: 100
238Applicable socket types:: all, only for connection-oriented transports
239
240
241ZMQ_RECONNECT_IVL_MAX: Retrieve maximum reconnection interval
242~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
243The 'ZMQ_RECONNECT_IVL_MAX' option shall retrieve the maximum reconnection 
244interval for the specified 'socket'.  This is the maximum period 0MQ shall wait 
245between attempts to reconnect. On each reconnect attempt, the previous interval 
246shall be doubled untill ZMQ_RECONNECT_IVL_MAX is reached. This allows for 
247exponential backoff strategy. Default value means no exponential backoff is 
248performed and reconnect interval calculations are only based on
249ZMQ_RECONNECT_IVL.
250
251NOTE:  Values less than ZMQ_RECONNECT_IVL will be ignored.
252
253[horizontal]
254Option value type:: int
255Option value unit:: milliseconds
256Default value:: 0 (only use ZMQ_RECONNECT_IVL)
257Applicable socket types:: all, only for connection-oriented transport
258
259
260ZMQ_BACKLOG: Retrieve maximum length of the queue of outstanding connections
261~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
262The 'ZMQ_BACKLOG' option shall retrieve the maximum length of the queue of
263outstanding peer connections for the specified 'socket'; this only applies to
264connection-oriented transports. For details refer to your operating system
265documentation for the 'listen' function.
266
267[horizontal]
268Option value type:: int
269Option value unit:: connections
270Default value:: 100
271Applicable socket types:: all, only for connection-oriented transports
272
273
274ZMQ_MAXMSGSIZE: Maximum acceptable inbound message size
275~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
276The option shall retrieve limit for the inbound messages. If a peer sends
277a message larger than ZMQ_MAXMSGSIZE it is disconnected. Value of -1 means
278'no limit'.
279
280[horizontal]
281Option value type:: int64_t
282Option value unit:: bytes
283Default value:: -1
284Applicable socket types:: all
285
286
287ZMQ_MULTICAST_HOPS: Maximum network hops for multicast packets
288~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
289The option shall retrieve time-to-live used for outbound multicast packets.
290The default of 1 means that the multicast packets don't leave the local network.
291
292[horizontal]
293Option value type:: int
294Option value unit:: network hops
295Default value:: 1
296Applicable socket types:: all, when using multicast transports
297
298
299ZMQ_RCVTIMEO: Maximum time before a socket operation returns with EAGAIN
300~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
301Retrieve the timeout for recv operation on the socket.  If the value is `0`,
302_zmq_recv(3)_ will return immediately, with a EAGAIN error if there is no
303message to receive. If the value is `-1`, it will block until a message is
304available. For all other values, it will wait for a message for that amount
305of time before returning with an EAGAIN error.
306
307[horizontal]
308Option value type:: int
309Option value unit:: milliseconds
310Default value:: -1 (infinite)
311Applicable socket types:: all
312
313
314ZMQ_SNDTIMEO: Maximum time before a socket operation returns with EAGAIN
315~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
316Retrieve the timeout for send operation on the socket. If the value is `0`,
317_zmq_send(3)_ will return immediately, with a EAGAIN error if the message
318cannot be sent. If the value is `-1`, it will block until the message is sent.
319For all other values, it will try to send the message for that amount of time
320before returning with an EAGAIN error.
321
322[horizontal]
323Option value type:: int
324Option value unit:: milliseconds
325Default value:: -1 (infinite)
326Applicable socket types:: all
327
328
329ZMQ_IPV6: Retrieve IPv6 socket status
330~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
331Retrieve the IPv6 option for the socket. A value of `1` means IPv6 is
332enabled on the socket, while `0` means the socket will use only IPv4.
333When IPv6 is enabled the socket will connect to, or accept connections
334from, both IPv4 and IPv6 hosts.
335
336[horizontal]
337Option value type:: int
338Option value unit:: boolean
339Default value:: 0 (false)
340Applicable socket types:: all, when using TCP transports.
341
342
343ZMQ_IPV4ONLY: Retrieve IPv4-only socket override status
344~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345Retrieve the IPv4-only option for the socket. This option is deprecated.
346Please use the ZMQ_IPV6 option.
347
348[horizontal]
349Option value type:: int
350Option value unit:: boolean
351Default value:: 1 (true)
352Applicable socket types:: all, when using TCP transports.
353
354
355ZMQ_DELAY_ATTACH_ON_CONNECT: Retrieve attach-on-connect value
356~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
357Retrieve the state of the attach on connect value. If set to `1`, will delay the
358attachment of a pipe on connect until the underlying connection has completed.
359This will cause the socket to block if there are no other connections, but will
360prevent queues from filling on pipes awaiting connection.
361
362[horizontal]
363Option value type:: int
364Option value unit:: boolean
365Default value:: 0 (false)
366Applicable socket types:: all, primarily when using TCP/IPC transports.
367
368
369ZMQ_FD: Retrieve file descriptor associated with the socket
370~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
371The 'ZMQ_FD' option shall retrieve the file descriptor associated with the
372specified 'socket'. The returned file descriptor can be used to integrate the
373socket into an existing event loop; the 0MQ library shall signal any pending
374events on the socket in an _edge-triggered_ fashion by making the file
375descriptor become ready for reading.
376
377NOTE: The ability to read from the returned file descriptor does not
378necessarily indicate that messages are available to be read from, or can be
379written to, the underlying socket; applications must retrieve the actual event
380state with a subsequent retrieval of the 'ZMQ_EVENTS' option.
381
382NOTE: The returned file descriptor is also used internally by the 'zmq_send' 
383and 'zmq_recv' functions. As the descriptor is edge triggered, applications 
384must update the state of 'ZMQ_EVENTS' after each invocation of 'zmq_send' 
385or 'zmq_recv'.To be more explicit: after calling 'zmq_send' the socket may 
386become readable (and vice versa) without triggering a read event on the 
387file descriptor.
388
389CAUTION: The returned file descriptor is intended for use with a 'poll' or
390similar system call only. Applications must never attempt to read or write data
391to it directly, neither should they try to close it.
392
393[horizontal]
394Option value type:: int on POSIX systems, SOCKET on Windows
395Option value unit:: N/A
396Default value:: N/A
397Applicable socket types:: all
398
399
400ZMQ_EVENTS: Retrieve socket event state
401~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
402The 'ZMQ_EVENTS' option shall retrieve the event state for the specified
403'socket'.  The returned value is a bit mask constructed by OR'ing a combination
404of the following event flags:
405
406*ZMQ_POLLIN*::
407Indicates that at least one message may be received from the specified socket
408without blocking.
409
410*ZMQ_POLLOUT*::
411Indicates that at least one message may be sent to the specified socket without
412blocking.
413
414The combination of a file descriptor returned by the 'ZMQ_FD' option being
415ready for reading but no actual events returned by a subsequent retrieval of
416the 'ZMQ_EVENTS' option is valid; applications should simply ignore this case
417and restart their polling operation/event loop.
418
419[horizontal]
420Option value type:: int
421Option value unit:: N/A (flags)
422Default value:: N/A
423Applicable socket types:: all
424
425
426ZMQ_LAST_ENDPOINT: Retrieve the last endpoint set
427~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
428The 'ZMQ_LAST_ENDPOINT' option shall retrieve the last endpoint bound for 
429TCP and IPC transports. The returned value will be a string in the form of
430a ZMQ DSN. Note that if the TCP host is INADDR_ANY, indicated by a *, then
431the returned address will be 0.0.0.0 (for IPv4).
432
433[horizontal]
434Option value type:: character string
435Option value unit:: N/A
436Default value:: NULL
437Applicable socket types:: all, when binding TCP or IPC transports
438
439
440ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option
441~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
442Override 'SO_KEEPALIVE' socket option(where supported by OS).
443The default value of `-1` means to skip any overrides and leave it to OS default.
444
445[horizontal]
446Option value type:: int
447Option value unit:: -1,0,1
448Default value:: -1 (leave to OS default)
449Applicable socket types:: all, when using TCP transports.
450
451
452ZMQ_TCP_KEEPALIVE_IDLE: Override TCP_KEEPCNT(or TCP_KEEPALIVE on some OS)
453~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
454Override 'TCP_KEEPCNT'(or 'TCP_KEEPALIVE' on some OS) socket option(where supported by OS).
455The default value of `-1` means to skip any overrides and leave it to OS default.
456
457[horizontal]
458Option value type:: int
459Option value unit:: -1,>0
460Default value:: -1 (leave to OS default)
461Applicable socket types:: all, when using TCP transports.
462
463
464ZMQ_TCP_KEEPALIVE_CNT: Override TCP_KEEPCNT socket option
465~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
466Override 'TCP_KEEPCNT' socket option(where supported by OS).
467The default value of `-1` means to skip any overrides and leave it to OS default.
468
469[horizontal]
470Option value type:: int
471Option value unit:: -1,>0
472Default value:: -1 (leave to OS default)
473Applicable socket types:: all, when using TCP transports.
474
475
476ZMQ_TCP_KEEPALIVE_INTVL: Override TCP_KEEPINTVL socket option
477~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
478Override 'TCP_KEEPINTVL' socket option(where supported by OS).
479The default value of `-1` means to skip any overrides and leave it to OS default.
480
481[horizontal]
482Option value type:: int
483Option value unit:: -1,>0
484Default value:: -1 (leave to OS default)
485Applicable socket types:: all, when using TCP transports.
486
487
488RETURN VALUE
489------------
490The _zmq_getsockopt()_ function shall return zero if successful. Otherwise it
491shall return `-1` and set 'errno' to one of the values defined below.
492
493
494ERRORS
495------
496*EINVAL*::
497The requested option _option_name_ is unknown, or the requested _option_len_ or
498_option_value_ is invalid, or the size of the buffer pointed to by
499_option_value_, as specified by _option_len_, is insufficient for storing the
500option value.
501*ETERM*::
502The 0MQ 'context' associated with the specified 'socket' was terminated.
503*ENOTSOCK*::
504The provided 'socket' was invalid.
505*EINTR*::
506The operation was interrupted by delivery of a signal.
507
508
509EXAMPLE
510-------
511.Retrieving the high water mark for outgoing messages
512----
513/* Retrieve high water mark into sndhwm */
514int sndhwm;
515size_t sndhwm_size = sizeof (sndhwm);
516rc = zmq_getsockopt (socket, ZMQ_SNDHWM, &sndhwm, &sndhwm_size);
517assert (rc == 0);
518----
519
520
521SEE ALSO
522--------
523linkzmq:zmq_setsockopt[3]
524linkzmq:zmq_socket[3]
525linkzmq:zmq[7]
526
527
528AUTHORS
529-------
530This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
531Martin Lucina <mato@kotelna.sk>.