Netscape 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