Embedthis GoAhead

https://www.embedthis.com/goahead/doc/
Admin
GoAhead is a lightweight, embedded web server with HTTP/1.1, SSL/TLS support, authentication, and...
Tokens:71,674
Snippets:944
Trust Score:7.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example CGI URI

Source: https://www.embedthis.com/goahead/doc/users/cgi.html

This is an example of a URI that would trigger a CGI program execution. The script name follows the '/cgi-bin/' prefix.

```text
https://www.embedthis.com/cgi-bin/cgitest
```

--------------------------------

### websStartEvent

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Start a callback event.

```APIDOC
## websStartEvent

### Description
Start a callback event.

### Signature
`int websStartEvent(int delay, WebsEventProc proc, void *data)`
```

--------------------------------

### Convert Web Files to C Structures

Source: https://www.embedthis.com/goahead/doc/man/webcomp.html

Example demonstrating how to find web files, convert them using webcomp, and compile the resulting C code.

```bash
find web -type f -print >;fileList

           webcomp --files filelist >;romFiles.c

           cc -o romFiles.o romFiles.c


```

--------------------------------

### Embed GoAhead Library with Full Control API

Source: https://www.embedthis.com/goahead/doc/developers/embedding.html

This example demonstrates how to create a web server by linking the GoAhead library with a custom main program. It uses the 'server.conf' configuration file and services events until terminated. Ensure you include "goahead.h" and link against the GoAhead library.

```c
#include "goahead.h"
int main(int argc, char **argv)
{
    if (websOpen("web", "route.txt") < 0) {
        error("Can't open the web server runtime");
        return 0;
    }
    if (websListen(":80") < 0) {
        mprError("Can't listen on port 80");
        return 0;
    }
    websServiceEvents(NULL);
    websClose();
    return 0;
}

```

--------------------------------

### Compile Web Pages into C Code with webcomp

Source: https://www.embedthis.com/goahead/doc/developers/rom.html

Use the webcomp program to compile web documents and configuration files into C data structures. This example finds all .txt and web files, lists them, and then converts them into C structures in rom.c.

```bash
find *.txt web -print >fileList \
webcomp filelist >rom.c
```

--------------------------------

### Example CGI URI

Source: https://www.embedthis.com/goahead/doc/users/cgi.html

This URI demonstrates how to run a Perl interpreter to execute a CGI script. It shows typical query parameters.

```http
http://hostname/cgi-bin/myScript/products/pricelists.pl?id=23&payment=creditCard
```

--------------------------------

### Minimal Login Form Example

Source: https://www.embedthis.com/goahead/doc/users/authentication.html

A basic HTML form for user login, submitting username and password via POST to the /auth/login action.

```html
<html><head><title>login.html</title></head>
<body>
    <p>Please log in</p>
    <form name="details" method="post" **action="/auth/login"**>
        Username <input type="text" **name="username"** value=''><br/>
        Password <input type="password" **name="password"** value=''><br/>
        <input type="submit" name="submit" value="OK">
    </form>
</body>
</html>
```

--------------------------------

### WebsGetHost

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request host.

```APIDOC
## websGetHost

### Description
Get the request host.

### Signature
cchar * websGetHost(Webs *wp)
```

--------------------------------

### Basic Authentication Configuration

Source: https://www.embedthis.com/goahead/doc/users/authentication.html

Example configuration for basic authentication, defining roles, users, and restricting access to specific URIs.

```goahead
# In auth.txt
role name=operator abilities=start,stop
user name=julie password=9d8873a123eb506e7f8e84d1f2a26916 roles=operator
# In route.txt
route uri=/machinery auth=basic abilities=start,stop
```

--------------------------------

### bufCompact

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Compacts the data in the buffer by moving it to the start of the buffer.

```APIDOC
## bufCompact

### Description
Compact the data in the buffer and move to the start of the buffer.

### Parameters
- **bp** (WebsBuf *) - Buffer reference.
```

--------------------------------

### WebsGetServer

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the server host name.

```APIDOC
## websGetServer

### Description
Get the server host name.

### Signature
cchar * websGetServer(void)
```

--------------------------------

### WebsGetBackground

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the background execution flag.

```APIDOC
## websGetBackground

### Description
Get the background execution flag.

### Signature
int websGetBackground(void)
```

--------------------------------

### CGI HTML Output

Source: https://www.embedthis.com/goahead/doc/users/cgi.html

This example shows how a CGI program can return HTML content back to the client's browser. It includes standard HTML structure and a custom header.

```html
Content-type: text/html
<HTML><HEAD><TITLE>Sample CGI Output</TITLE></HEAD>
<BODY>
<H1>Hello World</H1>
</BODY></HTML>
```

--------------------------------

### WebsGetExt

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request URI extension.

```APIDOC
## websGetExt

### Description
Get the request URI extension.

### Signature
cchar * websGetExt(Webs *wp)
```

--------------------------------

### bufAdjustStart

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Adjusts the start (servp) reference of the buffer by a specified count.

```APIDOC
## bufAdjustStart

### Description
Adjust the start (servp) reference.

### Parameters
- **bp** (WebsBuf *) - Buffer reference.
- **count** (ssize) - Number of bytes to adjust.
```

--------------------------------

### WebsGetDir

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the base file directory for a request.

```APIDOC
## websGetDir

### Description
Get the base file directory for a request.

### Signature
cchar * websGetDir(Webs *wp)
```

--------------------------------

### Configure Action Handler Route

Source: https://www.embedthis.com/goahead/doc/users/handlers.html

Use this route directive to configure the action handler for URLs starting with /action. See GoActions for more details.

```nginx
route uri=/action handler=action
```

--------------------------------

### Define Valid File Extensions for a Route

Source: https://www.embedthis.com/goahead/doc/users/routing.html

Specify a set of valid file extensions for documents handled by a particular route. This example uses the CGI handler for specific extensions.

```route
route uri=/ **extension=cgi|fcgi|mycgi** handler=cgi
```

--------------------------------

### Example PEM-Encoded Certificate

Source: https://www.embedthis.com/goahead/doc/users/sslOverview.html

This is an example of a certificate encoded in Privacy-Enhanced Mail (PEM) format, commonly used for SSL/TLS.

```text
-----BEGIN CERTIFICATE-----
MIIC7jCCAlegAwIBAgIBATANBgkqhkiG9w0BAQQFADCBqTELMAkGA1UEBhMCWFkx
FTATBgNVBAgTDFNuYWtlIERlc2VydDETMBEGA1PEBxMKU25ha2UgVG93bjEXMBUG
A1UEChMOU25ha2UgT2lsLCBMdGQxHjAcBgNVBAsTFUNlcnRpZmljYXRlIEF1dGhv
cml0eTEVMBMGA1UEAxMMU25ha2UgT2lsIENBMR4wHAYJKoZIhvcNAQkBFg9jYUBz
bmFrZW9pbC5kb20wHhcNOTgxMDIxMDg1ODM2WhcNOTkxMDIxMDg1ODM2WjCBpzEL
MAkGA1UEBhMCWFkxFTATBgNVBAgTDFNuYWtlIELlc2VydDETMBEGA1UEBxMKU25h
a2UgVG93bjEXMBAGA1UEChMOU25ha2UgT2lsLCBMdGQxFzAVBgNVBAsTDldlYnNl
cnZlciBUZWFtMRkwFwYDVQQDExB3d3cuc25ha2VvaWwuZG9tMR8wHQYJKoZIhvcN
AQkBFhB3d3dAc25ha2VvaWwuZG9tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKB
gQDH9Ge/s2zcH+da+rPTx/DPRp3xGjHZ4GG6pCmvADIEtBtKBFAcZ64n+Dy7Np8b
vKR+yy5DGQiijsH1D/j8HlGE+q4TZ8OFk7BNBFazHxFbYI4OKMiCxdKzdif1yfaa
lWoANFlAzlSdbxeEVHoT0K+gT5w3UxwZKv2DLbETzLZyPwIDAQABoyYwJDAPBgNV
HRMECDAGAQH/AgEAMBEGCWCGSAGG+EIBAQQEAwIAQDANBgkqhkiG9w0BAQQFAAOB
gQAZUIHAL4D09oE6Lv2k56Gp38OBDuILvwLg1v1KL8mQR+KFjghCrtpqaztZqcDt
2q2QoyulCgSzHbEGmi0EsdkPfg6mp0penssIFePYNI+/8u9HT4LuKMJX15hxBam7
dUHzICxBVC1lnHyYGjDuAMhe396lYAn8bCld1/L4NMGBCQ==
-----END CERTIFICATE-----
```

--------------------------------

### Specify Redirect for 404 Status

Source: https://www.embedthis.com/goahead/doc/users/routing.html

Use the redirect keyword to specify a target URI for a given HTTP status code. This example redirects 404 errors to a custom upgrade message page.

```goahead
route uri=/old-content/ **redirect=404@/upgrade-message.html**
```

--------------------------------

### websOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Initializes the web server and defines the documents directory.

```APIDOC
## websOpen

### Description
This initializes the web server and defines the documents directory.

### Parameters
- **documents** (cchar *) - Optional web documents directory. If set to null, the build time ME_GOAHEAD_DOCUMENTS value is used for the documents directory.
- **routes** (cchar *) - Optional routes configuration.
```

--------------------------------

### WebsGetRoles

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the roles hash.

```APIDOC
## websGetRoles

### Description
Get the roles hash.

### Signature
WebsHash websGetRoles(void)
```

--------------------------------

### Accessing URL Query Variables in C

Source: https://www.embedthis.com/goahead/doc/users/js.html

Example of a C procedure that retrieves 'name' and 'age' from a URL query string and writes them to the web page. Ensure the URL contains these parameters.

```c
int myAspProcedure(Webs wp, int argc, char **argv) {
    char *name = websGetVar(wp, "name", "undefined");
    char *age = websGetVar(wp, "age", "undefined");
    websWrite(wp, "Name %s, Age %s", name, age);
}
```

--------------------------------

### wopenAlloc

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Initialize the walloc module.

```APIDOC
## wopenAlloc

### Description
Initialize the walloc module.

### Signature
`int wopenAlloc(void *buf, int bufsize, int flags)`
```

--------------------------------

### WebsGetRandomBytes

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets random data.

```APIDOC
## websGetRandomBytes

### Description
Get some random data.

### Signature
int websGetRandomBytes(char *buf, ssize length, bool block)
```

--------------------------------

### webcomp Command Synopsis

Source: https://www.embedthis.com/goahead/doc/man/webcomp.html

Shows the basic syntax for using the webcomp command, including options and file arguments.

```bash
**webcomp** **[options]** **files** **...** **>;output.c**

       [ _--files_ _fileList_] [_--name_ _structName_] [_--strip_ _prefix_]


```

--------------------------------

### WebsPath

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request path.

```APIDOC
## websGetPath

### Description
Get the request path.

### Signature
cchar * websGetPath(Webs *wp)
```

--------------------------------

### GoAhead Log Output Sample

Source: https://www.embedthis.com/goahead/doc/users/logFiles.html

Displays a sample of GoAhead's detailed log output, showing configuration and startup information.

```text
goahead: 2: Configuration for Embedthis GoAhead
goahead: 2: ---------------------------------------------
goahead: 2: Version:            3.0.0-0
goahead: 2: BuildType:          Debug
goahead: 2: CPU:                x64
goahead: 2: OS:                 macosx
goahead: 2: Host:               10.0.0.102
goahead: 2: Directory:          /Users/john/git/goahead
goahead: 2: Configure:          me configure
goahead: 2: ---------------------------------------------
goahead: 2: Started http://*:80
goahead: 2: Started https://*:443

```

--------------------------------

### WebsGetPassword

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request password.

```APIDOC
## websGetPassword

### Description
Get the request password.

### Signature
cchar * websGetPassword(Webs *wp)
```

--------------------------------

### logOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the log logging module, initializing it for use.

```APIDOC
## logOpen

### Description
Open the log logging module.

### Returns
Zero if successful.

### API Stability
Stable.
```

--------------------------------

### WebsGetMethod

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request method.

```APIDOC
## websGetMethod

### Description
Get the request method.

### Signature
cchar * websGetMethod(Webs *wp)
```

--------------------------------

### WebsGetFilename

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request filename.

```APIDOC
## websGetFilename

### Description
Get the request filename.

### Signature
cchar * websGetFilename(Webs *wp)
```

--------------------------------

### WebsGetDebug

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the debug flag.

```APIDOC
## websGetDebug

### Description
Get the debug flag.

### Signature
int websGetDebug(void)
```

--------------------------------

### WebsFsOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the file system module.

```APIDOC
## websFsOpen

### Description
Open the file system module.

### Signature
int websFsOpen(void)
```

--------------------------------

### WebsGetDateString

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets a date as a string.

```APIDOC
## websGetDateString

### Description
Get a date as a string.

### Signature
char * websGetDateString(WebsFileInfo *sbuf)
```

--------------------------------

### websFsOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the file system module.

```APIDOC
## websFsOpen

### Description
Open the file system module.

### Returns
Zero if successful, otherwise -1.
```

--------------------------------

### WebsFileOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens and initializes the file handler.

```APIDOC
## websFileOpen

### Description
Open and initialize the file handler.

### Signature
void websFileOpen(void)
```

--------------------------------

### websStatFile

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Get file status for a file.

```APIDOC
## websStatFile

### Description
Get file status for a file.

### Signature
`int websStatFile(cchar *path, WebsFileInfo *sbuf)`
```

--------------------------------

### websFileOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens and initializes the file handler.

```APIDOC
## websFileOpen

### Description
Open and initialize the file handler.

### Returns
None.
```

--------------------------------

### WebsGetSession

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the webs session object.

```APIDOC
## websGetSession

### Description
Get the webs session object.

### Signature
WebsSession * websGetSession(Webs *wp, int create)
```

--------------------------------

### websOpenRoute

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Initializes and opens the route module for use.

```APIDOC
## websOpenRoute

### Description
Open the route module.

### API Stability
Stable.
```

--------------------------------

### WebsGetServerAddress

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the server IP address.

```APIDOC
## websGetServerAddress

### Description
Get the server IP address.

### Signature
cchar * websGetServerAddress(void)
```

--------------------------------

### websSetEnv

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Create the CGI environment variables for the current request.

```APIDOC
## websSetEnv

### Description
Create the CGI environment variables for the current request.

### Signature
`void websSetEnv(Webs *wp)`
```

--------------------------------

### WebsGetQuery

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request query component.

```APIDOC
## websGetQuery

### Description
Get the request query component.

### Signature
cchar * websGetQuery(Webs *wp)
```

--------------------------------

### websSetEnv

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Create the CGI environment variables for the current request.

```APIDOC
## websSetEnv

### Description
Create the CGI environment variables for the current request.

### Parameters
- **wp** (Webs *) - Webs request object.
```

--------------------------------

### WebsGetProtocol

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request HTTP protocol.

```APIDOC
## websGetProtocol

### Description
Get the request HTTP protocol.

### Signature
cchar * websGetProtocol(Webs *wp)
```

--------------------------------

### WebsGetPort

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request TCP/IP port.

```APIDOC
## websGetPort

### Description
Get the request TCP/IP port.

### Signature
int websGetPort(Webs *wp)
```

--------------------------------

### WebsGetIfaddr

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request interface address.

```APIDOC
## websGetIfaddr

### Description
Get the request interface address.

### Signature
cchar * websGetIfaddr(Webs *wp)
```

--------------------------------

### sslOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the SSL module, initializing the SSL subsystem. Call this before using other SSL functions.

```APIDOC
## sslOpen

### Description
Open the ssl module.

### Returns
- Zero if successful, otherwise -1.

### API Stability
Stable.

### See Also
void sslClose (void )
void sslFree (Webs *wp)
ssize sslRead (Webs *wp, void *buf, ssize len)
int sslUpgrade (Webs *wp)
```

--------------------------------

### Configure GoAhead for ROM Support

Source: https://www.embedthis.com/goahead/doc/developers/rom.html

Run configure with the --rom option to enable ROM file system support and set the ME_ROM compiler definition.

```bash
./configure --rom
```

--------------------------------

### sstarts

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Tests if a string begins with a specified prefix.

```APIDOC
## sstarts

### Description
Test if the string starts with a given pattern.

### Parameters
- **str** (cchar *) - String to examine.
- **prefix** (cchar *) - Pattern to search for.

### Returns
Returns TRUE if the pattern was found. Otherwise returns zero.

### API Stability
Stable.
```

--------------------------------

### WebsGetEof

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request EOF status.

```APIDOC
## websGetEof

### Description
Get the request EOF status.

### Signature
int websGetEof(Webs *wp)
```

--------------------------------

### WebsGetCookie

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the request cookie if supplied.

```APIDOC
## websGetCookie

### Description
Get the request cookie if supplied.

### Signature
cchar * websGetCookie(Webs *wp)
```

--------------------------------

### websCgiOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the CGI handler, preparing it for processing CGI requests.

```APIDOC
## websCgiOpen

### Description
Open the CGI handler.

### Returns
- Zero if successful, otherwise -1.
```

--------------------------------

### webcomp Command Options

Source: https://www.embedthis.com/goahead/doc/man/webcomp.html

Details the available options for the webcomp command, such as specifying input files and the output structure name.

```bash
**--files** **fileList**
              Option to provide a list of files that should be converted.  **--p**
              **strip** Specifies a prefix to remove from each of the compiled file
              names.

       **--name** **structName**
              Specifies the name of top level C structure that holds the
              converted files.


```

--------------------------------

### Write Hello World in JST

Source: https://www.embedthis.com/goahead/doc/users/jst.html

Use the '<% %>" delimiters to embed Javascript. The 'write' function outputs content to the client.

```javascript
Today is <% write("Hello" + " World"); %>
```

--------------------------------

### WebsGetLogLevel

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the current trace log level.

```APIDOC
## websGetLogLevel

### Description
Get the current trace log level.

### Signature
int websGetLogLevel(void)
```

--------------------------------

### websLoad

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Loads routing tables from a specified configuration file.

```APIDOC
## websLoad

### Description
Load routing tables from the specified filename.

### Parameters
- **path** (cchar *) - Route configuration filename.

### Returns
Zero if successful, otherwise -1.

### API Stability
Stable.
```

--------------------------------

### WebsGetIndex

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the default index document name.

```APIDOC
## websGetIndex

### Description
Get the default index document name.

### Signature
cchar * websGetIndex(void)
```

--------------------------------

### WebsGetDocuments

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the GoAhead base documents directory.

```APIDOC
## websGetDocuments

### Description
Get the GoAhead base documents directory.

### Signature
char * websGetDocuments(void)
```

--------------------------------

### GoAhead Command-Line Synopsis

Source: https://www.embedthis.com/goahead/doc/man/goahead.html

Displays the basic command-line syntax for invoking the GoAhead web server, including common options and arguments.

```bash
**goahead** **[options]** **[documents]** **[[IP][:port]** **...]**

       **goahead**
           **--auth** **authFile**
           **--background**
           **--debugger**
           **--home** **directory**
           **--log** **logSpec**
           **--route** **routeFile**
           **--version**
           **--verbose**
           **[IP][:port]** **[documents]**
```

--------------------------------

### WebsErrorMsg

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets a message for a HTTP status code.

```APIDOC
## websErrorMsg

### Description
Get a message for a HTTP status code.

### Signature
cchar * websErrorMsg(int code)
```

--------------------------------

### bufCreate

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Creates a WebsBuf with specified growth increment and maximum size.

```APIDOC
## bufCreate

### Description
Create a buffer.

### Parameters
- **bp** (WebsBuf *) - Buffer reference.
- **increment** (int) - Incremental size to grow the buffer. This will be increased by a power of two each time the buffer grows.
- **maxsize** (int) - Maximum size of the buffer.

### Returns
Zero if successful.
```

--------------------------------

### WebsCgiOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the CGI handler.

```APIDOC
## websCgiOpen

### Description
Open the CGI handler.

### Signature
int websCgiOpen(void)
```

--------------------------------

### WebsGetServerUrl

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the server host name with port number.

```APIDOC
## websGetServerUrl

### Description
Get the server host name with port number.

### Signature
cchar * websGetServerUrl(void)
```

--------------------------------

### websRuntimeOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Open the runtime code. Called from websOpen.

```APIDOC
## websRuntimeOpen

### Description
Open the runtime code. Called from websOpen.

### Returns
- Zero if successful.
```

--------------------------------

### Configure Default Listen Addresses

Source: https://www.embedthis.com/goahead/doc/users/ports.html

Set the default HTTP and HTTPS listen addresses during the build configuration. Use '*' to listen on all network interfaces.

```bash
./configure --set listen="http://*:80, https://*:443"

```

--------------------------------

### WebsGetServerAddressUrl

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the server IP address with port number.

```APIDOC
## websGetServerAddressUrl

### Description
Get the server IP address with port number.

### Signature
cchar * websGetServerAddressUrl(void)
```

--------------------------------

### WebsGetCgiCommName

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets a unique temporary filename for CGI communications.

```APIDOC
## websGetCgiCommName

### Description
Get a unique temporary filename for CGI communications.

### Signature
char * websGetCgiCommName(void)
```

--------------------------------

### Log Entry Format

Source: https://www.embedthis.com/goahead/doc/users/logFiles.html

Illustrates the standard format for log entries, which includes the program name and log level.

```text
program:logLevel

```

--------------------------------

### Sample Password Verifier Routine in C

Source: https://www.embedthis.com/goahead/doc/developers/authstore.html

This C routine can be used as a starter for custom password verification. It handles both plain text and Digest authentication, and creates or updates user roles within GoAhead.

```c
static bool verifyPassword(Webs *wp)
{
    char    *password, *roles;
    /*
        If using Digest auth, compare the digest of the password
     */
    password = (wp->digest) ? wp->digest : wp->user->password;
    if (!CHECK_PASSWORD(wp->username, password, &roles)) {
        return 0;
    }
    /*
        Create the user inside GoAhead and set the user roles/abilities
     */
    if ((wp->user = websLookupUser(wp->username)) == 0) {
        if ((wp->user = websAddUser(wp->username, 0, roles)) == 0) {
            return 0;
        }
        websSetUserRoles(wp->username, roles);
    }
    return 1;
}

```

--------------------------------

### Define Routes in route.txt

Source: https://www.embedthis.com/goahead/doc/users/routing.html

Configure request routing by defining routes with URI patterns and associated handlers. Routes are tested in the order they appear.

```route
route uri=/cgi-bin dir=cgi-bin handler=cgi
route uri=/action handler=action
route uri=/ extensions=jst,asp handler=jst
route uri=/ methods=OPTIONS|TRACE handler=options
```

--------------------------------

### websGetBackground

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets the background execution flag. If GoAhead is invoked with background, it will run as a daemon in the background.

```APIDOC
## websGetBackground

### Description
If GoAhead is invoked with background, it will run as a daemon in the background.

### Returns
True if GoAhead is running in the background.
```

--------------------------------

### websGetCgiCommName

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Gets a unique temporary filename for CGI communications. The caller must free the returned string.

```APIDOC
## websGetCgiCommName

### Description
Get a unique temporary filename for CGI communications.

### Returns
Allocated filename string. Caller must free.
```

--------------------------------

### Event Management Functions

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Functions for managing scheduled events, including starting, stopping, restarting, and running events.

```APIDOC
## websRestartEvent

### Description
Restart an event.

### Parameters
- **id** (int) - Event id allocated by websStartEvent.
- **delay** (int) - Delay in milliseconds till the event next runs.

### Stability
Stable.

## websRunEvents

### Description
Run due events.

### Returns
- Time delay till the next event.

### Stability
Stable.

## websStartEvent

### Description
This schedules an event to run once. The event can be rescheduled in the callback by invoking websRestartEvent.

### Parameters
- **delay** (int) - Delay in milliseconds in which to run the callback.
- **proc** (WebsEventProc) - Callback procedure function. Signature is: void (*fn)(void *data, int id).
- **data** (void *) - Data reference to pass to the callback.

### Returns
- A positive integer event ID.

### Stability
Stable.

## websStopEvent

### Description
Stop an event.

### Parameters
- **id** (int) - Event id allocated by websStartEvent.

### Stability
Stable.
```

--------------------------------

### Server Initialization and Control Functions

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Functions for initializing and controlling the GoAhead web server, including listening for connections, loading routes, and managing server state.

```APIDOC
## websJstOpen

### Description
Open the Javascript module.

### Signature
`int websJstOpen(void)`

## websListen

### Description
Listen on a TCP/IP address endpoint.

### Signature
`int websListen(cchar *endpoint)`

## websLoad

### Description
Load routing tables from the specified filename.

### Signature
`int websLoad(cchar *path)`

## websOpen

### Description
Open the web server.

### Signature
`int websOpen(cchar *documents, cchar *routes)`

## websOpenAuth

### Description
Open the authentication module.

### Signature
`int websOpenAuth(int minimal)`

## websOpenRoute

### Description
Open the routing module.

### Signature
`int websOpenRoute(void)`

## websOptionsOpen

### Description
Open the options handler.

### Signature
`int websOptionsOpen(void)`

## websOsClose

### Description
Close the O/S dependent code.

### Signature
`void websOsClose(void)`

## websOsOpen

### Description
Open the O/S dependent code.

### Signature
`int websOsOpen(void)`

## websPageOpen

### Description
Open a web page document for a request.

### Signature
`int websPageOpen(Webs *wp, int mode, int perms)`

## websRuntimeClose

### Description
Close the runtime code.

### Signature
`void websRuntimeClose(void)`

## websRuntimeOpen

### Description
Open the runtime code.

### Signature
`int websRuntimeOpen(void)`

## websServer

### Description
One line embedding API.

### Signature
`int websServer(cchar *endpoint, cchar *documents)`

## websServiceEvents

### Description
Service I/O events until finished.

### Signature
`void websServiceEvents(int *finished)`

## websSetBackground

### Description
Set the background processing flag.

### Signature
`void websSetBackground(int on)`
```

--------------------------------

### wopenAlloc

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Initializes the walloc module, which handles memory allocations. It should be called at the beginning of the application. Optionally, a user-supplied buffer can be provided for allocations. This is a stable API function.

```APIDOC
## wopenAlloc

### Description
Initialize the walloc module.

### Parameters
- **buf** (void *) - Optional user supplied block of memory to use for allocations.
- **bufsize** (int) - Size of buf.
- **flags** (int) - Allocation flags. Set to WEBS_USE_MALLOC to permit the use of malloc() to grow memory.

### Returns
- Zero if successful, otherwise -1.
```

--------------------------------

### websGetMethod

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Retrieves the HTTP method used for the current request (e.g., GET, POST). The caller should not free the returned string.

```APIDOC
## websGetMethod

### Description
Get the request method.

### Parameters
- **wp** (Webs *) - Webs request object.

### Returns
- **char** - HTTP method string. Caller should not free.
```

--------------------------------

### websSetHost

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Define the host name for the server.

```APIDOC
## websSetHost

### Description
Define the host name for the server.

### Signature
`void websSetHost(cchar *host)`
```

--------------------------------

### websServer

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

One line embedding API. This call will also open auth.txt and route.txt for authentication and routing configuration.

```APIDOC
## websServer

### Description
One line embedding API. This call will also open auth.txt and route.txt for authentication and routing configuration.

### Parameters
- **endpoint** (cchar *) - IP:PORT address on which to listen.
- **documents** (cchar *) - Directory containing web documents to serve.
```

--------------------------------

### websOpenFile

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens a web page document for the current request. This function is used to get a file handle for subsequent read operations.

```APIDOC
## websOpenFile

### Description
Open the web page document for the current request.

### Parameters
#### Path Parameters
- **path** (cchar *) - Required - Filename path to open.
- **flags** (int) - Required - File open flags.
- **mode** (int) - Required - Permissions mask.

### Returns
Positive file handle if successful, otherwise -1.
```

--------------------------------

### Configure IPv6 Listen Address

Source: https://www.embedthis.com/goahead/doc/users/ports.html

Specify an IPv6 listen address during build configuration. Enclose the IPv6 address in brackets if a port is also specified.

```bash
./configure --set listen="http://[2001:0db8:85a3:08d3:1319:8a2e:0370:7348]:8080"

```

--------------------------------

### websListen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Listens on a specified TCP/IP address endpoint for incoming connections.

```APIDOC
## websListen

### Description
Listen on a TCP/IP address endpoint.

### Parameters
- **endpoint** (cchar *) - IPv4 or IPv6 address on which to listen. For IPv6 addresses, use the format: [aaaa:bbbb:cccc:dddd:eeee:ffff:gggg:hhhh:iiii]:port.

### Returns
Positive integer holding a Socket ID handle if successful, otherwise -1.
```

--------------------------------

### websOptionsOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the options handler for the web server. This function is typically used to access or modify server options.

```APIDOC
## websOptionsOpen

### Description
Open the options handler.

### Returns
Zero if successful, otherwise -1.
```

--------------------------------

### Create Password and Update Auth File

Source: https://www.embedthis.com/goahead/doc/man/gopass.html

Use this command to create a password for a user and update the specified authentication configuration file. The password will be hashed using the default blowfish cipher.

```bash
gopass --file auth.conf --password pass1 example.com joshua
administrator buyer

```

--------------------------------

### Define Custom JST Function in C

Source: https://www.embedthis.com/goahead/doc/users/jst.html

Define a new JST function by binding a C function using 'websDefineJst'. This example shows how to create a 'date' function.

```c
static getDate(int jid, Webs *wp, int argc, char **argv) {
    char *date = websGetDate(0);
    websWrite(wp, "%s", date);
    gfree(date);
}
**websDefineJst("date", getDate);**
```

--------------------------------

### websTimeOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the date/time parsing module. This function initializes resources required for date and time parsing operations.

```APIDOC
## websTimeOpen

### Description
Open the date/time parsing module.

### Returns
Zero if successful, otherwise -1.

### API Stability
Evolving.
```

--------------------------------

### socketOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Initializes the socket module. This function must be called before using other socket functions.

```APIDOC
## socketOpen

### Description
Open the socket module.

### Returns
- **int** - Zero if successful, otherwise -1.
```

--------------------------------

### Call a GoAction via URI

Source: https://www.embedthis.com/goahead/doc/users/goactions.html

Client requests to URIs starting with /action/NAME invoke the corresponding GoAction. Query string parameters are automatically decoded and available as GoAhead variables.

```http
/action/buy?name=John&item=candy           
```

--------------------------------

### websSetIpAddr

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Define the host IP address.

```APIDOC
## websSetIpAddr

### Description
Define the host IP address.

### Signature
`void websSetIpAddr(cchar *ipaddr)`
```

--------------------------------

### Calculate Password to Standard Output

Source: https://www.embedthis.com/goahead/doc/man/gopass.html

Omit the '--file' option to calculate the password and display it directly to the standard output. This is useful for testing or when not immediately updating a configuration file.

```bash
gopass --password pass1 example.com joshua administrator buyer

```

--------------------------------

### Define Role Abilities in auth.txt

Source: https://www.embedthis.com/goahead/doc/users/authentication.html

Specify user abilities based on Unix group membership. Create a role definition in auth.txt that matches a Unix group name to grant abilities to users in that group.

```plaintext
Role staff add,edit,delete
```

--------------------------------

### socketListen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens a listening socket on a specified host and port. It accepts a callback function to handle incoming connections.

```APIDOC
## socketListen

### Description
Open a listening socket.

### Parameters
#### Path Parameters
- **host** (cchar *) - Host IP address on which to listen. Set to NULL to listen on all interfaces.
- **port** (int) - TCP/IP port on which to listen.
- **accept** (SocketAccept) - SocketAccept callback function to invoke to receive incoming connections.
- **flags** (int) - Reserved.

### Returns
- **int** - Zero if successful, otherwise -1.
```

--------------------------------

### Configure Continue Handler for Authentication

Source: https://www.embedthis.com/goahead/doc/users/handlers.html

This route directive uses the continue handler to redirect to a login page if not authenticated. If authenticated, routing continues to the next route. See User Authentication for more examples.

```nginx
route uri=/ auth=form handler=continue redirect=401@/login.html
```

--------------------------------

### WebsCreateSession

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Creates a new web session.

```APIDOC
## websCreateSession

### Description
Test if a user possesses the required ability. (Note: Description seems mismatched with function name, assuming it creates a session based on context).

### Signature
WebsSession * websCreateSession(Webs *wp)
```

--------------------------------

### bufGetBlk

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Copies a block of data from the buffer and advances the servp pointer.

```APIDOC
## bufGetBlk

### Description
Copy a block of from the buffer and adjust the servp.

### Parameters
- **bp** (WebsBuf *) - Buffer reference.
- **blk** (char *) - Block into which to place the data.
- **len** (ssize) - Length of the block.

### Returns
Number of bytes copied.
```

--------------------------------

### websSetPasswordStoreVerify

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Set the password store verify callback.

```APIDOC
## websSetPasswordStoreVerify

### Description
Set the password store verify callback.

### Signature
`void websSetPasswordStoreVerify(WebsVerify verify)`
```

--------------------------------

### Catch-All Route

Source: https://www.embedthis.com/goahead/doc/users/routing.html

Implement a catch-all route to handle requests that do not match any preceding routes. If no handler is specified, the 'file' handler is used by default.

```goahead
route uri=/
```

--------------------------------

### Configure Log File Location

Source: https://www.embedthis.com/goahead/doc/users/logFiles.html

Shows how to set the default log file location and trace level during the GoAhead build configuration.

```bash
./configure --set trace="file:level"

```

--------------------------------

### websSetIndex

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Create and send a request response.

```APIDOC
## websSetIndex

### Description
Create and send a request response.

### Signature
`void websSetIndex(cchar *filename)`
```

--------------------------------

### sfmtv

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Formats a string using printf-style formatting with va_list arguments, offering a secure alternative to sprintf that handles null arguments.

```APIDOC
## sfmtv

### Description
Format the given arguments according to the printf style format. This is a secure replacement for sprintf, it can handle null arguments without crashes.

### Parameters
- **format** (cchar *) - Printf style format string.
- **args** (va_list) - Varargs argument obtained from va_start.

### Returns
- (char **) Returns a newly allocated string.
```

--------------------------------

### websActionOpen

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Opens the action handler, preparing it to process actions defined via websDefineAction.

```APIDOC
## websActionOpen

### Description
Open the action handler.
```

--------------------------------

### websTempFile

Source: https://www.embedthis.com/goahead/doc/ref/api/goahead.html

Create a temporary filename. This does not guarantee the filename is unique or that it is not already in use by another application.

```APIDOC
## websTempFile

### Description
Create a temporary filename. This does not guarantee the filename is unique or that it is not already in use by another application.

### Signature
`char *websTempFile(cchar *dir, cchar *prefix)`
```

--------------------------------

### Enable TRACE and OPTIONS Methods

Source: https://www.embedthis.com/goahead/doc/users/routing.html

Selectively enable the TRACE and OPTIONS HTTP methods for specific routes. These methods are disabled by default for security.

```goahead
route uri=/partition/ methods=OPTIONS|TRACE handler=options
```
Tokens:
Raw