Function Categories

The AOLserver Tcl functions are divided into four categories. The tables below list the functions in each category. Detailed descriptions of the functions are provided in alphabetical order in the remainder of this chapter.

Core functions

Core functions are available regardless of which modules are or are not loaded.

Function	Description
env	Manipulate environment variables
ns_atclose	Register a script to be executed when the current connection closes
ns_atexit	Register a script to be run at shutdown
ns_atshutdown	Register a script to be run at shutdown
ns_atsignal	Register a script to be run in response to a SIGHUP signal
ns_cache_flush	Remove cache entry
ns_cache_names	Return cache names
ns_cache_size	Return size of cache
ns_cache_stats	Return cache statistics
ns_chmod	Change a file's access permissions
ns_config	Extract information from the configuration file
ns_configsection	Return values of a configuration file section
ns_configsections	Return values of all configuration file sections
ns_conn	Find information about the HTTP connection
ns_conncptofp	Write content to a file
ns_connsendfp	Write contents of file to conn
ns_cp	Copy one file to another
ns_cpfp	Copy a specified number of bytes from one file to another
ns_crypt	Encrypt password
ns_eval	Evaluate Tcl (obsolete)
ns_fmttime	Return a formatted date and time
ns_ftruncate	Truncate an open file to a specified length
ns_getcsv	Read CSV data from a file
ns_getform	Return an ns_set that contains all of the query data that was part of the HTTP request
ns_get_multipart_formdata	Handle the POST action of a form containing one file widget
ns_geturl	Fetch a URL
ns_gifsize	Determine the width and height of a GIF87 or GIF89 image
ns_gmtime	Return time in GMT form
ns_guesstype	Lookup MIME type
ns_hrefs	Return list of HTML <A> links
ns_httpget	Open an HTTP connection and fetch a page
ns_httpopen	Open an HTTP connection
ns_httptime	Convert time in seconds to HTTP header format
ns_info	Find information about AOLserver
ns_jpegsize	Determine the width and height of a JPEG image
ns_kill	Send a signal to a process
ns_library	Return directory for a server's Tcl library
ns_link	Create a link
ns_localtime	Return local time
ns_log	Write messages to the error log
ns_logroll	Roll server log
ns_markfordelete	Mark interpreter for deletion
ns_mkdir	Create a directory
ns_mktemp	Return a unique file name based on a template
ns_modlog	Send notice to the log
ns_modlogcontrol	Define log realms
ns_modulepath	Return server directory
ns_normalizepath	Normalize a path
ns_param	Define a parameter in the configuration file
ns_parseheader	Parse HTTP header
ns_parsehttptime	Return number of seconds from HTTP time
ns_parsequery	Parse querystring
ns_queryexists	Check for a key in the query data that was part of the HTTP request
ns_queryget	Get a value from the query data that was part of the HTTP request
ns_querygetall	Get multiple query values
ns_quotehtml	Escape <, >, and & characters
ns_rand	Generate a random number
ns_register_filter	Register a filter function for a method/URL combination
ns_register_proc	Register a procedure for a URL
ns_register_trace	Register a Tcl trace script to a method and matching URL (obsolete)
ns_rename	Rename a file
ns_requestauthorize	Check permissions
ns_respond	Build a complete response
ns_return	Return information to client
ns_rmdir	Remove a directory
ns_rollfile	Roll an arbitrary file
ns_rwlock	Create, destroy, and manipulate read/write locks
ns_section	Define a section in the configuration file
ns_sendmail	Send a mail message
ns_server	Get information about a virtual server
ns_set	Manipulate sets of key-value pairs
ns_setexpires	Set Expires header
ns_set_precision	Set precision for floating-point to string conversions
ns_share	Share variable among all Tcl interpreters
ns_shutdown	Shut down the server and optionally restart it
ns_sleep	Sleep for a specified number of seconds
ns_socketpair	Create a pair of connected sockets
ns_striphtml	Remove HTML tags from a string
ns_symlink	Create a symbolic link
ns_time	Return current time in seconds
ns_tmpnam	Generate a temporary file name
ns_truncate	Truncate a file to a specified length
ns_unlink	Remove a file
ns_unregister_proc	Unregister a procedure for a URL
ns_url2file	Return file corresponding to URL
ns_urldecode	Decode characters
ns_urlencode	Encode characters in a URL
ns_uudecode	Perform base-64 decode
ns_uuencode	Perform base-64 encode
ns_write	Write raw content back to the client
ns_writecontent	Write content to a file
ns_writefp	Write file contents to the connection

ADP functions

These functions are for use within AOLserver Dynamic Pages (ADPs):

Function	Description
ns_adp_abort	Stop processing of ADP and throw away all output
ns_adp_argc	Return number of ADP arguments
ns_adp_argv	Return ADP argument values
ns_adp_bind_args	Bind ADP arguments to names
ns_adp_break	Stop processing of ADP and flush all output
ns_adp_debug	Connect to TclPro debugger
ns_adp_dir	Return directory where ADP resides
ns_adp_dump	Return ADP output buffer
ns_adp_eval	Evaluate ADP
ns_adp_exception	Return ADP exception state
ns_adp_include	Write contents of file to page
ns_adp_parse	Process an ADP file and return the result as a string
ns_adp_puts	Write string or Tcl command output to page
ns_adp_registertag	Register an ADP tag
ns_adp_return	Stop processing of ADP and flush all output
ns_adp_stream	Begin ADP streaming
ns_adp_tell	Return bytes in ADP output buffer
ns_adp_trunc	Clear ADP output buffer
ns_register_adptag	Register a tag for use within an ADP

Control port interface functions

This function is available for use within the control port interface:

Function	Description
ns_cport	Control port interface commands
ns_menu	Administer server in control port

Scheduled procedures

These functions allow you to specify a Tcl script to be run daily, weekly, or at specified intervals.

Function	Description
ns_schedule_daily	Schedule a procedure to run once a day
ns_schedule_proc	Schedule a procedure to run at specified intervals
ns_schedule_weekly	Schedule a procedure to run once a week
ns_unschedule_proc	Stop a scheduled procedure

Sockets interface

The following functions are available for managing sockets:

Function	Description
ns_hostbyaddr	Resolve an IP address to a hostname
ns_sockaccept	Accept a new socket connection
ns_sockblocking	Set socket blocking
ns_sockcallback	Register a socket callback script
ns_sockcheck	Check if a socket is connected
ns_sockopen	Create a socket listening for connections
ns_socklistencallback	Run script on connection
ns_socknonblocking	Set socket nonblocking
ns_socknread	Return bytes to be read
ns_sockopen	Connect to a remote host on the specified port
ns_sockselect	Determine readable file id's

Threads interface

The following functions are available for managing threads and thread synchronozation objects:

Function	Description
ns_cond	Manage events
ns_critsec	Manage critical sections
ns_event	Manage events
ns_mutex	Manage mutexes
ns_sema	Manage semaphores
ns_thread	Manage threads

Permissions functions

Permissions functions are available only when the nsperm module is loaded. See Chapter 6 for information on the access control system. Note that the entire user interface for the access control system is implemented in Tcl. Follow the nsperm link on the Tcl Script Maintenance page to see the scripts..

Function	Description
ns_checkurl	Authorize a request
ns_passwordcheck	Verify a user/password combination
ns_perm	Add users, groups, and permissions
ns_permpasswd	Update existing password

Database Services functions

Database services functions are available only when the nsdb module is loaded.

Function	Description
ns_db	Access the AOLserver database
ns_dbconfigpath	Get nsdb section name
ns_dberror	Return SQL error information
ns_dbformvalue	Retrieve the value of a column specified by form data
ns_dbformvalueput	Set default values in an HTML form for accessing the database
ns_dbquotename	Surround a name by double quotes if it contains a space
ns_dbquotevalue	Prepare a value string for inclusion in an SQL statement
ns_deleterow	Delete row in specified table corresponding to form data
ns_ext	Send information to the database proxy daemon
ns_findrowbyid	Return row corresponding to specified key/value pairs
ns_insertrow	Insert form data into specified table as a new row
ns_localsqltimestamp	Return a SQL timestamp containing the local time
ns_pooldescription	Get database pool description