Netscape FastTrack Server Programmer's Guide

Introduction

What are the CGI and the server plug-in API?

Conventions used in this book

Chapter 1 Server programming overview

Comparison of server programming tools

Java and java applets

JavaScript

Server plug-in API

Server application programming

CGI (Common Gateway Interface)

Server plug-in API

Java and JavaScript Server APIs

Chapter 2 CGI basics

The CGI request process in detail

The client sends the request

The server creates the CGI process

The server assigns variables and opens data paths

The CGI program sends the response to the client

Security concerns about CGI

Accessing CGI programs through URLs

Embedding information in URLs

Accepting user input from URLs and other sources

HTML form data 33

Input to an ISINDEX search dialog 34

ISMAP or imagemaps 34

Data the server sends to the CGI program

Accessing environment variables

Using Java Applets 35

Using C or C++ 35

Using Perl 35

Using the Bourne shell 35

Using the C shell 35

Environment variables and their formats

Secure server variable formats

HTTP headers as environment variables 41

Using standard input to get information

Sending command-line arguments to your CGI program

Sending output from CGI programs

Bypassing the server: nonparsed headers

CGI generic headers

CGI-specific headers

Sample program output

Configuring your server to use CGI programs

Specifying a CGI directory

Activating CGI as a file type for parts of the server

Setting up a default query handler

Customizing server-parsed HTML

Server-parsed HTML commands 50

Environment variables that affect parsing 52

Adding signatures (trailers) to files

Chapter 3 Tips for developing CGI programs

A sample CGI shell script

A sample CGI program in Perl

A more detailed Perl example

A sample CGI program as a Java Applet

A sample CGI program in ANSI C

Chapter 4 Server operation

How the server handles client requests

What are server application functions?

Configuring the server

The magnus.conf file

Directive syntax 74

The obj.conf file

The structure of obj.conf 76

Required objects for obj.conf 78

Data in the server: the parameter block

Details for each directive/step

AuthTrans 80

NameTrans 81

PathCheck 82

ObjectType 82

Service 82

Initialization functions

Equivalents to CGI Environment Variables

Some new features in version 2.0

Threading

Caching

Software multihoming

Chapter 5 Creating server plug-in functions

What is the server plug-in API?

Writing plug-in functions

The server plug-in API header files

Getting data from the server: the parameter block

Passing parameters to server application functions

Parameter-manipulating functions 96

Data structures and data access functions 97

Application function status codes 98

Reporting errors to the server

Compiling and linking your code

Loading your shared object

Using your plug-in functions

Chapter 6 Server plug-in API function definitions

cinfo_find base/cinfo.h 103

condvar_init base/crit.h 104

condvar_notify base/crit.h 104

condvar_terminate base/crit.h 105

condvar_wait base/crit.h 105

crit_enter base/crit.h 106

crit_exit base/crit.h 106

crit_init base/crit.h 106

crit_terminate base/crit.h 107

daemon_atrestart netsite.h 107

filebuf_buf2sd base/buffer.h 108

filebuf_close base/buffer.h 108

filebuf_getc base/buffer.h 109

filebuf_open base/buffer.h 109

filebuf_open_nostat base/buffer.h 110

FREE netsite.h 110

func_exec frame/func.h 111

func_find frame/func.h 111

log_error frame/log.h 112

magnus_atrestart netsite.h 113

MALLOC netsite.h 113

net_ip2host base/net.h 114

net_read base/net.h 115

net_socket base/net.h 115

net_write base/net.h 116

netbuf_buf2sd base/buffer.h 116

netbuf_close base/buffer.h 117

netbuf_getc base/buffer.h 117

netbuf_grab base/buffer.h 117

netbuf_open base/buffer.h 118

param_create base/pblock.h 118

param_free base/pblock.h 119

pblock_copy base/pblock.h 119

pblock_create base/pblock.h 120

pblock_dup base/pblock.h 120

pblock_find base/pblock.h 121

pblock_findval base/pblock.h 121

pblock_free base/pblock.h 122

pblock_nninsert base/pblock.h 122

pblock_nvinsert base/pblock.h 123

pblock_pb2env base/pblock.h 124

pblock_pblock2str base/pblock.h 124

pblock_pinsert base/pblock.h 125

pblock_remove base/pblock.h 125

pblock_str2pblock base/pblock.h 126

PERM_FREE netsite.h 126

PERM_MALLOC netsite.h 127

PERM_STRDUP netsite.h 127

protocol_dump822 frame/protocol.h 128

protocol_set_finfo frame/protocol.h 128

protocol_start_response frame/protocol.h 129

protocol_status frame/protocol.h 130

protocol_uri2url frame/protocol.h 131

protocol_uri2url_dynamic frame/protocol.h 131

REALLOC netsite.h 132

request_create frame/req.h 133

request_free frame/req.h 133

request_header frame/req.h 133

request_stat_path frame/req.h 134

request_translate_uri frame/req.h 135

sem_grab base/sem.h 135

sem_init base/sem.h 136

sem_release base/sem.h 136

sem_terminate base/sem.h 137

sem_tgrab base/sem.h 137

session_create base/session.h 137

session_free base/session.h 138

session_maxdns base/session.h 138

shexp_casecmp base/shexp.h 139

shexp_cmp base/shexp.h 139

shexp_match base/shexp.h 141

shexp_valid base/shexp.h 141

shmem_alloc base/shmem.h 142

shmem_free base/shmem.h 142

STRDUP netsite.h 143

system_errmsg base/file.h 143

system_fclose base/file.h 144

system_flock base/file.h 144

system_fopenRO base/file.h 145

system_fopenRW base/file.h 145

system_fopenWA base/file.h 146

system_fread base/file.h 146

system_fwrite base/file.h 147

system_fwrite_atomic base/file.h 147

system_gmtime base/file.h 148

system_localtime base/file.h 148

system_ulock base/file.h 149

system_unix2local base/file.h 149

systhread_current base/systhr.h 150

systhread_getdata base/systhr.h 150

systhread_newkey base/systhr.h 151

systhread_setdata base/systhr.h 151

systhread_sleep base/systhr.h 152

systhread_start base/systhr.h 152

systhread_terminate base/systhr.h 152

systhread_timerset base/systhr.h 153

util_can_exec base/util.h 153

util_chdir2path base/util.h 154

util_env_create base/util.h 154

util_env_find base/util.h 155

util_env_free base/util.h 155

util_env_replace base/util.h 156

util_env_str base/util.h 156

util_getline base/util.h 157

util_hostname base/util.h 157

util_is_mozilla base/util.h 158

util_is_url base/util.h 158

util_itoa base/util.h 159

util_later_than base/util.h 159

util_sh_escape base/util.h 160

util_snprintf base/util.h 160

util_sprintf base/util.h 161

util_strcasecmp base/systems.h 162

util_strncasecmp base/systems.h 162

util_uri_escape base/util.h 163

util_uri_is_evil base/util.h 163

util_uri_parse base/util.h 164

util_uri_unescape base/util.h 164

util_vsnprintf base/util.h 164

util_vsprintf base/util.h 165

Chapter 7 Java API

Class netscape.server.applet.HttpApplet

Variables

BAD_REQUEST 168

boundaryCount 168

boundaryGen 168

boundaryStack 169

FORBIDDEN 169

formData 169

NO_RESPONSE 169

NOT_FOUND 169

NOT_IMPLEMENTED 170

NOT_MODIFIED 170

OK 170

REDIRECT 170

SERVER_ERROR 170

UNAUTHORIZED 170

Constructor

public HttpApplet() 171

Methods

getMethod 171

getURI 171

getProtocol 172

getQuery 172

getPath 172

setContentType 172

getURL 172

returnNormalResponse--one parameter 173

returnNormalResponse--two parameters 173

returnFile--two parameters 174

returnFile--one parameter 174

returnErrorResponse--three parameters 174

returnErrorResponse--two parameters 175

returnMultipartResponse--one parameter 175

returnMultipartResponse--two parameters 176

endMultipartResponse 176

startResponse 176

setStatus--two parameters 177

setStatus--one parameter 177

setFileInfo 177

translateURI 177

uri2url 178

getFormData 178

getFormField 178

handleRequest 179

Class netscape.server.applet.Server

Variables

Methods

getAddress 180

getListeningAddress 180

getListeningPort 180

securityActive 180

Class netscape.server.applet.ServerApplet

Variables

ABORTED 181

EXIT 181

name 182

NOACTION 182

PROCEED 182

responseStarted 182

socket 182

Constructor

ServerApplet 183

Methods

getClientSocket 183

getClientProperty 183

getConfigProperty 184

getHeader 184

getInputStream 184

getOutputStream 184

getRequestProperty 185

getResponseProperty 185

getServer 185

getServerProperty 186

handleRequest 186

inform 186

reportMisconfiguration 187

reportCatastrophe 187

reportFailure 187

reportSecurity 187

run 187

setResponseProperty 188

warn 188

Class netscape.server.applet.URIUtil

Variables

Methods

isEvil 189

splitFormData 190

uriEscape 190

urlEscape 190

urlUnescape 190

Appendix A Server data structures

The Session data structure

The parameter block (pblock) data structure

The pb_entry data structure 194

The pb_param data structure 194

The Client parameter block

The Request data structure

The stat data structure

The shared memory structure shmem_s

The netbuf data structure

The filebuffer data structure

The cinfo data structure

The SYS_NETFD data structure

The SYS_FILE data structure

The SEMAPHORE data structure

The sockaddr_in data structure

The CONDVAR data structure

The CRITICAL data structure

The SYS_THREAD data structure

Appendix B Server configuration files

Syntax

Case sensitivity 200

Separators 200

Quotes 200

Spaces 200

Comments 200

Line continuation 200

Directives in magnus.conf

ServerName directive

Port directive

User directive

MaxProcs directive

MinThreads directive

MaxThreads directive

ErrorLog directive

PidLog directive

LoadObjects directive

RootObject directive

Chroot directive

DNS directive

Security directive

ServerKey directive

ServerCert directive

Ciphers directive

Directives in obj.conf

Summaries of the obj.conf directives

Init directive

load-types function 216

init-clf 216

flex-init function 217

init-uhome function 219

cindex-init function 219

pool-init function 220

cache-init function 221

dns-cache-init function 222

init-cgi function 222

AuthTrans Directive

basic-ncsa function 223

NameTrans directive

pfx2dir function 225

unix-home function 225

document-root function 226

redirect function 226

mozilla-redirect function 226

home-page function 227

PathCheck directive

unix-uri-clean function 227

find-index function 227

require-auth function 228

deny-existence function 228

find-links function 229

find-pathinfo function 229

ObjectType directive

type-by-extension function 230

image-switch function 230

type-by-exp function 230

force-type function 231

shtml-hacktype function 231

Service directive

send-file function 232

send-error function 232

send-range function 233

append-trailer function 233

send-cgi function 233

query-handler function 234

imagemap function 234

index-simple function 234

index-common function 234

parse-html function 235

upload-file function 235

remove-file function 235

list-dir function 236

make-dir function 236

remove-dir function 236

rename-file function 237

key-toosmall function 237

AddLog directive

common-log function 238

flex-log function 238

record-useragent function 239

Error directive

key-toosmall function 240

The mime.types file

The admpw file

Index