10.0.0.21 Git - tlspool/blob - doc/man/tlspool_socket.man

   1 .TH TLSPOOL_SOCKET 3 "November 2015" "ARPA2.net" "Library Calls"
   2 .SH NAME
   3 tlspool_socket \- Setup the TLS Pool to use with a given socket path.
   4 .SH SYNOPSIS
   5 .B #include <tlspool/commands.h>
   6 .br
   7 .B #include <tlspool/starttls.h>
   8 .sp
   9 .B int tlspool_socket (char *\fIpath\fB);
  10 .SH DESCRIPTION
  11 .PP
  12 .BR tlspool_socket ()
  13 returns a file descriptor for the TLS Pool.  During the first call, the
  14 .I path
  15 argument is used as a path to the UNIX domain socket to use; during later
  16 calls, the argument is ignored but the returned file descriptor is instead
  17 the same one as before.  A NULL value for the argument is replaced with
  18 the value of the
  19 .BR socket_name configuration
  20 file as returned by
  21 .IR tlspool_configvar()
  22 or, if that fails, the statically compiled value in
  23 .BR TLSPOOL_DEFAULT_SOCKET_PATH .
  24 .PP
  25 All of the
  26 .IR tlspool_XXX ()
  27 functions that do not have a socket path argument
  28 call this function internally, to setup a shared access point
  29 to the TLS Pool.  In addition, a "master thread" is created to retrieve
  30 and redistribute return values.  This mechanism facilitates multiple
  31 simultaneous commands being sent to the TLS Pool by independent threads.
  32 .SH "RETURN VALUE"
  33 The function returns a file descriptor >= 0 on success.
  34 If an error occurs, the function returns -1 and
  35 .I errno
  36 is set appropriately.
  37 .\"TODO: .SH ERRORS
  38 .\"TODO: Various.
  39 .SH AUTHOR
  40 .PP
  41 Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project.
  42 .SH "REPORTING BUGS"
  43 .PP
  44 For any discussion, including about bugs, please use the mailing list
  45 found on
  46 .IR http://lists.arpa2.org/mailman/listinfo/tls-pool .
  47 .PP
  48 Please read the software distribution's
  49 .IR README ", " INSTALL " and " TODO " files"
  50 for information about the
  51 .I tlspool
  52 implementation status.
  53 .SH COPYRIGHT
  54 .PP
  55 Copyright \(co 2015 Rick van Rein, ARPA2.net.
  56 .PP
  57 ARPA2 is funded from InternetWide.org, which in turns receives donations
  58 from various funding sources with an interest in a private and secure
  59 Internet that gives users control over their online presence.  This particular
  60 project has been sponsored in part by NCSC.
  61 .SH "SEE ALSO"
  62 .IR tlspool "(8)."
  63 .IR tlspool_configvar "(3)"
  64 .PP
  65 The configuration file option
  66 .I socket_name
  67 influences the path at which the TLS Pool is available; this is not
  68 read by the client library, and when it differs from the default path in
  69 .BR TLSPOOL_DEFAULT_SOCKET_PATH ,
  70 this function is used to inform the client library once, before calling
  71 any of the other client functions.
  72 .PP
  73 The TLS Pool API is documented in the include file
  74 .IR <tlspool/commands.h> " and " <tlspool/starttls.h>
  75 for C, and the
  76 .I tlspool.py
  77 module for Python.
  78 .PP
  79 Online resources may be found on the project home page,
  80 .IR http://tlspool.arpa2.net .