1/*
2 * libwebsockets - small server side websockets and web server implementation
3 *
4 * Copyright (C) 2010 - 2019 Andy Green <andy@warmcat.com>
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to
8 * deal in the Software without restriction, including without limitation the
9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10 * sell copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22 * IN THE SOFTWARE.
23 */
24
25/*! \defgroup cgi cgi handling
26 *
27 * ##CGI handling
28 *
29 * These functions allow low-level control over stdin/out/err of the cgi.
30 *
31 * However for most cases, binding the cgi to http in and out, the default
32 * lws implementation already does the right thing.
33 */
34
35enum lws_enum_stdinouterr {
36 LWS_STDIN = 0,
37 LWS_STDOUT = 1,
38 LWS_STDERR = 2,
39};
40
41enum lws_cgi_hdr_state {
42 LCHS_HEADER,
43 LCHS_CR1,
44 LCHS_LF1,
45 LCHS_CR2,
46 LCHS_LF2,
47 LHCS_RESPONSE,
48 LHCS_DUMP_HEADERS,
49 LHCS_PAYLOAD,
50 LCHS_SINGLE_0A,
51};
52
53struct lws_cgi_args {
54 struct lws **stdwsi; /**< get fd with lws_get_socket_fd() */
55 enum lws_enum_stdinouterr ch; /**< channel index */
56 unsigned char *data; /**< for messages with payload */
57 enum lws_cgi_hdr_state hdr_state; /**< track where we are in cgi headers */
58 int len; /**< length */
59};
60
61/** struct lws_cgi_info - parameters to spawn network-connected cgi
62 * process when using lws_cgi_via_info() */
63struct lws_cgi_info {
64 struct lws *wsi;
65 /**< connection to own the process */
66 const char * const *exec_array;
67 /**< array of "exec-name" "arg1" ... "argn" NULL */
68 int script_uri_path_len;
69 /**< how many chars on the left of the uri are the path to the
70 * cgi, or -1 to spawn without URL-related env vars */
71 int timeout_secs;
72 /**< seconds script should be allowed to run */
73 const struct lws_protocol_vhost_options *mp_cgienv;
74 /**< pvo list with per-vhost cgi options to put in env */
75 const char *chroot_path;
76 /**< NULL, or chroot patch for child process */
77 const char *wd;
78 /**< working directory to cd to after fork, NULL defaults to /tmp */
79};
80
81#ifdef LWS_WITH_CGI
82/**
83 * lws_cgi_via_info() - Spawn network-connected cgi process
84 * \param cgiinfo: pointer to lws_cgi_info struct
85 */
86LWS_VISIBLE LWS_EXTERN int lws_cgi_via_info(struct lws_cgi_info * cgiinfo);
87
88/**
89 * lws_cgi: spawn network-connected cgi process
90 *
91 * \param wsi: connection to own the process
92 * \param exec_array: array of "exec-name" "arg1" ... "argn" NULL
93 * \param script_uri_path_len: how many chars on the left of the uri are the
94 * path to the cgi, or -1 to spawn without URL-related env vars
95 * \param timeout_secs: seconds script should be allowed to run
96 * \param mp_cgienv: pvo list with per-vhost cgi options to put in env
97 */
98LWS_VISIBLE LWS_EXTERN int
99lws_cgi(struct lws *wsi, const char * const *exec_array,
100 int script_uri_path_len, int timeout_secs,
101 const struct lws_protocol_vhost_options *mp_cgienv);
102
103/**
104 * lws_cgi_write_split_stdout_headers: write cgi output accounting for header part
105 *
106 * \param wsi: connection to own the process
107 */
108LWS_VISIBLE LWS_EXTERN int
109lws_cgi_write_split_stdout_headers(struct lws *wsi);
110
111/**
112 * lws_cgi_kill: terminate cgi process associated with wsi
113 *
114 * \param wsi: connection to own the process
115 */
116LWS_VISIBLE LWS_EXTERN int
117lws_cgi_kill(struct lws *wsi);
118
119/**
120 * lws_cgi_get_stdwsi: get wsi for stdin, stdout, or stderr
121 *
122 * \param wsi: parent wsi that has cgi
123 * \param ch: which of LWS_STDIN, LWS_STDOUT or LWS_STDERR
124 */
125LWS_VISIBLE LWS_EXTERN struct lws *
126lws_cgi_get_stdwsi(struct lws *wsi, enum lws_enum_stdinouterr ch);
127
128#endif
129///@}
130
131