From 14bb9d54528c66f7842391ca691f59f77d4938f8 Mon Sep 17 00:00:00 2001 From: Alexander Vdolainen Date: Mon, 28 Mar 2016 02:06:49 +0300 Subject: [PATCH] [manpages] Added sxstream_open, sxstream_openwch, sxstream_close; --- man/Makefile.am | 3 +- man/sxstream_close.3 | 1 + man/sxstream_open.3 | 129 +++++++++++++++++++++++++++++++++++++++++ man/sxstream_openwch.3 | 1 + 4 files changed, 133 insertions(+), 1 deletion(-) create mode 120000 man/sxstream_close.3 create mode 100644 man/sxstream_open.3 create mode 120000 man/sxstream_openwch.3 diff --git a/man/Makefile.am b/man/Makefile.am index e3d63d1..97bdb4d 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -4,4 +4,5 @@ man_MANS = sxmsg_rreply.3 sxhub_create.3 sxhub_init.3 sxhub_destroy.3 sxhub_free sxhub_set_authcheck.3 sxhub_set_rpcvalidator.3 sxhub_set_channelcall.3 \ sxlink_master_accept.3 sxlink_connect.3 sxlink_close.3 sxchannel_open.3 \ sxchannel_close.3 sxmsg_send.3 sxmsg_send_pp.3 sxmsg_clean.3 sxmp_finalize.3 sxmsg_pulse.3 \ - sxmsg_reply.3 sxmsg_reply_pp.3 sxmsg_return.3 sxmsg_return_pp.3 sxlink_connect_at.3 + sxmsg_reply.3 sxmsg_reply_pp.3 sxmsg_return.3 sxmsg_return_pp.3 sxlink_connect_at.3 \ + sxstream_open.3 sxstream_openwch.3 sxstream_close.3 diff --git a/man/sxstream_close.3 b/man/sxstream_close.3 new file mode 120000 index 0000000..1ef5acf --- /dev/null +++ b/man/sxstream_close.3 @@ -0,0 +1 @@ +sxstream_open.3 \ No newline at end of file diff --git a/man/sxstream_open.3 b/man/sxstream_open.3 new file mode 100644 index 0000000..c1bb932 --- /dev/null +++ b/man/sxstream_open.3 @@ -0,0 +1,129 @@ +.TH SXSTREAM_OPEN 3 "28 March 2016" "SXMP" "SXMP Library Manual" +.SH NAME +sxstream_open \- Open a stream on the pointed sxlink. +.br +sxstream_openwch \- Open a stream on the pointed sxlink using already opened channel. +.br +sxstream_close \- Close stream and free all associated buffers. +.SH SYNOPSIS +.B #include +.sp +sxstream_t *sxstream_open(sxlink_t *link, const char *opt, int stid, + int flags); + +sxstream_t *sxstream_openwch(sxlink_t *link, sxchnl_t *channel, + const char *opt, int stid, + int flags); + +int sxstream_close(sxstream_t *stream); + +.br +.sp +.SH DESCRIPTION +.B sxstream_open +will open a stream on the pointed by +.B link +sxlink with optional parameter +.B opt. +Stream with +.B stid +type will be opened with applied +.B flags. +.br +Flags is ored the following ones: +.br +.B SXE_O_BINARY +- Opening stream desired to be binary (not to use with +.B SXE_O_NAMED +) +.br +.B SXE_O_READ +- Opening stream has read access +.br +.B SXE_O_WRITE +- Opening stream has write access +.br +.B SXE_O_ASYNC +- Currently not implemented +.br +.B SXE_O_TRUNC +- Stream will be truncated to zero (might be used with SXE_O_WRITE only) +.br +.B SXE_O_NAMED +- Opening stream desired to be a named list data (not to use with SXE_O_BINARY) +.br +.B sxstream_openwch +will do the same, but will use already opened channel pointed by +.B channel. +.br +.B sxstream_close +will close a +.B stream +and destroy all buffers dedicated for the stream. +.br +Please note: stream functions are not thread safe you need to care about using it in multithreaded +applications. +.br +.SH RETURN VALUE +Upon successful completion, the functions +.B sxstream_open +and +.B sxstream_openwch +will return a valid pointer to the newly created stream. Otherwise NULL will be returned and +.B errno will be set with appropriate error. +.B sxstream_close +will return +.B SXE_SUCCESS +on successful case, otherwise it will return an error described below. +.SH ERRORS +.B SXE_FAILED +will be returned in case of bad params given. +.br +.B SXE_ENOMEM +will be returned if there are no memory available. +.br +.B SXE_BADPROTO +will be returned if other side has an invalid protocol. +.B SXE_EPERM +will be returned if permission was denied. +.br +.B SXE_NOSUCHSTREAMTYPE +will be returned in case if no such stream exist on the requested side. +.br +.B SXE_LINKERROR +or +.B SXE_LINKBROKEN +will be returned if connection link is broken i.e. SSL read or write was failed due to the broken TCP connection. +.br +.SH BUGS +Not known yet. +.SH EXAMPLE +None. +.SH APPLICATION USAGE +This type of data transfer is very useful when you need to get a lot of typed data i.e. lists of lists, +or if you need to get a blob data. +.SH RATIONALE +Writing to the stream isn't a fast operation, since base 64 used to transfer a data from client +to master (master send a raw data instead of base 64 encoded). But it will be changed in the +future versions. +.br +Better to know: fastest stream is not named list of the lists stream, it's also has a cache i.e. +each read operation doesn't means a real message initiation. +.SH SEE ALSO +.BI sxlink_connect(3) +, +.BI sxchannel_open(3) +, +.BI sxchannel_close(3) +, +.BI sxstream_read(3) +, +.BI sxstream_readnamed(3) +, +.BI sxstream_bread(3) +.SH COPYRIGHT +This software licensed under GNU LGPL v3. See COPYING for further details. +.br +(c) Askele Group 2013-2015 , (c) libsxmp dev team 2016 +.SH AUTHOR +Alexander Vdolainen (avdolainen@zoho.com) diff --git a/man/sxstream_openwch.3 b/man/sxstream_openwch.3 new file mode 120000 index 0000000..1ef5acf --- /dev/null +++ b/man/sxstream_openwch.3 @@ -0,0 +1 @@ +sxstream_open.3 \ No newline at end of file