<!-- d function#1 <p><bf>$1</bf>\label{$1}<p><descrip> --> <!doctype linuxdoc system> <article> <title> {The <bf>S-lang</bf> C Library Reference} <author> John E. Davis, <tt>davis@space.mit.edu</tt> <date> Sat Feb 3 15:48:12 2001 <toc> <sect><bf>SLsmg_fill_region</bf><label id="SLsmg_fill_region"><p><descrip> <tag> Synopsis </tag> Fill a rectangular region with a character <tag> Usage </tag> <tt>void SLsmg_fill_region (r, c, nr, nc, ch)</tt> <tscreen><verb> int r int c unsigned int nr unsigned int nc unsigned char ch </verb></tscreen> <tag> Description </tag> The <tt>SLsmg_fill_region</tt> function may be used to a rectangular region with the character <tt>ch</tt> in the current color. The rectangle's upper left corner is at row <tt>r</tt> and column <tt>c</tt>, and spans <tt>nr</tt> rows and <tt>nc</tt> columns. The position of the virtual cursor will be left at (<tt>r</tt>, <tt>c</tt>). <tag> See Also </tag> <tt>SLsmg_write_char, SLsmg_set_color</tt> </descrip><p> <sect><bf>SLsmg_set_char_set</bf><label id="SLsmg_set_char_set"><p><descrip> <tag> Synopsis </tag> Turn on or off line drawing characters <tag> Usage </tag> <tt>void SLsmg_set_char_set (int a);</tt> <tag> Description </tag> <tt>SLsmg_set_char_set</tt> may be used to select or deselect the line drawing character set as the current character set. If <tt>a</tt> is non-zero, the line drawing character set will be selected. Otherwise, the standard character set will be selected. <tag> Notes </tag> There is no guarantee that this function will actually enable the use of line drawing characters. All it does is cause subsequent characters to be rendered using the terminal's alternate character set. Such character sets usually contain line drawing characters. <tag> See Also </tag> <tt>SLsmg_write_char, SLtt_get_terminfo</tt> </descrip><p> <sect><bf>int SLsmg_Scroll_Hash_Border;</bf><label id="int SLsmg_Scroll_Hash_Border;"><p><descrip> <tag> Synopsis </tag> Set the size of the border for the scroll hash <tag> Usage </tag> <tt>int SLsmg_Scroll_Hash_Border = 0;</tt> <tag> Description </tag> This variable may be used to ignore the characters that occur at the beginning and the end of a row when performing the hash calculation to determine whether or not a line has scrolled. The default value is zero which means that all the characters on a line will be used. <tag> See Also </tag> <tt>SLsmg_refresh</tt> </descrip><p> <sect><bf>SLsmg_suspend_smg</bf><label id="SLsmg_suspend_smg"><p><descrip> <tag> Synopsis </tag> Suspend screen management <tag> Usage </tag> <tt>int SLsmg_suspend_smg (void)</tt> <tag> Description </tag> <tt>SLsmg_suspend_smg</tt> can be used to suspend the state of the screen management facility during suspension of the program. Use of this function will reset the display back to its default state. The funtion <tt>SLsmg_resume_smg</tt> should be called after suspension. It returns zero upon success, or <tt>-1</tt> upon error. This function is similar to <tt>SLsmg_reset_smg</tt> except that the state of the display prior to calling <tt>SLsmg_suspend_smg</tt> is saved. <tag> See Also </tag> <tt>SLsmg_resume_smg, SLsmg_reset_smg</tt> </descrip><p> <sect><bf>SLsmg_resume_smg</bf><label id="SLsmg_resume_smg"><p><descrip> <tag> Synopsis </tag> Resume screen management <tag> Usage </tag> <tt>int SLsmg_resume_smg (void)</tt> <tag> Description </tag> <tt>SLsmg_resume_smg</tt> should be called after <tt>SLsmg_suspend_smg</tt> to redraw the display exactly like it was before <tt>SLsmg_suspend_smg</tt> was called. It returns zero upon success, or <tt>-1</tt> upon error. <tag> See Also </tag> <tt>SLsmg_suspend_smg</tt> </descrip><p> <sect><bf>SLsmg_erase_eol</bf><label id="SLsmg_erase_eol"><p><descrip> <tag> Synopsis </tag> Erase to the end of the row <tag> Usage </tag> <tt>void SLsmg_erase_eol (void);</tt> <tag> Description </tag> <tt>SLsmg_erase_eol</tt> erases all characters from the current position to the end of the line. The newly created space is given the color of the current color. This function has no effect on the position of the virtual cursor. <tag> See Also </tag> <tt>SLsmg_gotorc, SLsmg_erase_eos, SLsmg_fill_region</tt> </descrip><p> <sect><bf>SLsmg_gotorc</bf><label id="SLsmg_gotorc"><p><descrip> <tag> Synopsis </tag> Move the virtual cursor <tag> Usage </tag> <tt>void SLsmg_gotorc (int r, int c)</tt> <tag> Description </tag> The <tt>SLsmg_gotorc</tt> function moves the virtual cursor to the row <tt>r</tt> and column <tt>c</tt>. The first row and first column is specified by <tt>r = 0</tt> and <tt>c = 0</tt>. <tag> See Also </tag> <tt>SLsmg_refresh</tt> </descrip><p> <sect><bf>SLsmg_erase_eos</bf><label id="SLsmg_erase_eos"><p><descrip> <tag> Synopsis </tag> Erase to the end of the screen <tag> Usage </tag> <tt>void SLsmg_erase_eos (void);</tt> <tag> Description </tag> The <tt>SLsmg_erase_eos</tt> is like <tt>SLsmg_erase_eol</tt> except that it erases all text from the current position to the end of the display. The current color will be used to set the background of the erased area. <tag> See Also </tag> <tt>SLsmg_erase_eol</tt> </descrip><p> <sect><bf>SLsmg_reverse_video</bf><label id="SLsmg_reverse_video"><p><descrip> <tag> Synopsis </tag> Set the current color to 1 <tag> Usage </tag> <tt>void SLsmg_reverse_video (void);</tt> <tag> Description </tag> This function is nothing more than <tt>SLsmg_set_color(1)</tt>. <tag> See Also </tag> <tt>SLsmg_set_color</tt> </descrip><p> <sect><bf>SLsmg_set_color (int)</bf><label id="SLsmg_set_color (int)"><p><descrip> <tag> Synopsis </tag> Set the current color <tag> Usage </tag> <tt>void SLsmg_set_color (int c);</tt> <tag> Description </tag> <tt>SLsmg_set_color</tt> is used to set the current color. The parameter <tt>c</tt> is really a color object descriptor. Actual foreground and background colors as well as other visual attributes may be associated with a color descriptor via the <tt>SLtt_set_color</tt> function. <tag> Example </tag> This example defines color <tt>7</tt> to be green foreground on black background and then displays some text in this color: <tscreen><verb> SLtt_set_color (7, NULL, "green", "black"); SLsmg_set_color (7); SLsmg_write_string ("Hello"); SLsmg_refresh (); </verb></tscreen> <tag> Notes </tag> It is important to understand that the screen managment routines know nothing about the actual colors associated with a color descriptor. Only the descriptor itself is used by the <tt>SLsmg</tt> routines. The lower level <tt>SLtt</tt> interface converts the color descriptors to actual colors. Thus <tscreen><verb> SLtt_set_color (7, NULL, "green", "black"); SLsmg_set_color (7); SLsmg_write_string ("Hello"); SLtt_set_color (7, NULL, "red", "blue"); SLsmg_write_string ("World"); SLsmg_refresh (); </verb></tscreen> will result in <tt>"hello"</tt> displayed in red on blue and <em>not</em> green on black. <tag> See Also </tag> <tt>SLtt_set_color, SLtt_set_color_object</tt> </descrip><p> <sect><bf>SLsmg_normal_video</bf><label id="SLsmg_normal_video"><p><descrip> <tag> Synopsis </tag> Set the current color to 0 <tag> Usage </tag> <tt>void SLsmg_normal_video (void);</tt> <tag> Description </tag> <tt>SLsmg_normal_video</tt> sets the current color descriptor to <tt>0</tt>. <tag> See Also </tag> <tt>SLsmg_set_color</tt> </descrip><p> <sect><bf>SLsmg_printf</bf><label id="SLsmg_printf"><p><descrip> <tag> Synopsis </tag> Format a string on the virtual display <tag> Usage </tag> <tt>void SLsmg_printf (char *fmt, ...)</tt> <tag> Description </tag> <tt>SLsmg_printf</tt> format a <tt>printf</tt> style variable argument list and writes it on the virtual display. The virtual cursor will be moved to the end of the string. <tag> See Also </tag> <tt>SLsmg_write_string, SLsmg_vprintf</tt> </descrip><p> <sect><bf>SLsmg_vprintf</bf><label id="SLsmg_vprintf"><p><descrip> <tag> Synopsis </tag> Format a string on the virtual display <tag> Usage </tag> <tt>void SLsmg_vprintf (char *fmt, va_list ap)</tt> <tag> Description </tag> <tt>SLsmg_vprintf</tt> formats a string in the manner of <em>vprintf</em> and writes the result to the display. The virtual cursor is advanced to the end of the string. <tag> See Also </tag> <tt>SLsmg_write_string, SLsmg_printf</tt> </descrip><p> <sect><bf>SLsmg_write_string</bf><label id="SLsmg_write_string"><p><descrip> <tag> Synopsis </tag> Write a character string on the display <tag> Usage </tag> <tt>void SLsmg_write_string (char *s)</tt> <tag> Description </tag> The function <tt>SLsmg_write_string</tt> displays the string <tt>s</tt> on the virtual display at the current position and moves the position to the end of the string. <tag> See Also </tag> <tt>SLsmg_printf, SLsmg_write_nstring</tt> </descrip><p> <sect><bf>SLsmg_write_nstring</bf><label id="SLsmg_write_nstring"><p><descrip> <tag> Synopsis </tag> Write the first n characters of a string on the display <tag> Usage </tag> <tt>void SLsmg_write_nstring (char *s, unsigned int n);</tt> <tag> Description </tag> <tt>SLsmg_write_nstring</tt> writes the first <tt>n</tt> characters of <tt>s</tt> to this virtual display. If the length of the string <tt>s</tt> is less than <tt>n</tt>, the spaces will used until <tt>n</tt> characters have been written. <tt>s</tt> can be <tt>NULL</tt>, in which case <tt>n</tt> spaces will be written. <tag> See Also </tag> <tt>SLsmg_write_string, SLsmg_write_nchars</tt> </descrip><p> <sect><bf>SLsmg_write_char</bf><label id="SLsmg_write_char"><p><descrip> <tag> Synopsis </tag> Write a character to the virtual display <tag> Usage </tag> <tt>void SLsmg_write_char (char ch);</tt> <tag> Description </tag> <tt>SLsmg_write_char</tt> writes the character <tt>ch</tt> to the virtual display. <tag> See Also </tag> <tt>SLsmg_write_nchars, SLsmg_write_string</tt> </descrip><p> <sect><bf>SLsmg_write_nchars</bf><label id="SLsmg_write_nchars"><p><descrip> <tag> Synopsis </tag> Write n characters to the virtual display <tag> Usage </tag> <tt>void SLsmg_write_nchars (char *s, unsigned int n);</tt> <tag> Description </tag> <tt>SLsmg_write_nchars</tt> writes at most <tt>n</tt> characters from the string <tt>s</tt> to the display. If the length of <tt>s</tt> is less than <tt>n</tt>, the whole length of the string will get written. This function differs from <tt>SLsmg_write_nstring</tt> in that <tt>SLsmg_write_nstring</tt> will pad the string to write exactly <tt>n</tt> characters. <tt>SLsmg_write_nchars</tt> does not perform any padding. <tag> See Also </tag> <tt>SLsmg_write_nchars, SLsmg_write_nstring</tt> </descrip><p> <sect><bf>SLsmg_write_wrapped_string</bf><label id="SLsmg_write_wrapped_string"><p><descrip> <tag> Synopsis </tag> Write a string to the display with wrapping <tag> Usage </tag> <tt>void SLsmg_write_wrapped_string (s, r, c, nr, nc, fill)</tt> <tscreen><verb> char *s int r, c unsigned int nr, nc int fill </verb></tscreen> <tag> Description </tag> <tt>SLsmg_write_wrapped_string</tt> writes the string <tt>s</tt> to the virtual display. The string will be confined to the rectangular region whose upper right corner is at row <tt>r</tt> and column <tt>c</tt>, and consists of <tt>nr</tt> rows and <tt>nc</tt> columns. The string will be wrapped at the boundaries of the box. If <tt>fill</tt> is non-zero, the last line to which characters have been written will get padded with spaces. <tag> Notes </tag> This function does not wrap on word boundaries. However, it will wrap when a newline charater is encountered. <tag> See Also </tag> <tt>SLsmg_write_string</tt> </descrip><p> <sect><bf>SLsmg_cls</bf><label id="SLsmg_cls"><p><descrip> <tag> Synopsis </tag> Clear the virtual display <tag> Usage </tag> <tt>void SLsmg_cls (void)</tt> <tag> Description </tag> <tt>SLsmg_cls</tt> erases the virtual display using the current color. This will cause the physical display to get cleared the next time <tt>SLsmg_refresh</tt> is called. <tag> Notes </tag> This function is not the same as <tscreen><verb> SLsmg_gotorc (0,0); SLsmg_erase_eos (); </verb></tscreen> since these statements do not guarantee that the physical screen will get cleared. <tag> See Also </tag> <tt>SLsmg_refresh, SLsmg_erase_eos</tt> </descrip><p> <sect><bf>SLsmg_refresh</bf><label id="SLsmg_refresh"><p><descrip> <tag> Synopsis </tag> Update physical screen <tag> Usage </tag> <tt>void SLsmg_refresh (void)</tt> <tag> Description </tag> The <tt>SLsmg_refresh</tt> function updates the physical display to look like the virtual display. <tag> See Also </tag> <tt>SLsmg_suspend_smg, SLsmg_init_smg, SLsmg_reset_smg</tt> </descrip><p> <sect><bf>SLsmg_touch_lines</bf><label id="SLsmg_touch_lines"><p><descrip> <tag> Synopsis </tag> Mark lines on the virtual display for redisplay <tag> Usage </tag> <tt>void SLsmg_touch_lines (int r, unsigned int nr)</tt> <tag> Description </tag> <tt>SLsmg_touch_lines</tt> marks the <tt>nr</tt> lines on the virtual display starting at row <tt>r</tt> for redisplay upon the next call to <tt>SLsmg_refresh</tt>. <tag> Notes </tag> This function should rarely be called, if ever. If you find that you need to call this function, then your application should be modified to properly use the <tt>SLsmg</tt> screen management routines. This function is provided only for curses compatibility. <tag> See Also </tag> <tt>SLsmg_refresh</tt> </descrip><p> <sect><bf>SLsmg_init_smg</bf><label id="SLsmg_init_smg"><p><descrip> <tag> Synopsis </tag> Initialize the <tt>SLsmg</tt> routines <tag> Usage </tag> <tt>int SLsmg_init_smg (void)</tt> <tag> Description </tag> The <tt>SLsmg_init_smg</tt> function initializes the <tt>SLsmg</tt> screen management routines. Specifically, this function allocates space for the virtual display and calls <tt>SLtt_init_video</tt> to put the terminal's physical display in the proper state. It is up to the caller to make sure that the <tt>SLtt</tt> routines are initialized via <tt>SLtt_get_terminfo</tt> before calling <tt>SLsmg_init_smg</tt>. This function should also be called any time the size of the physical display has changed so that it can reallocate a new virtual display to match the physical display. It returns zero upon success, or <tt>-1</tt> upon failure. <tag> See Also </tag> <tt>SLsmg_reset_smg</tt> </descrip><p> <sect><bf>SLsmg_reset_smg</bf><label id="SLsmg_reset_smg"><p><descrip> <tag> Synopsis </tag> Reset the <tt>SLsmg</tt> routines <tag> Usage </tag> <tt>int SLsmg_reset_smg (void);</tt> <tag> Description </tag> <tt>SLsmg_reset_smg</tt> resets the <tt>SLsmg</tt> screen management routines by freeing all memory allocated while it was active. It also calls <tt>SLtt_reset_video</tt> to put the terminal's display in it default state. <tag> See Also </tag> <tt>SLsmg_init_smg</tt> </descrip><p> <sect><bf>SLsmg_char_at</bf><label id="SLsmg_char_at"><p><descrip> <tag> Synopsis </tag> Get the character at the current position on the virtual display <tag> Usage </tag> <tt>unsigned short SLsmg_char_at(void)</tt> <tag> Description </tag> The <tt>SLsmg_char_at</tt> function returns the character and its color at the current position on the virtual display. <tag> See Also </tag> <tt>SLsmg_read_raw, SLsmg_write_char</tt> </descrip><p> <sect><bf>SLsmg_set_screen_start</bf><label id="SLsmg_set_screen_start"><p><descrip> <tag> Synopsis </tag> Set the origin of the virtual display <tag> Usage </tag> <tt>void SLsmg_set_screen_start (int *r, int *c)</tt> <tag> Description </tag> <tt>SLsmg_set_screen_start</tt> sets the origin of the virtual display to the row <tt>*r</tt> and the column <tt>*c</tt>. If either <tt>r</tt> or <tt>c</tt> is <tt>NULL</tt>, then the corresponding value will be set to <tt>0</tt>. Otherwise, the location specified by the pointers will be updated to reflect the old origin. See <tt>slang/demo/pager.c</tt> for how this function may be used to scroll horizontally. <tag> See Also </tag> <tt>SLsmg_init_smg</tt> </descrip><p> <sect><bf>SLsmg_draw_hline</bf><label id="SLsmg_draw_hline"><p><descrip> <tag> Synopsis </tag> Draw a horizontal line <tag> Usage </tag> <tt>void SLsmg_draw_hline (unsigned int len)</tt> <tag> Description </tag> The <tt>SLsmg_draw_hline</tt> function draws a horizontal line of length <tt>len</tt> on the virtual display. The position of the virtual cursor is left at the end of the line. <tag> See Also </tag> <tt>SLsmg_draw_vline</tt> </descrip><p> <sect><bf>SLsmg_draw_vline</bf><label id="SLsmg_draw_vline"><p><descrip> <tag> Synopsis </tag> Draw a vertical line <tag> Usage </tag> <tt>void SLsmg_draw_vline (unsigned int len);</tt> <tag> Description </tag> The <tt>SLsmg_draw_vline</tt> function draws a vertical line of length <tt>len</tt> on the virtual display. The position of the virtual cursor is left at the end of the line. <tag> See Also </tag> <tt>??</tt> </descrip><p> <sect><bf>SLsmg_draw_object</bf><label id="SLsmg_draw_object"><p><descrip> <tag> Synopsis </tag> Draw an object from the alternate character set <tag> Usage </tag> <tt>void SLsmg_draw_object (int r, int c, unsigned char obj)</tt> <tag> Description </tag> The <tt>SLsmg_draw_object</tt> function may be used to place the object specified by <tt>obj</tt> at row <tt>r</tt> and column <tt>c</tt>. The object is really a character from the alternate character set and may be specified using one of the following constants: <tscreen><verb> SLSMG_HLINE_CHAR Horizontal line SLSMG_VLINE_CHAR Vertical line SLSMG_ULCORN_CHAR Upper left corner SLSMG_URCORN_CHAR Upper right corner SLSMG_LLCORN_CHAR Lower left corner SLSMG_LRCORN_CHAR Lower right corner SLSMG_CKBRD_CHAR Checkboard character SLSMG_RTEE_CHAR Right Tee SLSMG_LTEE_CHAR Left Tee SLSMG_UTEE_CHAR Up Tee SLSMG_DTEE_CHAR Down Tee SLSMG_PLUS_CHAR Plus or Cross character </verb></tscreen> <tag> See Also </tag> <tt>SLsmg_draw_vline, SLsmg_draw_hline, SLsmg_draw_box</tt> </descrip><p> <sect><bf>SLsmg_draw_box</bf><label id="SLsmg_draw_box"><p><descrip> <tag> Synopsis </tag> Draw a box on the virtual display <tag> Usage </tag> <tt>void SLsmg_draw_box (int r, int c, unsigned int dr, unsigned int dc)</tt> <tag> Description </tag> <tt>SLsmg_draw_box</tt> uses the <tt>SLsmg_draw_hline</tt> and <tt>SLsmg_draw_vline</tt> functions to draw a rectangular box on the virtual display. The box's upper left corner is placed at row <tt>r</tt> and column <tt>c</tt>. The width and length of the box is specified by <tt>dc</tt> and <tt>dr</tt>, respectively. <tag> See Also </tag> <tt>SLsmg_draw_vline, SLsmg_draw_hline, SLsmg_draw_object</tt> </descrip><p> <sect><bf>SLsmg_set_color_in_region</bf><label id="SLsmg_set_color_in_region"><p><descrip> <tag> Synopsis </tag> Change the color of a specifed region <tag> Usage </tag> <tt>void SLsmg_set_color_in_region (color, r, c, dr, dc)</tt> <tscreen><verb> int color; int r, c; unsigned int dr, dc; </verb></tscreen> <tag> Description </tag> <tt>SLsmg_set_color_in_region</tt> may be used to change the color of a rectangular region whose upper left corner is given by (<tt>r</tt>,<tt>c</tt>), and whose width and height is given by <tt>dc</tt> and <tt>dr</tt>, respectively. The color of the region is given by the <tt>color</tt> parameter. <tag> See Also </tag> <tt>SLsmg_draw_box, SLsmg_set_color</tt> </descrip><p> <sect><bf>SLsmg_get_column</bf><label id="SLsmg_get_column"><p><descrip> <tag> Synopsis </tag> Get the column of the virtual cursor <tag> Usage </tag> <tt>int SLsmg_get_column(void);</tt> <tag> Description </tag> The <tt>SLsmg_get_column</tt> function returns the current column of the virtual cursor on the virtual display. <tag> See Also </tag> <tt>SLsmg_get_row, SLsmg_gotorc</tt> </descrip><p> <sect><bf>SLsmg_get_row</bf><label id="SLsmg_get_row"><p><descrip> <tag> Synopsis </tag> Get the row of the virtual cursor <tag> Usage </tag> <tt>int SLsmg_get_row(void);</tt> <tag> Description </tag> The <tt>SLsmg_get_row</tt> function returns the current row of the virtual cursor on the virtual display. <tag> See Also </tag> <tt>SLsmg_get_column, SLsmg_gotorc</tt> </descrip><p> <sect><bf>SLsmg_forward</bf><label id="SLsmg_forward"><p><descrip> <tag> Synopsis </tag> Move the virtual cursor forward n columns <tag> Usage </tag> <tt>void SLsmg_forward (int n);</tt> <tag> Description </tag> The <tt>SLsmg_forward</tt> function moves the virtual cursor forward <tt>n</tt> columns. <tag> See Also </tag> <tt>SLsmg_gotorc</tt> </descrip><p> <sect><bf>SLsmg_write_color_chars</bf><label id="SLsmg_write_color_chars"><p><descrip> <tag> Synopsis </tag> Write characters with color descriptors to virtual display <tag> Usage </tag> <tt>void SLsmg_write_color_chars (unsigned short *s, unsigned int len)</tt> <tag> Description </tag> The <tt>SLsmg_write_color_chars</tt> function may be used to write <tt>len</tt> characters, each with a different color descriptor to the virtual display. Each character and its associated color are encoded as an <tt>unsigned short</tt> such that the lower eight bits form the character and the next eight bits form the color. <tag> See Also </tag> <tt>SLsmg_char_at, SLsmg_write_raw</tt> </descrip><p> <sect><bf>SLsmg_read_raw</bf><label id="SLsmg_read_raw"><p><descrip> <tag> Synopsis </tag> Read characters from the virtual display <tag> Usage </tag> <tt>unsigned int SLsmg_read_raw (unsigned short *buf, unsigned int len)</tt> <tag> Description </tag> <tt>SLsmg_read_raw</tt> attempts to read <tt>len</tt> characters from the current position on the virtual display into the buffer specified by <tt>buf</tt>. It returns the number of characters actually read. This number will be less than <tt>len</tt> if an attempt is made to read past the right margin of the display. <tag> Notes </tag> The purpose of the pair of functions, <tt>SLsmg_read_raw</tt> and <tt>SLsmg_write_raw</tt>, is to permit one to copy the contents of one region of the virtual display to another region. <tag> See Also </tag> <tt>SLsmg_char_at, SLsmg_write_raw</tt> </descrip><p> <sect><bf>SLsmg_write_raw</bf><label id="SLsmg_write_raw"><p><descrip> <tag> Synopsis </tag> Write characters directly to the virtual display <tag> Usage </tag> <tt>unsigned int SLsmg_write_raw (unsigned short *buf, unsigned int len)</tt> <tag> Description </tag> The <tt>SLsmg_write_raw</tt> function attempts to write <tt>len</tt> characters specified by <tt>buf</tt> to the display at the current position. It returns the number of characters successfully written, which will be less than <tt>len</tt> if an attempt is made to write past the right margin. <tag> Notes </tag> The purpose of the pair of functions, <tt>SLsmg_read_raw</tt> and <tt>SLsmg_write_raw</tt>, is to permit one to copy the contents of one region of the virtual display to another region. <tag> See Also </tag> <tt>SLsmg_read_raw</tt> </descrip><p> <sect><bf>SLallocate_load_type</bf><label id="SLallocate_load_type"><p><descrip> <tag> Synopsis </tag> Allocate a SLang_Load_Type object <tag> Usage </tag> <tt>SLang_Load_Type *SLallocate_load_type (char *name)</tt> <tag> Description </tag> The <tt>SLallocate_load_type</tt> function allocates and initializes space for a <tt>SLang_Load_Type</tt> object and returns it. Upon failure, the function returns <tt>NULL</tt>. The parameter <tt>name</tt> must uniquely identify the object. For example, if the object represents a file, then <tt>name</tt> could be the absolute path name of the file. <tag> See Also </tag> <tt>SLdeallocate_load_type, SLang_load_object</tt> </descrip><p> <sect><bf>SLdeallocate_load_type</bf><label id="SLdeallocate_load_type"><p><descrip> <tag> Synopsis </tag> Free a SLang_Load_Type object <tag> Usage </tag> <tt>void SLdeallocate_load_type (SLang_Load_Type *slt)</tt> <tag> Description </tag> This function frees the memory associated with a <tt>SLang_Load_Type</tt> object that was acquired from a call to the <tt>SLallocate_load_type</tt> function. <tag> See Also </tag> <tt>SLallocate_load_type, SLang_load_object</tt> </descrip><p> <sect><bf>SLang_load_object</bf><label id="SLang_load_object"><p><descrip> <tag> Synopsis </tag> Load an object into the interpreter <tag> Usage </tag> <tt>int SLang_load_object (SLang_Load_Type *obj)</tt> <tag> Description </tag> The function <tt>SLang_load_object</tt> is a generic function that may be used to loaded an object of type <tt>SLang_Load_Type</tt> into the interpreter. For example, the functions <tt>SLang_load_file</tt> and <tt>SLang_load_string</tt> are wrappers around this function to load a file and a string, respectively. <tag> See Also </tag> <tt>SLang_load_file, SLang_load_string, SLallocate_load_type</tt> </descrip><p> <sect><bf>SLclass_allocate_class</bf><label id="SLclass_allocate_class"><p><descrip> <tag> Synopsis </tag> Allocate a class for a new data type <tag> Usage </tag> <tt>SLang_Class_Type *SLclass_allocate_class (char *name)</tt> <tag> Description </tag> The purpose of this function is to allocate and initialize space that defines a new data type or class called <tt>name</tt>. If successful, a pointer to the class is returned, or upon failure the function returns <tt>NULL</tt>. This function does not automatically create the new data type. Callback functions must first be associated with the data type via functions such as <tt>SLclass_set_push_function</tt>, and the the data type must be registered with the interpreter via <tt>SLclass_register_class</tt>. See the <bf>S-lang</bf> library programmer's guide for more information. <tag> See Also </tag> <tt>SLclass_register_class, SLclass_set_push_function</tt> </descrip><p> <sect><bf>SLclass_register_class</bf><label id="SLclass_register_class"><p><descrip> <tag> Synopsis </tag> Register a new data type with the interpreter <tag> Usage </tag> <tt>int SLclass_register_class (cl, type, sizeof_type, class_type)</tt> <tscreen><verb> SLang_Class_Type *cl unsigned char type unsigned int sizeof_type unsigned char class_type </verb></tscreen> <tag> Description </tag> The <tt>SLclass_register_class</tt> function is used to register a new class or data type with the interpreter. If successful, the function returns <tt>0</tt>, or upon failure, it returns <tt>-1</tt>. The first parameter, <tt>cl</tt>, must have been previously obtained via the <tt>SLclass_allocate_class</tt> function. The second parameter, <tt>type</tt> specifies the data type of the new class. It must be an unsigned character with value greater that <tt>127</tt>. The values in the range <tt>0-127</tt> are reserved for internal use by the library. The size that the data type represents in bytes is specified by the third parameter, <tt>sizeof_type</tt>. This value should not be confused with the sizeof the structure that represents the data type, unless the data type is of class <tt>SLANG_CLASS_TYPE_VECTOR</tt> or <tt>SLANG_CLASS_TYPE_SCALAR</tt>. For pointer objects, the value of this parameter is just <tt>sizeof(void *)</tt>. The final parameter specifies the class type of the data type. It must be one of the values: <tscreen><verb> SLANG_CLASS_TYPE_SCALAR SLANG_CLASS_TYPE_VECTOR SLANG_CLASS_TYPE_PTR SLANG_CLASS_TYPE_MMT </verb></tscreen> The <tt>SLANG_CLASS_TYPE_SCALAR</tt> indicates that the new data type is a scalar. Examples of scalars in <tt>SLANG_INT_TYPE</tt> and <tt>SLANG_DOUBLE_TYPE</tt>. Setting <tt>class_type</tt> to SLANG_CLASS_TYPE_VECTOR implies that the new data type is a vector, or a 1-d array of scalar types. An example of a data type of this class is the <tt>SLANG_COMPLEX_TYPE</tt>, which represents complex numbers. <tt>SLANG_CLASS_TYPE_PTR</tt> specifies the data type is of a pointer type. Examples of data types of this class include <tt>SLANG_STRING_TYPE</tt> and <tt>SLANG_ARRAY_TYPE</tt>. Such types must provide for their own memory management. Data types of class <tt>SLANG_CLASS_TYPE_MMT</tt> are pointer types except that the memory management, i.e., creation and destruction of the type, is handled by the interpreter. Such a type is called a <em>memory managed type</em>. An example of this data type is the <tt>SLANG_FILEPTR_TYPE</tt>. <tag> Notes </tag> See the <em>S-Lang Library C Programmer's Guide</em> for more information. <tag> See Also </tag> <tt>SLclass_allocate_class</tt> </descrip><p> <sect><bf>SLclass_set_string_function</bf><label id="SLclass_set_string_function"><p><descrip> <tag> Synopsis </tag> Set a data type's string representation callback <tag> Usage </tag> <tt>int SLclass_set_string_function (cl, sfun)</tt> <tscreen><verb> SLang_Class_Type *cl char *(*sfun) (unsigned char, VOID_STAR); </verb></tscreen> <tag> Description </tag> The <tt>SLclass_set_string_function</tt> routine is used to define a callback function, <tt>sfun</tt>, that that will be used when a string representation of an object of the data type represented by <tt>cl</tt> is needed. <tt>cl</tt> must have already been obtained via a call to <tt>SLclass_allocate_class</tt>. When called, <tt>sfun</tt> will be passed two arguments: a unsigned char which represents the data type, and the address of the object for which a string represetation is required. The callback function must return a <em>malloced</em> string. Upon success, <tt>SLclass_set_string_function</tt> returns zero, or upon error it returns <tt>-1</tt>. <tag> Example </tag> A callback function that handles both <tt>SLANG_STRING_TYPE</tt> and <tt>SLANG_INT_TYPE</tt> variables looks like: <tscreen><verb> char *string_and_int_callback (unsigned char type, VOID_STAR addr) { char buf[64]; switch (type) { case SLANG_STRING_TYPE: return SLmake_string (*(char **)addr); case SLANG_INTEGER_TYPE: sprintf (buf, "%d", *(int *)addr); return SLmake_string (buf); } return NULL; } </verb></tscreen> <tag> Notes </tag> The default string callback simply returns the name of the data type. <tag> See Also </tag> <tt>SLclass_allocate_class, SLclass_register_class</tt> </descrip><p> <sect><bf>SLclass_set_destroy_function</bf><label id="SLclass_set_destroy_function"><p><descrip> <tag> Synopsis </tag> Set the destroy method callback for a data type <tag> Usage </tag> <tt>int SLclass_set_destroy_function (cl, destroy_fun)</tt> <tscreen><verb> SLang_Class_Type *cl void (*destroy_fun) (unsigned char, VOID_STAR); </verb></tscreen> <tag> Description </tag> <tt>SLclass_set_destroy_function</tt> is used to set the destroy callback for a data type. The data type's class <tt>cl</tt> must have been previously obtained via a call to <tt>SLclass_allocate_class</tt>. When called, <tt>destroy_fun</tt> will be passed two arguments: a unsigned char which represents the data type, and the address of the object to be destroyed. <tt>SLclass_set_destroy_function</tt> returns zero upon success, and <tt>-1</tt> upon failure. <tag> Example </tag> The destroy method for <tt>SLANG_STRING_TYPE</tt> looks like: <tscreen><verb> static void string_destroy (unsigned char type, VOID_STAR ptr) { char *s = *(char **) ptr; if (s != NULL) SLang_free_slstring (*(char **) s); } </verb></tscreen> <tag> Notes </tag> Data types of class SLANG_CLASS_TYPE_SCALAR do not require a destroy callback. However, other classes do. <tag> See Also </tag> <tt>SLclass_allocate_class, SLclass_register_class</tt> </descrip><p> <sect><bf>SLclass_set_push_function</bf><label id="SLclass_set_push_function"><p><descrip> <tag> Synopsis </tag> Set the push callback for a new data type <tag> Usage </tag> <tt>int SLclass_set_push_function (cl, push_fun)</tt> <tscreen><verb> SLang_Class_Type *cl int (*push_fun) (unsigned char, VOID_STAR); </verb></tscreen> <tag> Description </tag> <tt>SLclass_set_push_function</tt> is used to set the push callback for a new data type specified by <tt>cl</tt>, which must have been previously obtained via <tt>SLclass_allocate_class</tt>. The parameter <tt>push_fun</tt> is a pointer to the push callback. It is required to take two arguments: an unsigned character representing the data type, and the address of the object to be pushed. It must return zero upon success, or <tt>-1</tt> upon failure. <tt>SLclass_set_push_function</tt> returns zero upon success, or <tt>-1</tt> upon failure. <tag> Example </tag> The push callback for <tt>SLANG_COMPLEX_TYPE</tt> looks like: <tscreen><verb> static int complex_push (unsigned char type, VOID_STAR ptr) { double *z = *(double **) ptr; return SLang_push_complex (z[0], z[1]); } </verb></tscreen> <tag> See Also </tag> <tt>SLclass_allocate_class, SLclass_register_class</tt> </descrip><p> <sect><bf>SLclass_set_pop_function</bf><label id="SLclass_set_pop_function"><p><descrip> <tag> Synopsis </tag> Set the pop callback for a new data type <tag> Usage </tag> <tt>int SLclass_set_pop_function (cl, pop_fun)</tt> <tscreen><verb> SLang_Class_Type *cl int (*pop_fun) (unsigned char, VOID_STAR); </verb></tscreen> <tag> Description </tag> <tt>SLclass_set_pop_function</tt> is used to set the callback for popping an object from the stack for a new data type specified by <tt>cl</tt>, which must have been previously obtained via <tt>SLclass_allocate_class</tt>. The parameter <tt>pop_fun</tt> is a pointer to the pop callback function, which is required to take two arguments: an unsigned character representing the data type, and the address of the object to be popped. It must return zero upon success, or <tt>-1</tt> upon failure. <tt>SLclass_set_pop_function</tt> returns zero upon success, or <tt>-1</tt> upon failure. <tag> Example </tag> The pop callback for <tt>SLANG_COMPLEX_TYPE</tt> looks like: <tscreen><verb> static int complex_push (unsigned char type, VOID_STAR ptr) { double *z = *(double **) ptr; return SLang_pop_complex (&z[0], &z[1]); } </verb></tscreen> <tag> See Also </tag> <tt>SLclass_allocate_class, SLclass_register_class</tt> </descrip><p> <sect><bf>SLclass_get_datatype_name</bf><label id="SLclass_get_datatype_name"><p><descrip> <tag> Synopsis </tag> Get the name of a data type <tag> Usage </tag> <tt>char *SLclass_get_datatype_name (unsigned char type)</tt> <tag> Description </tag> The <tt>SLclass_get_datatype_name</tt> function returns the name of the data type specified by <tt>type</tt>. For example, if <tt>type</tt> is <tt>SLANG_INT_TYPE</tt>, the string <tt>"Integer_Type"</tt> will be returned. This function returns a pointer that should not be modified or freed. <tag> See Also </tag> <tt>SLclass_allocate_class, SLclass_register_class</tt> </descrip><p> <sect><bf>SLang_free_mmt</bf><label id="SLang_free_mmt"><p><descrip> <tag> Synopsis </tag> Free a memory managed type <tag> Usage </tag> <tt>void SLang_free_mmt (SLang_MMT_Type *mmt)</tt> <tag> Description </tag> The <tt>SLang_MMT_Type</tt> function is used to free a memory managed data type. <tag> See Also </tag> <tt>SLang_object_from_mmt, SLang_create_mmt</tt> </descrip><p> <sect><bf>SLang_object_from_mmt</bf><label id="SLang_object_from_mmt"><p><descrip> <tag> Synopsis </tag> Get a pointer to the value of a memory managed type <tag> Usage </tag> <tt>VOID_STAR SLang_object_from_mmt (SLang_MMT_Type *mmt)</tt> <tag> Description </tag> The <tt>SLang_object_from_mmt</tt> function returns a pointer the the actually object whose memory is being managed by the interpreter. <tag> See Also </tag> <tt>SLang_free_mmt, SLang_create_mmt</tt> </descrip><p> <sect><bf>SLang_create_mmt</bf><label id="SLang_create_mmt"><p><descrip> <tag> Synopsis </tag> Create a memory managed data type <tag> Usage </tag> <tt>SLang_MMT_Type *SLang_create_mmt (unsigned char t, VOID_STAR ptr)</tt> <tag> Description </tag> The <tt>SLang_create_mmt</tt> function returns a pointer to a new memory managed object. This object contains information necessary to manage the memory associated with the pointer <tt>ptr</tt> which represents the application defined data type of type <tt>t</tt>. <tag> See Also </tag> <tt>SLang_object_from_mmt, SLang_push_mmt, SLang_free_mmt</tt> </descrip><p> <sect><bf>SLang_push_mmt</bf><label id="SLang_push_mmt"><p><descrip> <tag> Synopsis </tag> Push a memory managed type <tag> Usage </tag> <tt>int SLang_push_mmt (SLang_MMT_Type *mmt)</tt> <tag> Description </tag> This function is used to push a memory managed type onto the interpreter stack. It returns zero upon success, or <tt>-1</tt> upon failure. <tag> See Also </tag> <tt>SLang_create_mmt, SLang_pop_mmt</tt> </descrip><p> <sect><bf>SLang_pop_mmt</bf><label id="SLang_pop_mmt"><p><descrip> <tag> Synopsis </tag> Pop a memory managed data type <tag> Usage </tag> <tt>SLang_MMT_Type *SLang_pop_mmt (unsigned char t)</tt> <tag> Description </tag> The <tt>SLang_pop_mmt</tt> function may be used to pop a memory managed type of type <tt>t</tt> from the stack. It returns a pointer to the memory managed object upon success, or <tt>NULL</tt> upon failure. The function <tt>SLang_object_from_mmt</tt> should be used to access the actual pointer to the data type. <tag> See Also </tag> <tt>SLang_object_from_mmt, SLang_push_mmt</tt> </descrip><p> <sect><bf>SLang_inc_mmt</bf><label id="SLang_inc_mmt"><p><descrip> <tag> Synopsis </tag> Increment a memory managed type reference count <tag> Usage </tag> <tt>void SLang_inc_mmt (SLang_MMT_Type *mmt);</tt> <tag> Description </tag> The <tt>SLang_inc_mmt</tt> function may be used to increment the reference count associated with the memory managed data type given by <tt>mmt</tt>. <tag> See Also </tag> <tt>SLang_free_mmt, SLang_create_mmt, SLang_pop_mmt, SLang_pop_mmt</tt> </descrip><p> <sect><bf>SLang_vmessage</bf><label id="SLang_vmessage"><p><descrip> <tag> Synopsis </tag> Display a message to the message device <tag> Usage </tag> <tt>void SLang_vmessage (char *fmt, ...)</tt> <tag> Description </tag> This function prints a <tt>printf</tt> style formatted variable argument list to the message device. The default message device is <tt>stdout</tt>. <tag> See Also </tag> <tt>SLang_verror</tt> </descrip><p> <sect><bf>SLang_exit_error</bf><label id="SLang_exit_error"><p><descrip> <tag> Synopsis </tag> Exit the program and display an error message <tag> Usage </tag> <tt>void SLang_exit_error (char *fmt, ...)</tt> <tag> Description </tag> The <tt>SLang_exit_error</tt> function terminates the program and displays an error message using a <tt>printf</tt> type variable argument list. The default behavior to this function is to write the message to <tt>stderr</tt> and exit with the <tt>exit</tt> system call. If the the function pointer <tt>SLang_Exit_Error_Hook</tt> is non-NULL, the function to which it points will be called. This permits an application to perform whatever cleanup is necessary. This hook has the prototype: <tscreen><verb> void (*SLang_Exit_Error_Hook)(char *, va_list); </verb></tscreen> <tag> See Also </tag> <tt>SLang_verror, exit</tt> </descrip><p> <sect><bf>SLang_init_slang</bf><label id="SLang_init_slang"><p><descrip> <tag> Synopsis </tag> Initialize the interpreter <tag> Usage </tag> <tt>int SLang_init_slang (void)</tt> <tag> Description </tag> The <tt>SLang_init_slang</tt> function must be called by all applications that use the <bf>S-lang</bf> interpreter. It initializes the interpreter, defines the built-in data types, and adds a set of core intrinsic functions. The function returns <tt>0</tt> upon success, or <tt>-1</tt> upon failure. <tag> See Also </tag> <tt>SLang_init_slfile, SLang_init_slmath, SLang_init_slunix</tt> </descrip><p> <sect><bf>SLang_init_slfile</bf><label id="SLang_init_slfile"><p><descrip> <tag> Synopsis </tag> Initialize the interpreter file I/O intrinsics <tag> Usage </tag> <tt>int SLang_init_slfile (void)</tt> <tag> Description </tag> This function initializes the interpreters file I/O intrinsic functions. This function adds intrinsic functions such as <tt>fopen</tt>, <tt>fclose</tt>, and <tt>fputs</tt> to the interpreter. It returns <tt>0</tt> if successful, or <tt>-1</tt> upon error. <tag> Notes </tag> Before this function can be called, it is first necessary to call <tt>SLang_init_slang</tt>. It also adds the preprocessor symbol <tt>__SLFILE__</tt> to the interpreter. <tag> See Also </tag> <tt>SLang_init_slang, SLang_init_slunix, SLang_init_slmath</tt> </descrip><p> <sect><bf>SLang_init_slmath</bf><label id="SLang_init_slmath"><p><descrip> <tag> Synopsis </tag> Initialize the interpreter math intrinsics <tag> Usage </tag> <tt>int SLang_init_slmath (void)</tt> <tag> Description </tag> The <tt>SLang_init_slmath</tt> function initializes the interpreter's mathematical intrinsic functions and makes them available to the language. The intrinsic functions include <tt>sin</tt>, <tt>cos</tt>, <tt>tan</tt>, etc... It returns <tt>0</tt> if successful, or <tt>-1</tt> upon failure. <tag> Notes </tag> This function must be called after <tt>SLang_init_slang</tt>. It adds the preprocessor symbol <tt>__SLMATH__</tt> to the interpreter. <tag> See Also </tag> <tt>SLang_init_slang, SLang_init_slfile, SLang_init_slunix</tt> </descrip><p> <sect><bf>SLang_init_slunix</bf><label id="SLang_init_slunix"><p><descrip> <tag> Synopsis </tag> Make available some unix system calls to the interpreter <tag> Usage </tag> <tt>int SLang_init_slunix (void)</tt> <tag> Description </tag> The <tt>SLang_init_slunix</tt> function initializes the interpreter's unix system call intrinsic functions and makes them available to the language. Examples of functions made available by <tt>SLang_init_slunix</tt> include <tt>chmod</tt>, <tt>chown</tt>, and <tt>stat_file</tt>. It returns <tt>0</tt> if successful, or <tt>-1</tt> upon failure. <tag> Notes </tag> This function must be called after <tt>SLang_init_slang</tt>. It adds the preprocessor symbol <tt>__SLUNIX__</tt> to the interpreter. <tag> See Also </tag> <tt>SLang_init_slang, SLang_init_slfile, SLang_init_slmath</tt> </descrip><p> <sect><bf>SLadd_intrin_fun_table</bf><label id="SLadd_intrin_fun_table"><p><descrip> <tag> Synopsis </tag> Add a table of intrinsic functions to the interpreter <tag> Usage </tag> <tt>int SLadd_intrin_fun_table(SLang_Intrin_Fun_Type *tbl, char *pp_name);</tt> <tag> Description </tag> The <tt>SLadd_intrin_fun_table</tt> function adds an array, or table, of <tt>SLang_Intrin_Fun_Type</tt> objects to the interpreter. The first parameter, <tt>tbl</tt> specifies the table to be added. The second parameter <tt>pp_name</tt>, if non-NULL will be added to the list of preprocessor symbols. This function returns <tt>-1</tt> upon failure or zero upon success. <tag> Notes </tag> A table should only be loaded one time and it is considered to be an error on the part of the application if it loads a table more than once. <tag> See Also </tag> <tt>SLadd_intrin_var_table, SLadd_intrinsic_function, SLdefine_for_ifdef</tt> </descrip><p> <sect><bf>SLadd_intrin_var_table</bf><label id="SLadd_intrin_var_table"><p><descrip> <tag> Synopsis </tag> Add a table of intrinsic variables to the interpreter <tag> Usage </tag> <tt>int SLadd_intrin_var_table (SLang_Intrin_Var_Type *tbl, char *pp_name);</tt> <tag> Description </tag> The <tt>SLadd_intrin_var_table</tt> function adds an array, or table, of <tt>SLang_Intrin_Var_Type</tt> objects to the interpreter. The first parameter, <tt>tbl</tt> specifies the table to be added. The second parameter <tt>pp_name</tt>, if non-NULL will be added to the list of preprocessor symbols. This function returns <tt>-1</tt> upon failure or zero upon success. <tag> Notes </tag> A table should only be loaded one time and it is considered to be an error on the part of the application if it loads a table more than once. <tag> See Also </tag> <tt>SLadd_intrin_var_table, SLadd_intrinsic_function, SLdefine_for_ifdef</tt> </descrip><p> <sect><bf>SLang_load_file</bf><label id="SLang_load_file"><p><descrip> <tag> Synopsis </tag> Load a file into the interpreter <tag> Usage </tag> <tt>int SLang_load_file (char *fn)</tt> <tag> Description </tag> The <tt>SLang_load_file</tt> function opens the file whose name is specified by <tt>fn</tt> and feeds it to the interpreter, line by line, for execution. If <tt>fn</tt> is <tt>NULL</tt>, the function will take input from <tt>stdin</tt>. If no error occurs, it returns <tt>0</tt>; otherwise, it returns <tt>-1</tt>, and sets <tt>SLang_Error</tt> accordingly. For example, if it fails to open the file, it will return <tt>-1</tt> with <tt>SLang_Error</tt> set to <tt>SL_OBJ_NOPEN</tt>. <tag> Notes </tag> If the hook <tt>SLang_Load_File_Hook</tt> declared as <tscreen><verb> int (*SLang_Load_File_Hook)(char *); </verb></tscreen> is non-NULL, the function point to by it will be used to load the file. For example, the <bf>jed</bf> editor uses this hook to load files via its own routines. <tag> See Also </tag> <tt>SLang_load_object, SLang_load_string</tt> </descrip><p> <sect><bf>SLang_restart</bf><label id="SLang_restart"><p><descrip> <tag> Synopsis </tag> Reset the interpreter after an error <tag> Usage </tag> <tt>void SLang_restart (int full)</tt> <tag> Description </tag> The <tt>SLang_restart</tt> function should be called by the application at top level if an error occurs. If the parameter <tt>full</tt> is non-zero, any objects on the <bf>S-lang</bf> run time stack will be removed from the stack; otherwise, the stack will be left intact. Any time the stack is believed to be trashed, this routine should be called with a non-zero argument (e.g., if <tt>setjmp</tt>/<tt>longjmp</tt> is called). Calling <tt>SLang_restart</tt> does not reset the global variable <tt>SLang_Error</tt> to zero. It is up to the application to reset that variable to zero after calling <tt>SLang_restart</tt>. <tag> Example </tag> <tscreen><verb> while (1) { if (SLang_Error) { SLang_restart (1); SLang_Error = 0; } (void) SLang_load_file (NULL); } </verb></tscreen> <tag> See Also </tag> <tt>SLang_init_slang, SLang_load_file</tt> </descrip><p> <sect><bf>SLang_byte_compile_file</bf><label id="SLang_byte_compile_file"><p><descrip> <tag> Synopsis </tag> Byte-compile a file for faster loading <tag> Usage </tag> <tt>int SLang_byte_compile_file(char *fn, int reserved)</tt> <tag> Description </tag> The <tt>SLang_byte_compile_file</tt> function ``byte-compiles'' the file <tt>fn</tt> for faster loading by the interpreter. This produces a new file whose filename is equivalent to the one specified by <tt>fn</tt>, except that a <tt>'c'</tt> is appended to the name. For example, if <tt>fn</tt> is set to <tt>init.sl</tt>, then the new file will have the name exmp{init.slc}. The meaning of the second parameter, <tt>reserved</tt>, is reserved for future use. For now, set it to <tt>0</tt>. The function returns zero upon success, or <tt>-1</tt> upon error and sets SLang_Error accordingly. <tag> See Also </tag> <tt>SLang_load_file, SLang_init_slang</tt> </descrip><p> <sect><bf>SLang_autoload</bf><label id="SLang_autoload"><p><descrip> <tag> Synopsis </tag> Autoload a function from a file <tag> Usage </tag> <tt>int SLang_autoload(char *funct, char *filename)</tt> <tag> Description </tag> The <tt>SLang_autoload</tt> function may be used to associate a <tt>slang</tt> function name <tt>funct</tt> with the file <tt>filename</tt> such that if <tt>funct</tt> has not already been defined when needed, it will be loaded from <tt>filename</tt>. <tt>SLang_autoload</tt> has no effect if <tt>funct</tt> has already been defined. Otherwise it declares <tt>funct</tt> as a user-defined <bf>S-lang</bf> function. It returns <tt>0</tt> upon success, or <tt>-1</tt> upon error. <tag> See Also </tag> <tt>SLang_load_file, SLang_is_defined</tt> </descrip><p> <sect><bf>SLang_load_string</bf><label id="SLang_load_string"><p><descrip> <tag> Synopsis </tag> Interpret a string <tag> Usage </tag> <tt>int SLang_load_string(char *str)</tt> <tag> Description </tag> The <tt>SLang_load_string</tt> function feeds the string specified by <tt>str</tt> to the interpreter for execution. It returns zero upon success, or <tt>-1</tt> upon failure. <tag> See Also </tag> <tt>SLang_load_file, SLang_load_object</tt> </descrip><p> <sect><bf>SLdo_pop</bf><label id="SLdo_pop"><p><descrip> <tag> Synopsis </tag> Delete an object from the stack <tag> Usage </tag> <tt>int SLdo_pop(void)</tt> <tag> Description </tag> This function removes an object from the top of the interpeter's run-time stack and frees any memory associated with it. It returns zero upon success, or <tt>-1</tt> upon error (most likely due to a stack-underflow). <tag> See Also </tag> <tt>SLdo_pop_n, SLang_pop_integer, SLang_pop_string</tt> </descrip><p> <sect><bf>SLdo_pop_n</bf><label id="SLdo_pop_n"><p><descrip> <tag> Synopsis </tag> Delete n objects from the stack <tag> Usage </tag> <tt>int SLdo_pop_n (unsigned int n)</tt> <tag> Description </tag> The <tt>SLdo_pop_n</tt> function removes the top <tt>n</tt> objects from the interpreter's run-time stack and frees all memory associated with the objects. It returns zero upon success, or <tt>-1</tt> upon error (most likely due to a stack-underflow). <tag> See Also </tag> <tt>SLdo_pop, SLang_pop_integer, SLang_pop_string</tt> </descrip><p> <sect><bf>SLang_pop_integer</bf><label id="SLang_pop_integer"><p><descrip> <tag> Synopsis </tag> Pop an integer off the stack <tag> Usage </tag> <tt>int SLang_pop_integer (int *i)</tt> <tag> Description </tag> The <tt>SLang_pop_integer</tt> function removes an integer from the top of the interpreter's run-time stack and returns its value via the pointer <tt>i</tt>. If successful, it returns zero. However, if the top stack item is not of type <tt>SLANG_INT_TYPE</tt>, or the stack is empty, the function will return <tt>-1</tt> and set <tt>SLang_Error</tt> accordingly. <tag> See Also </tag> <tt>SLang_push_integer, SLang_pop_double</tt> </descrip><p> <sect><bf>SLpop_string</bf><label id="SLpop_string"><p><descrip> <tag> Synopsis </tag> Pop a string from the stack <tag> Usage </tag> <tt>int SLpop_string (char **strptr);</tt> <tag> Description </tag> The <tt>SLpop_string</tt> function pops a string from the stack and returns it as a malloced pointer. It is up to the calling routine to free this string via a call to <tt>free</tt> or <tt>SLfree</tt>. If successful, <tt>SLpop_string</tt> returns zero. However, if the top stack item is not of type <tt>SLANG_STRING_TYPE</tt>, or the stack is empty, the function will return <tt>-1</tt> and set <tt>SLang_Error</tt> accordingly. <tag> Example </tag> <tscreen><verb> define print_string (void) { char *s; if (-1 == SLpop_string (&s)) return; fputs (s, stdout); SLfree (s); } </verb></tscreen> <tag> Notes </tag> This function should not be confused with <tt>SLang_pop_slstring</tt>, which pops a <em>hashed</em> string from the stack. <tag> See Also </tag> <tt>SLang_pop_slstring. SLfree</tt> </descrip><p> <sect><bf>SLang_pop_string</bf><label id="SLang_pop_string"><p><descrip> <tag> Synopsis </tag> Pop a string from the stack <tag> Usage </tag> <tt>int SLang_pop_string(char **strptr, int *do_free)</tt> <tag> Description </tag> The <tt>SLpop_string</tt> function pops a string from the stack and returns it as a malloced pointer via <tt>strptr</tt>. After the function returns, the integer pointed to by the second parameter will be set to a non-zero value if <tt>*strptr</tt> should be freed via <tt>free</tt> or <tt>SLfree</tt>. If successful, <tt>SLpop_string</tt> returns zero. However, if the top stack item is not of type <tt>SLANG_STRING_TYPE</tt>, or the stack is empty, the function will return <tt>-1</tt> and set <tt>SLang_Error</tt> accordingly. <tag> Notes </tag> This function is considered obsolete and should not be used by applications. If one requires a malloced string for modification, <tt>SLpop_string</tt> should be used. If one requires a constant string that will not be modifed by the application, <tt>SLang_pop_slstring</tt> should be used. <tag> See Also </tag> <tt>SLang_pop_slstring, SLpop_string</tt> </descrip><p> <sect><bf>SLang_pop_slstring</bf><label id="SLang_pop_slstring"><p><descrip> <tag> Synopsis </tag> Pop a hashed string from the stack <tag> Usage </tag> <tt>int SLang_pop_slstring (char **s_ptr)</tt> <tag> Description </tag> The <tt>SLang_pop_slstring</tt> function pops a hashed string from the <bf>S-lang</bf> run-time stack and returns it via <tt>s_ptr</tt>. It returns zero if successful, or <tt>-1</tt> upon failure. The resulting string should be freed via a call to <tt>SLang_free_slstring</tt> after use. <tag> Example </tag> <tscreen><verb> void print_string (void) { char *s; if (-1 == SLang_pop_slstring (&s)) return; fprintf (stdout, "%s\n", s); SLang_free_slstring (s); } </verb></tscreen> <tag> Notes </tag> <tt>SLang_free_slstring</tt> is the preferred function for popping strings. This is a result of the fact that the interpreter uses hashed strings as the native representation for string data. One must <em>never</em> free a hashed string using <tt>free</tt> or <tt>SLfree</tt>. In addition, one must never make any attempt to modify a hashed string and doing so will result in memory corruption. <tag> See Also </tag> <tt>SLang_free_slstring, SLpop_string</tt> </descrip><p> <sect><bf>SLang_pop_double</bf><label id="SLang_pop_double"><p><descrip> <tag> Synopsis </tag> Pop a double from the stack <tag> Usage </tag> <tt>int SLang_pop_double (double *dptr, int *iptr, int *conv)</tt> <tag> Description </tag> The <tt>SLang_pop_double</tt> function pops a double precision number from the stack and returns it via <tt>dptr</tt>. If the number was derived from an integer, <tt>*conv</tt> will be set to <tt>1</tt> upon return, otherwise, <tt>*conv</tt> will be set to <tt>0</tt>. This function returns <tt>0</tt> upon success, otherwise it returns <tt>-1</tt> and sets <tt>SLang_Error</tt> accordingly. <tag> Notes </tag> If one does not care whether or not <tt>*dptr</tt> was derived from an integer, <tt>iptr</tt> and <tt>conv</tt> may be passed as <tt>NULL</tt> pointers. <tag> See Also </tag> <tt>SLang_pop_integer, SLang_push_double</tt> </descrip><p> <sect><bf>SLang_pop_complex</bf><label id="SLang_pop_complex"><p><descrip> <tag> Synopsis </tag> Pop a complex number from the stack <tag> Usage </tag> <tt>int SLang_pop_complex (double *re, double *im)</tt> <tag> Description </tag> <tt>SLang_pop_complex</tt> pops a complex number from the stack and returns it via the parameters <tt>re</tt> and <tt>im</tt> as the real and imaginary parts of the complex number, respectively. This function automatically converts objects of type <tt>SLANG_DOUBLE_TYPE</tt> and <tt>SLANG_INT_TYPE</tt> to <tt>SLANG_COMPLEX_TYPE</tt>, if necessary. It returns zero upon sucess, or <tt>-1</tt> upon error setting <tt>SLang_Error</tt> accordingly. <tag> See Also </tag> <tt>SLang_pop_integer, SLang_pop_double, SLang_push_complex</tt> </descrip><p> <sect><bf>SLang_push_complex</bf><label id="SLang_push_complex"><p><descrip> <tag> Synopsis </tag> Push a complex number onto the stack <tag> Usage </tag> <tt>int SLang_push_complex (double re, double im)</tt> <tag> Description </tag> <tt>SLang_push_complex</tt> may be used to push the complex number whose real and imaginary parts are given by <tt>re</tt> and <tt>im</tt>, respectively. It returns zero upon sucess, or <tt>-1</tt> upon error setting <tt>SLang_Error</tt> accordingly. <tag> See Also </tag> <tt>SLang_pop_complex, SLang_push_double</tt> </descrip><p> <sect><bf>SLang_push_double</bf><label id="SLang_push_double"><p><descrip> <tag> Synopsis </tag> Push a double onto the stack <tag> Usage </tag> <tt>int SLang_push_double(double d)</tt> <tag> Description </tag> <tt>SLang_push_double</tt> may be used to push the double precision floating point number <tt>d</tt> onto the interpreter's run-time stack. It returns zero upon success, or <tt>-1</tt> upon error setting <tt>SLang_Error</tt> accordingly. <tag> See Also </tag> <tt>SLang_pop_double, SLang_push_integer</tt> </descrip><p> <sect><bf>SLang_push_string</bf><label id="SLang_push_string"><p><descrip> <tag> Synopsis </tag> Push a string onto the stack <tag> Usage </tag> <tt>int SLang_push_string (char *s)</tt> <tag> Description </tag> <tt>SLang_push_string</tt> pushes a copy of the string specified by <tt>s</tt> onto the interpreter's run-time stack. It returns zero upon success, or <tt>-1</tt> upon error setting <tt>SLang_Error</tt> accordingly. <tag> Notes </tag> If <tt>s</tt> is <tt>NULL</tt>, this function pushes <tt>NULL</tt> (<tt>SLANG_NULL_TYPE</tt>) onto the stack. <tag> See Also </tag> <tt>SLang_push_malloced_string</tt> </descrip><p> <sect><bf>SLang_push_integer</bf><label id="SLang_push_integer"><p><descrip> <tag> Synopsis </tag> Push an integer onto the stack <tag> Usage </tag> <tt>int SLang_push_integer (int i)</tt> <tag> Description </tag> <tt>SLang_push_integer</tt> the integer <tt>i</tt> onto the interpreter's run-time stack. It returns zero upon success, or <tt>-1</tt> upon error setting <tt>SLang_Error</tt> accordingly. <tag> See Also </tag> <tt>SLang_pop_integer, SLang_push_double, SLang_push_string</tt> </descrip><p> <sect><bf>SLang_push_malloced_string</bf><label id="SLang_push_malloced_string"><p><descrip> <tag> Synopsis </tag> Push a malloced string onto the stack <tag> Usage </tag> <tt>int SLang_push_malloced_string (char *s);</tt> <tag> Description </tag> <tt>SLang_push_malloced_string</tt> may be used to push a malloced string onto the interpreter's run-time stack. It returns zero upon success, or <tt>-1</tt> upon error setting <tt>SLang_Error</tt> accordingly. <tag> Example </tag> The following example illustrates that it is up to the calling routine to free the string if <tt>SLang_push_malloced_string</tt> fails: <tscreen><verb> int push_hello (void) { char *s = malloc (6); if (s == NULL) return -1; strcpy (s, "hello"); if (-1 == SLang_push_malloced_string (s)) { free (s); return -1; } return 0; } </verb></tscreen> <tag> Example </tag> The function <tt>SLang_create_slstring</tt> returns a hashed string. Such a string may not be malloced and should not be passed to <tt>SLang_push_malloced_string</tt>. <tag> Notes </tag> If <tt>s</tt> is <tt>NULL</tt>, this function pushes <tt>NULL</tt> (<tt>SLANG_NULL_TYPE</tt>) onto the stack. <tag> See Also </tag> <tt>SLang_push_string, SLmake_string</tt> </descrip><p> <sect><bf>SLang_is_defined</bf><label id="SLang_is_defined"><p><descrip> <tag> Synopsis </tag> Check to see if the interpreter defines an object <tag> Usage </tag> <tt>int SLang_is_defined (char *nm)</tt> <tag> Description </tag> The <tt>SLang_is_defined</tt> function may be used to determine whether or not a variable or function whose name is given by <tt>em</tt> has been defined. It returns zero if no such object has been defined. Othewise it returns a non-zero value whose meaning is given by the following table: <tscreen><verb> 1 intrinsic function (SLANG_INTRINSIC) 2 user-defined slang function (SLANG_FUNCTION) -1 intrinsic variable (SLANG_IVARIABLE) -2 user-defined global variable (SLANG_GVARIABLE) </verb></tscreen> <tag> See Also </tag> <tt>SLadd_intrinsic_function, SLang_run_hooks, SLang_execute_function</tt> </descrip><p> <sect><bf>SLang_run_hooks</bf><label id="SLang_run_hooks"><p><descrip> <tag> Synopsis </tag> Run a user-defined hook with arguments <tag> Usage </tag> <tt>int SLang_run_hooks (char *fname, unsigned int n, ...)</tt> <tag> Description </tag> The <tt>SLang_run_hooks</tt> function may be used to execute a user-defined function named <tt>fname</tt>. Before execution of the function, the <tt>n</tt> string arguments specified by the variable parameter list are pushed onto the stack. If the function <tt>fname</tt> does not exist, <tt>SLang_run_hooks</tt> returns zero; otherwise, it returns <tt>1</tt> upon successful execution of the function, or <tt>-1</tt> if an error occurred. <tag> Example </tag> The <bf>jed</bf> editor uses <tt>SLang_run_hooks</tt> to setup the mode of a buffer based on the filename extension of the file associated with the buffer: <tscreen><verb> char *ext = get_filename_extension (filename); if (ext == NULL) return -1; if (-1 == SLang_run_hooks ("mode_hook", 1, ext)) return -1; return 0; </verb></tscreen> <tag> See Also </tag> <tt>SLang_is_defined, SLang_execute_function</tt> </descrip><p> <sect><bf>SLang_execute_function</bf><label id="SLang_execute_function"><p><descrip> <tag> Synopsis </tag> Execute a user or intrinsic function <tag> Usage </tag> <tt>int SLang_execute_function (char *fname)</tt> <tag> Description </tag> This function may be used to execute either a user-defined function or an intrinisic function. The name of the function is specified by <tt>fname</tt>. It returns zero if <tt>fname</tt> is not defined, or <tt>1</tt> if the function was successfully executed, or <tt>-1</tt> upon error. <tag> Notes </tag> The function <tt>SLexecute_function</tt> may be a better alternative for some uses. <tag> See Also </tag> <tt>SLang_run_hooks, SLexecute_function, SLang_is_defined</tt> </descrip><p> <sect><bf>SLang_verror</bf><label id="SLang_verror"><p><descrip> <tag> Synopsis </tag> Signal an error with a message <tag> Usage </tag> <tt>void SLang_verror (int code, char *fmt, ...);</tt> <tag> Description </tag> The <tt>SLang_verror</tt> function sets <tt>SLang_Error</tt> to <tt>code</tt> if <tt>SLang_Error</tt> is 0. It also displays the error message implied by the <tt>printf</tt> variable argument list using <tt>fmt</tt> as the format. <tag> Example </tag> <tscreen><verb> FILE *open_file (char *file) { char *file = "my_file.dat"; if (NULL == (fp = fopen (file, "w"))) SLang_verror (SL_INTRINSIC_ERROR, "Unable to open %s", file); return fp; } </verb></tscreen> <tag> See Also </tag> <tt>SLang_vmessage, SLang_exit_error</tt> </descrip><p> <sect><bf>SLang_doerror</bf><label id="SLang_doerror"><p><descrip> <tag> Synopsis </tag> Signal an error <tag> Usage </tag> <tt>void SLang_doerror (char *err_str)</tt> <tag> Description </tag> The <tt>SLang_doerror</tt> function displays the string <tt>err_str</tt> to the error device and signals a <bf>S-lang</bf> error. <tag> Notes </tag> <tt>SLang_doerror</tt> is considered to obsolete. Applications should use the <tt>SLang_verror</tt> function instead. <tag> See Also </tag> <tt>SLang_verror, SLang_exit_error</tt> </descrip><p> <sect><bf>SLang_get_function</bf><label id="SLang_get_function"><p><descrip> <tag> Synopsis </tag> Get a pointer to a <bf>S-lang</bf> function <tag> Usage </tag> <tt>SLang_Name_Type *SLang_get_function (char *fname)</tt> <tag> Description </tag> This function returns a pointer to the internal <bf>S-lang</bf> table entry of a function whose name is given by <tt>fname</tt>. It returns <tt>NULL</tt> upon failure. The value returned by this function can be used used <tt>SLexecute_function</tt> to call the function directly from C. <tag> See Also </tag> <tt>SLexecute_function</tt> </descrip><p> <sect><bf>SLexecute_function</bf><label id="SLexecute_function"><p><descrip> <tag> Synopsis </tag> Execute a <bf>S-lang</bf> or intrinsic function <tag> Usage </tag> <tt>int SLexecute_function (SLang_Name_Type *nt)</tt> <tag> Description </tag> The <tt>SLexecute_function</tt> allows an application to call the <bf>S-lang</bf> function specified by the <tt>SLang_Name_Type</tt> pointer <tt>nt</tt>. This parameter must be non <tt>NULL</tt> and must have been previously obtained by a call to <tt>SLang_get_function</tt>. <tag> Example </tag> Consider the <bf>S-lang</bf> function: <tscreen><verb> define my_fun (x) { return x^2 - 2; } </verb></tscreen> Suppose that it is desired to call this function many times with different values of x. There are at least two ways to do this. The easiest way is to use <tt>SLang_execute_function</tt> by passing the string <tt>"my_fun"</tt>. A better way that is much faster is to use <tt>SLexecute_function</tt>: <tscreen><verb> int sum_a_function (char *fname, double *result) { double sum, x, y; SLang_Name_Type *nt; if (NULL == (nt = SLang_get_function (fname))) return -1; sum = 0; for (x = 0; x < 10.0; x += 0.1) { SLang_start_arg_list (); if (-1 == SLang_push_double (x)) return -1; SLang_end_arg_list (); if (-1 == SLexecute_function (nt)) return -1; if (-1 == SLang_pop_double (&y, NULL, NULL)) return -1; sum += y; } return sum; } </verb></tscreen> Although not necessary in this case, <tt>SLang_start_arg_list</tt> and <tt>SLang_end_arg_list</tt> were used to provide the function with information about the number of parameters passed to it. <tag> See Also </tag> <tt>SLang_get_function, SLang_start_arg_list, SLang_end_arg_list</tt> </descrip><p> <sect><bf>SLang_peek_at_stack</bf><label id="SLang_peek_at_stack"><p><descrip> <tag> Synopsis </tag> Find the type of object on the top of the stack <tag> Usage </tag> <tt>int SLang_peek_at_stack (void)</tt> <tag> Description </tag> The <tt>SLang_peek_at_stack</tt> function is useful for determining the data type of the object at the top of the stack. It returns the data type, or -1 upon a stack-underflow error. It does not remove anything from the stack. <tag> See Also </tag> <tt>SLang_pop_string, SLang_pop_integer</tt> </descrip><p> <sect><bf>SLmake_string</bf><label id="SLmake_string"><p><descrip> <tag> Synopsis </tag> Duplicate a string <tag> Usage </tag> <tt>char *SLmake_string (char *s)</tt> <tag> Description </tag> The <tt>SLmake_string</tt> function creates a new copy of the string <tt>s</tt>, via <tt>malloc</tt>, and returns it. Upon failure it returns <tt>NULL</tt>. Since the resulting string is malloced, it should be freed when nolonger needed via a call to either <tt>free</tt> or <tt>SLfree</tt>. <tag> Notes </tag> <tt>SLmake_string</tt> should not be confused with the function <tt>SLang_create_slstring</tt>, which performs a similar function. <tag> See Also </tag> <tt>SLmake_nstring, SLfree, SLmalloc, SLang_create_slstring</tt> </descrip><p> <sect><bf>SLmake_nstring</bf><label id="SLmake_nstring"><p><descrip> <tag> Synopsis </tag> Duplicate a substring <tag> Usage </tag> <tt>char *SLmake_nstring (char *s, unsigned int n)</tt> <tag> Description </tag> This function is like <tt>SLmake_nstring</tt> except that it creates a null terminated string formed from the first <tt>n</tt> characters of <tt>s</tt>. Upon failure, it returns <tt>NULL</tt>, otherwise it returns the new string. When nolonger needed, the returned string should be freed with either <tt>free</tt> or <tt>SLfree</tt>. <tag> See Also </tag> <tt>SLmake_nstring, SLfree, SLang_create_nslstring</tt> </descrip><p> <sect><bf>SLang_create_nslstring</bf><label id="SLang_create_nslstring"><p><descrip> <tag> Synopsis </tag> Created a hashed substring <tag> Usage </tag> <tt>char *SLang_create_nslstring (char *s, unsigned int n)</tt> <tag> Description </tag> <tt>SLang_create_nslstring</tt> is like <tt>SLang_create_slstring</tt> except that only the first <tt>n</tt> characters of <tt>s</tt> are used to perform the string. Upon error, it returns <tt>NULL</tt>, otherwise it returns the hashed substring. Such a string must be freed by the function <tt>SLang_free_slstring</tt>. <tag> Notes </tag> Do not use <tt>free</tt> or <tt>SLfree</tt> to free the string returned by <tt>SLang_create_slstring</tt> or <tt>SLang_create_nslstring</tt>. Also it is important that no attempt is made to modify the hashed string returned by either of these functions. If one needs to modify a string, the functions <tt>SLmake_string</tt> or <tt>SLmake_nstring</tt> should be used instead. <tag> See Also </tag> <tt>SLang_free_slstring, SLang_create_slstring, SLmake_nstring</tt> </descrip><p> <sect><bf>SLang_create_slstring</bf><label id="SLang_create_slstring"><p><descrip> <tag> Synopsis </tag> Create a hashed string <tag> Usage </tag> <tt>char *SLang_create_slstring (char *s)</tt> <tag> Description </tag> The <tt>SLang_create_slstring</tt> creates a copy of <tt>s</tt> and returns it as a hashed string. Upon error, the function returns <tt>NULL</tt>, otherwise it returns the hashed string. Such a string must only be freed via the <tt>SLang_free_slstring</tt> function. <tag> Notes </tag> Do not use <tt>free</tt> or <tt>SLfree</tt> to free the string returned by <tt>SLang_create_slstring</tt> or <tt>SLang_create_nslstring</tt>. Also it is important that no attempt is made to modify the hashed string returned by either of these functions. If one needs to modify a string, the functions <tt>SLmake_string</tt> or <tt>SLmake_nstring</tt> should be used instead. <tag> See Also </tag> <tt>SLang_free_slstring, SLang_create_nslstring, SLmake_string</tt> </descrip><p> <sect><bf>SLang_free_slstring</bf><label id="SLang_free_slstring"><p><descrip> <tag> Synopsis </tag> Free a hashed string <tag> Usage </tag> <tt>void SLang_free_slstring (char *s)</tt> <tag> Description </tag> The <tt>SLang_free_slstring</tt> function is used to free a hashed string such as one returned by <tt>SLang_create_slstring</tt>, <tt>SLang_create_nslstring</tt>, or <tt>SLang_create_static_slstring</tt>. If <tt>s</tt> is <tt>NULL</tt>, the routine does nothing. <tag> See Also </tag> <tt>SLang_create_slstring, SLang_create_nslstring, SLang_create_static_slstring</tt> </descrip><p> <sect><bf>SLang_concat_slstrings</bf><label id="SLang_concat_slstrings"><p><descrip> <tag> Synopsis </tag> Concatenate two strings to produce a hashed string <tag> Usage </tag> <tt>char *SLang_concat_slstrings (char *a, char *b)</tt> <tag> Description </tag> The <tt>SLang_concat_slstrings</tt> function concatenates two strings, <tt>a</tt> and <tt>b</tt>, and returns the result as a hashed string. Upon failure, <tt>NULL</tt> is returned. <tag> Notes </tag> A hashed string can only be freed using <tt>SLang_free_slstring</tt>. Never use either <tt>free</tt> or <tt>SLfree</tt> to free a hashed string, otherwise memory corruption will result. <tag> See Also </tag> <tt>SLang_free_slstring, SLang_create_slstring</tt> </descrip><p> <sect><bf>SLang_create_static_slstring</bf><label id="SLang_create_static_slstring"><p><descrip> <tag> Synopsis </tag> Create a hashed string <tag> Usage </tag> <tt>char *SLang_create_static_slstring (char *s_literal)</tt> <tag> Description </tag> The <tt>SLang_create_static_slstring</tt> creates a hashed string from the string literal <tt>s_literal</tt> and returns the result. Upon failure it returns <tt>NULL</tt>. <tag> Example </tag> <tscreen><verb> char *create_hello (void) { return SLang_create_static_slstring ("hello"); } </verb></tscreen> <tag> Notes </tag> This function should only be used with string literals. <tag> See Also </tag> <tt>SLang_create_slstring, SLang_create_nslstring</tt> </descrip><p> <sect><bf>SLmalloc</bf><label id="SLmalloc"><p><descrip> <tag> Synopsis </tag> Allocate some memory <tag> Usage </tag> <tt>char *SLmalloc (unsigned int nbytes)</tt> <tag> Description </tag> This function uses <tt>malloc</tt> to allocate <tt>nbytes</tt> of memory. Upon error it returns <tt>NULL</tt>; otherwise it returns a pointer to the allocated memory. One should use <tt>SLfree</tt> to free the memory after used. <tag> See Also </tag> <tt>SLfree, SLrealloc, SLcalloc</tt> </descrip><p> <sect><bf>SLcalloc</bf><label id="SLcalloc"><p><descrip> <tag> Synopsis </tag> Allocate some memory <tag> Usage </tag> <tt>char *SLcalloc (unsigned int num_elem, unsigned int elem_size)</tt> <tag> Description </tag> This function uses <tt>calloc</tt> to allocate memory for <tt>num_elem</tt> objects with each of size <tt>elem_size</tt> and returns the result. In addition, the newly allocated memory is zeroed. Upon error it returns <tt>NULL</tt>; otherwise it returns a pointer to the allocated memory. One should use <tt>SLfree</tt> to free the memory after used. <tag> See Also </tag> <tt>SLmalloc, SLrealloc, SLfree</tt> </descrip><p> <sect><bf>SLfree</bf><label id="SLfree"><p><descrip> <tag> Synopsis </tag> Free some allocated memory <tag> Usage </tag> <tt>void SLfree (char *ptr)</tt> <tag> Description </tag> The <tt>SLfree</tt> function uses <tt>free</tt> to deallocate the memory specified by <tt>ptr</tt>, which may be <tt>NULL</tt> in which case the function does nothing. <tag> Notes </tag> Never use this function to free a hashed string returned by one of the family of <tt>slstring</tt> functions, e.g., <tt>SLang_pop_slstring</tt>. <tag> See Also </tag> <tt>SLmalloc, SLcalloc, SLrealloc, SLmake_string</tt> </descrip><p> <sect><bf>SLrealloc</bf><label id="SLrealloc"><p><descrip> <tag> Synopsis </tag> Resize a dynamic memory block <tag> Usage </tag> <tt>char *SLrealloc (char *ptr, unsigned int new_size)</tt> <tag> Description </tag> The <tt>SLrealloc</tt> uses the <tt>realloc</tt> function to resize the memory block specified by <tt>ptr</tt> to the new size <tt>new_size</tt>. If <tt>ptr</tt> is <tt>NULL</tt>, the function call is equivalent to <tt>SLmalloc(new_size)</tt>. Similarly, if <tt>new_size</tt> is zero, the function call is equivalent to <tt>SLfree(ptr)</tt>. If the function fails, or if <tt>new_size</tt> is zero, <tt>NULL</tt> is returned. Otherwise a pointer is returned to the (possibly moved) new block of memory. <tag> See Also </tag> <tt>SLfree, SLmalloc, SLcalloc</tt> </descrip><p> <sect><bf>SLcurrent_time_string</bf><label id="SLcurrent_time_string"><p><descrip> <tag> Synopsis </tag> Get the current time as a string <tag> Usage </tag> <tt>char *SLcurrent_time_string (void)</tt> <tag> Description </tag> The <tt>SLcurrent_time_string</tt> function uses the C library function call <tt>ctime</tt> to obtain a string representation of the the current date and time in the form <tscreen><verb> "Wed Dec 10 12:50:28 1997" </verb></tscreen> However, unlike the <tt>ctime</tt> function, a newline character is not present in the string. The returned value points to a statically allocated memory block which may get overwritten on subsequent function calls. <tag> See Also </tag> <tt>SLmake_string</tt> </descrip><p> <sect><bf>SLatoi</bf><label id="SLatoi"><p><descrip> <tag> Synopsis </tag> Convert a text string to an integer <tag> Usage </tag> <tt>int SLatoi(unsigned char *str</tt> <tag> Description </tag> <tt>SLatoi</tt> parses the string <tt>str</tt> to interpret it as an integer value. Unlike <tt>atoi</tt>, <tt>SLatoi</tt> can also parse strings containing integers expressed in hexidecimal (e.g., <tt>"0x7F"</tt>) and octal (e.g., <tt>"012"</tt>.) notation. <tag> See Also </tag> <tt>SLang_guess_type</tt> </descrip><p> <sect><bf>SLang_pop_fileptr</bf><label id="SLang_pop_fileptr"><p><descrip> <tag> Synopsis </tag> Pop a file pointer <tag> Usage </tag> <tt>int SLang_pop_fileptr (SLang_MMT_Type **mmt, FILE **fp)</tt> <tag> Description </tag> <tt>SLang_pop_fileptr</tt> pops a file pointer from the <bf>S-lang</bf> run-time stack. It returns zero upon success, or <tt>-1</tt> upon failure. A <bf>S-lang</bf> file pointer (SLANG_FILEPTR_TYPE) is actually a memory managed object. For this reason, <tt>SLang_pop_fileptr</tt> also returns the memory managed object via the argument list. It is up to the calling routine to call <tt>SLang_free_mmt</tt> to free the object. <tag> Example </tag> The following example illustrates an application defined intrinsic function that writes a user defined double precision number to a file. Note the use of <tt>SLang_free_mmt</tt>: <tscreen><verb> int write_double (void) { double t; SLang_MMT_Type *mmt; FILE *fp; int status; if (-1 == SLang_pop_double (&d, NULL, NULL)) return -1; if (-1 == SLang_pop_fileptr (&mmt, &fp)) return -1; status = fwrite (&d, sizeof (double), 1, fp); SLang_free_mmt (mmt); return status; } </verb></tscreen> This function can be used by a <bf>S-lang</bf> function as follows: <tscreen><verb> define write_some_values () { variable fp, d; fp = fopen ("myfile.dat", "wb"); if (fp == NULL) error ("file failed to open"); for (d = 0; d < 10.0; d += 0.1) { if (-1 == write_double (fp, d)) error ("write failed"); } if (-1 == fclose (fp)) error ("fclose failed"); } </verb></tscreen> <tag> See Also </tag> <tt>SLang_free_mmt, SLang_pop_double</tt> </descrip><p> <sect><bf>SLadd_intrinsic_function</bf><label id="SLadd_intrinsic_function"><p><descrip> <tag> Synopsis </tag> Add a new intrinsic function to the interpreter <tag> Usage </tag> <tt>int SLadd_intrinsic_function (name, f, type, nargs, ...)</tt> <tscreen><verb> char *name FVOID_STAR f unsigned char type unsigned int nargs </verb></tscreen> <tag> Description </tag> The <tt>SLadd_intrinsic_function</tt> function may be used to add a new intrinsic function. The <bf>S-lang</bf> name of the function is specified by <tt>name</tt> and the actual function pointer is given by <tt>f</tt>, cast to <tt>FVOID_STAR</tt>. The third parameter, <tt>type</tt> specifies the return type of the function and must be one of the following values: <tscreen><verb> SLANG_VOID_TYPE (returns nothing) SLANG_INT_TYPE (returns int) SLANG_DOUBLE_TYPE (returns double) SLANG_STRING_TYPE (returns char *) </verb></tscreen> The <tt>nargs</tt> parameter specifies the number of parameters to pass to the function. The variable argument list following <tt>nargs</tt> must consists of <tt>nargs</tt> integers which specify the data type of each argument. The function returns zero upon success or <tt>-1</tt> upon failure. <tag> Example </tag> The <bf>jed</bf> editor uses this function to change the <tt>system</tt> intrinsic function to the following: <tscreen><verb> static int jed_system (char *cmd) { if (Jed_Secure_Mode) { msg_error ("Access denied."); return -1; } return SLsystem (cmd); } </verb></tscreen> After initializing the interpreter with <tt>SLang_init_slang</tt>, <bf>jed</bf> calls <tt>SLadd_intrinsic_function</tt> to substitute the above definition for the default <bf>S-lang</bf> definition: <tscreen><verb> if (-1 == SLadd_intrinsic_function ("system", (FVOID_STAR)jed_system, SLANG_INT_TYPE, 1, SLANG_STRING_TYPE)) return -1; </verb></tscreen> <tag> See Also </tag> <tt>SLadd_intrinsic_variable, SLadd_intrinsic_array</tt> </descrip><p> <sect><bf>SLadd_intrinsic_variable</bf><label id="SLadd_intrinsic_variable"><p><descrip> <tag> Synopsis </tag> Add an intrinsic variable to the interpreter <tag> Usage </tag> <tt>int SLadd_intrinsic_variable (name, addr, type, rdonly)</tt> <tscreen><verb> char *name VOID_STAR type unsigned char type int rdonly </verb></tscreen> <tag> Description </tag> The <tt>SLadd_intrinsic_variable</tt> function adds an intrinsic variable called <tt>name</tt> to the interpeter. The second parameter <tt>addr</tt> specifies the address of the variable (cast to <tt>VOID_STAR</tt>). The third parameter, <tt>type</tt>, specifies the data type of the variable. If the fourth parameter, <tt>rdonly</tt>, is non-zero, the variable will interpreted by the interpreter as read-only. If successful, <tt>SLadd_intrinsic_variable</tt> returns zero, otherwise it returns <tt>-1</tt>. <tag> Example </tag> Suppose that <tt>My_Global_Int</tt> is a global variable (at least not a local one): <tscreen><verb> int My_Global_Int; </verb></tscreen> It can be added to the interpreter via the function call <tscreen><verb> if (-1 == SLadd_intrinsic_variable ("MyGlobalInt", (VOID_STAR)&My_Global_Int, SLANG_INT_TYPE, 0)) exit (1); </verb></tscreen> <tag> Notes </tag> The current implementation requires all pointer type intrinsic variables to be read-only. For example, <tscreen><verb> char *My_Global_String; </verb></tscreen> is of type <tt>SLANG_STRING_TYPE</tt>, and must be declared as read-only. Finally, not that <tscreen><verb> char My_Global_Char_Buf[256]; </verb></tscreen> is <em>not</em> a <tt>SLANG_STRING_TYPE</tt> object. This difference is very important because internally the interpreter dereferences the address passed to it to get to the value of the variable. <tag> See Also </tag> <tt>SLadd_intrinsic_function, SLadd_intrinsic_array</tt> </descrip><p> } <sect><bf>SLclass_add_unary_op</bf><label id="SLclass_add_unary_op"><p><descrip> <tag> Synopsis </tag> ?? <tag> Usage </tag> <tt>int SLclass_add_unary_op (unsigned char,int (*) (int, unsigned char, VOID_STAR, unsigned int, VOID_STAR), int (*) (int, unsigned char, unsigned char *));</tt> <tag> Description </tag> ?? <tag> See Also </tag> <tt>??</tt> </descrip><p> <sect><bf>SLclass_add_app_unary_op</bf><label id="SLclass_add_app_unary_op"><p><descrip> <tag> Synopsis </tag> ?? <tag> Usage </tag> <tt>int SLclass_add_app_unary_op (unsigned char, int (*) (int,unsigned char, VOID_STAR, unsigned int,VOID_STAR),int (*) (int, unsigned char, unsigned char *));</tt> <tag> Description </tag> ?? <tag> See Also </tag> <tt>??</tt> </descrip><p> <sect><bf>SLclass_add_binary_op</bf><label id="SLclass_add_binary_op"><p><descrip> <tag> Synopsis </tag> ?? <tag> Usage </tag> <tt>int SLclass_add_binary_op (unsigned char, unsigned char,int (*)(int, unsigned char, VOID_STAR, unsigned int,unsigned char, VOID_STAR, unsigned int,VOID_STAR),int (*) (int, unsigned char, unsigned char, unsigned char *));</tt> <tag> Description </tag> ?? <tag> See Also </tag> <tt>??</tt> </descrip><p> <sect><bf>SLclass_add_math_op</bf><label id="SLclass_add_math_op"><p><descrip> <tag> Synopsis </tag> ?? <tag> Usage </tag> <tt>int SLclass_add_math_op (unsigned char,int (*)(int,unsigned char, VOID_STAR, unsigned int,VOID_STAR),int (*)(int, unsigned char, unsigned char *));</tt> <tag> Description </tag> ?? <tag> See Also </tag> <tt>??</tt> </descrip><p> <sect><bf>SLclass_add_typecast</bf><label id="SLclass_add_typecast"><p><descrip> <tag> Synopsis </tag> ?? <tag> Usage </tag> <tt>int SLclass_add_typecast (unsigned char, unsigned char int (*)_PROTO((unsigned char, VOID_STAR, unsigned int,unsigned char, VOID_STAR)),int);</tt> <tag> Description </tag> ?? <tag> See Also </tag> <tt>??</tt> </descrip><p> <sect><bf>SLang_init_tty</bf><label id="SLang_init_tty"><p><descrip> <tag> Synopsis </tag> Initialize the terminal keyboard interface <tag> Usage </tag> <tt>int SLang_init_tty (int intr_ch, int no_flow_ctrl, int opost)</tt> <tag> Description </tag> <tt>SLang_init_tty</tt> initializes the terminal for single character input. If the first parameter <tt>intr_ch</tt> is in the range 0-255, it will be used as the interrupt character, e.g., under Unix this character will generate a <tt>SIGINT</tt> signal. Otherwise, if it is <tt>-1</tt>, the interrupt character will be left unchanged. If the second parameter <tt>no_flow_ctrl</tt> is non-zero, flow control (<tt>XON</tt>/<tt>XOFF</tt>) processing will be enabled. If the last parmeter <tt>opost</tt> is non-zero, output processing by the terminal will be enabled. If one intends to use this function in conjunction with the <bf>S-lang</bf> screen management routines (<tt>SLsmg</tt>), this paramete shold be set to zero. <tt>SLang_init_tty</tt> returns zero upon success, or <tt>-1</tt> upon error. <tag> Notes </tag> Terminal I/O is a complex subject. The <bf>S-lang</bf> interface presents a simplification that the author has found useful in practice. For example, the only special character processing that <tt>SLang_init_tty</tt> enables is that of the <tt>SIGINT</tt> character, and the generation of other signals via the keyboard is disabled. However, generation of the job control signal <tt>SIGTSTP</tt> is possible via the <tt>SLtty_set_suspend_state</tt> function. Under Unix, the integer variable <tt>SLang_TT_Read_FD</tt> is used to specify the input descriptor for the terminal. If <tt>SLang_TT_Read_FD</tt> represents a terminal device as determined via the <tt>isatty</tt> system call, then it will be used as the terminal file descriptor. Otherwise, the terminal device <tt>/dev/tty</tt> will used as the input device. The default value of <tt>SLang_TT_Read_FD</tt> is <tt>-1</tt> which causes <tt>/dev/tty</tt> to be used. So, if you prefer to use <tt>stdin</tt> for input, then set <tt>SLang_TT_Read_FD</tt> to <tt>fileno(stdin)</tt> <em>before</em> calling <tt>SLang_init_tty</tt>. If the variable <tt>SLang_TT_Baud_Rate</tt> is zero when this function is called, the function will attempt to determine the baud rate by querying the terminal driver and set <tt>SLang_TT_Baud_Rate</tt> to that value. <tag> See Also </tag> <tt>SLang_reset_tty, SLang_getkey, SLtty_set_suspend_state</tt> </descrip><p> <sect><bf>SLang_reset_tty</bf><label id="SLang_reset_tty"><p><descrip> <tag> Synopsis </tag> Reset the terminal <tag> Usage </tag> <tt>void SLang_reset_tty (void)</tt> <tag> Description </tag> <tt>SLang_reset_tty</tt> resets the terminal interface back to the state it was in before <tt>SLang_init_tty</tt> was called. <tag> See Also </tag> <tt>SLang_init_tty</tt> </descrip><p> <sect><bf>SLtty_set_suspend_state</bf><label id="SLtty_set_suspend_state"><p><descrip> <tag> Synopsis </tag> Enable or disable keyboard suspension <tag> Usage </tag> <tt>void SLtty_set_suspend_state (int s)</tt> <tag> Description </tag> The <tt>SLtty_set_suspend_state</tt> function may be used to enable or disable keyboard generation of the <tt>SIGTSTP</tt> job control signal. If <tt>s</tt> is non-zero, generation of this signal via the terminal interface will be enabled, otherwise it will be disabled. This function should only be called after the terminal driver has be initialized via <tt>SLang_init_tty</tt>. The <tt>SLang_init_tty</tt> always disables the generation of <tt>SIGTSTP</tt> via the keyboard. <tag> See Also </tag> <tt>SLang_init_tty</tt> </descrip><p> <sect><bf>SLang_getkey</bf><label id="SLang_getkey"><p><descrip> <tag> Synopsis </tag> Read a character from the keyboard <tag> Usage </tag> <tt>unsigned int SLang_getkey (void);</tt> <tag> Description </tag> The <tt>SLang_getkey</tt> reads a single character from the terminal and returns it. The terminal must first be initialized via a call to <tt>SLang_init_tty</tt> before this function can be called. Upon success, <tt>SLang_getkey</tt> returns the character read from the terminal, otherwise it returns <tt>SLANG_GETKEY_ERROR</tt>. <tag> See Also </tag> <tt>SLang_init_tty, SLang_input_pending, SLang_ungetkey</tt> </descrip><p> <sect><bf>SLang_ungetkey_string</bf><label id="SLang_ungetkey_string"><p><descrip> <tag> Synopsis </tag> Unget a key string <tag> Usage </tag> <tt>int SLang_ungetkey_string (unsigned char *buf, unsigned int n)</tt> <tag> Description </tag> The <tt>SLang_ungetkey_string</tt> function may be used to push the <tt>n</tt> characters pointed to by <tt>buf</tt> onto the buffered input stream that <tt>SLgetkey</tt> uses. If there is not enough room for the characters, <tt>-1</tt> is returned and none are buffered. Otherwise, it returns zero. <tag> Notes </tag> The difference between <tt>SLang_buffer_keystring</tt> and <tt>SLang_ungetkey_string</tt> is that the <tt>SLang_buffer_keystring</tt> appends the characters to the end of the getkey buffer, whereas <tt>SLang_ungetkey_string</tt> inserts the characters at the beginning of the input buffer. <tag> See Also </tag> <tt>SLang_ungetkey, SLang_getkey</tt> </descrip><p> <sect><bf>SLang_buffer_keystring</bf><label id="SLang_buffer_keystring"><p><descrip> <tag> Synopsis </tag> Append a keystring to the input buffer <tag> Usage </tag> <tt>int SLang_buffer_keystring (unsigned char *b, unsigned int len)</tt> <tag> Description </tag> <tt>SLang_buffer_keystring</tt> places the <tt>len</tt> characters specified by <tt>b</tt> at the <em>end</em> of the buffer that <tt>SLang_getkey</tt> uses. Upon success it returns 0; otherwise, no characters are buffered and it returns <tt>-1</tt>. <tag> Notes </tag> The difference between <tt>SLang_buffer_keystring</tt> and <tt>SLang_ungetkey_string</tt> is that the <tt>SLang_buffer_keystring</tt> appends the characters to the end of the getkey buffer, whereas <tt>SLang_ungetkey_string</tt> inserts the characters at the beginning of the input buffer. <tag> See Also </tag> <tt>SLang_getkey, SLang_ungetkey, SLang_ungetkey_string</tt> </descrip><p> <sect><bf>SLang_ungetkey</bf><label id="SLang_ungetkey"><p><descrip> <tag> Synopsis </tag> Push a character back onto the input buffer <tag> Usage </tag> <tt>int SLang_ungetkey (unsigned char ch)</tt> <tag> Description </tag> <tt>SLang_ungetkey</tt> pushes the character <tt>ch</tt> back onto the <tt>SLgetkey</tt> input stream. Upon success, it returns zero, otherwise it returns <tt>1</tt>. <tag> Example </tag> This function is implemented as: <tscreen><verb> int SLang_ungetkey (unsigned char ch) { return SLang_ungetkey_string(&ch, 1); } </verb></tscreen> <tag> See Also </tag> <tt>SLang_getkey, SLang_ungetkey_string</tt> </descrip><p> <sect><bf>SLang_flush_input</bf><label id="SLang_flush_input"><p><descrip> <tag> Synopsis </tag> Discard all keyboard input waiting to be read <tag> Usage </tag> <tt>void SLang_flush_input (void)</tt> <tag> Description </tag> <tt>SLang_flush_input</tt> discards all input characters waiting to be read by the <tt>SLang_getkey</tt> function. <tag> See Also </tag> <tt>SLang_getkey</tt> </descrip><p> <sect><bf>SLang_input_pending</bf><label id="SLang_input_pending"><p><descrip> <tag> Synopsis </tag> Check to see if input is pending <tag> Usage </tag> <tt>int SLang_input_pending (int tsecs)</tt> <tag> Description </tag> <tt>SLang_input_pending</tt> may be used to see if an input character is available to be read without causing <tt>SLang_getkey</tt> to block. It will wait up to <tt>tsecs</tt> tenths of a second if no characters are immediately available for reading. If <tt>tsecs</tt> is less than zero, then <tt>SLang_input_pending</tt> will wait <tt>-tsecs</tt> milliseconds for input, otherwise <tt>tsecs</tt> represents <tt>1/10</tt> of a second intervals. <tag> Notes </tag> Not all systems support millisecond resolution. <tag> See Also </tag> <tt>SLang_getkey</tt> </descrip><p> <sect><bf>SLang_set_abort_signal</bf><label id="SLang_set_abort_signal"><p><descrip> <tag> Synopsis </tag> Set the signal to trap SIGINT <tag> Usage </tag> <tt>void SLang_set_abort_signal (void (*f)(int));</tt> <tag> Description </tag> <tt>SLang_set_abort_signal</tt> sets the function that gets triggered when the user presses the interrupt key (<tt>SIGINT</tt>) to the function <tt>f</tt>. If <tt>f</tt> is <tt>NULL</tt> the default handler will get installed. <tag> Example </tag> The default interrupt handler on a Unix system is: <tscreen><verb> static void default_sigint (int sig) { SLKeyBoard_Quit = 1; if (SLang_Ignore_User_Abort == 0) SLang_Error = SL_USER_BREAK; SLsignal_intr (SIGINT, default_sigint); } </verb></tscreen> <tag> Notes </tag> For Unix programmers, the name of this function may appear misleading since it is associated with <tt>SIGINT</tt> and not <tt>SIGABRT</tt>. The origin of the name stems from the original intent of the function: to allow the user to abort the running of a <bf>S-lang</bf> interpreter function. <tag> See Also </tag> <tt>SLang_init_tty, SLsignal_intr</tt> </descrip><p> <sect><bf>SLkm_define_key</bf><label id="SLkm_define_key"><p><descrip> <tag> Synopsis </tag> Define a key in a keymap <tag> Usage </tag> <tt>int SLkm_define_key (char *seq, FVOID_STAR f, SLKeyMap_List_Type *km)</tt> <tag> Description </tag> <tt>SLkm_define_key</tt> associates the key sequence <tt>seq</tt> with the function pointer <tt>f</tt> in the keymap specified by <tt>km</tt>. Upon success, it returns zero, otherwise it returns a negative integer upon error. <tag> See Also </tag> <tt>SLkm_define_keysym, SLang_define_key</tt> </descrip><p> <sect><bf>SLang_define_key</bf><label id="SLang_define_key"><p><descrip> <tag> Synopsis </tag> Define a key in a keymap <tag> Usage </tag> <tt>int SLang_define_key(char *seq, char *fun, SLKeyMap_List_Type *km)</tt> <tag> Description </tag> <tt>SLang_define_key</tt> associates the key sequence <tt>seq</tt> with the function whose name is <tt>fun</tt> in the keymap specified by <tt>km</tt>. <tag> See Also </tag> <tt>SLkm_define_keysym, SLkm_define_key</tt> </descrip><p> <sect><bf>SLkm_define_keysym</bf><label id="SLkm_define_keysym"><p><descrip> <tag> Synopsis </tag> Define a keysym in a keymap <tag> Usage </tag> <tt>int SLkm_define_keysym (seq, ks, km)</tt> <tscreen><verb> char *seq; unsigned int ks; SLKeyMap_List_Type *km; </verb></tscreen> <tag> Description </tag> <tt>SLkm_define_keysym</tt> associates the key sequence <tt>seq</tt> with the keysym <tt>ks</tt> in the keymap <tt>km</tt>. Keysyms whose value is less than or equal to <tt>0x1000</tt> is reserved by the library and should not be used. <tag> See Also </tag> <tt>SLkm_define_key, SLang_define_key</tt> </descrip><p> <sect><bf>SLang_undefine_key</bf><label id="SLang_undefine_key"><p><descrip> <tag> Synopsis </tag> Undefined a key from a keymap <tag> Usage </tag> <tt>void SLang_undefine_key(char *seq, SLKeyMap_List_Type *km);</tt> <tag> Description </tag> <tt>SLang_undefine_key</tt> removes the key sequence <tt>seq</tt> from the keymap <tt>km</tt>. <tag> See Also </tag> <tt>SLang_define_key</tt> </descrip><p> <sect><bf>SLang_create_keymap</bf><label id="SLang_create_keymap"><p><descrip> <tag> Synopsis </tag> Create a new keymap <tag> Usage </tag> <tt>SLKeyMap_List_Type *SLang_create_keymap (name, km)</tt> <tscreen><verb> char *name; SLKeyMap_List_Type *km; </verb></tscreen> <tag> Description </tag> <tt>SLang_create_keymap</tt> creates a new keymap called <tt>name</tt> by copying the key definitions from the keymap <tt>km</tt>. If <tt>km</tt> is <tt>NULL</tt>, the newly created keymap will be empty and it is up to the calling routine to initialize it via the <tt>SLang_define_key</tt> and <tt>SLkm_define_keysym</tt> functions. <tt>SLang_create_keymap</tt> returns a pointer to the new keymap, or <tt>NULL</tt> upon failure. <tag> See Also </tag> <tt>SLang_define_key, SLkm_define_keysym</tt> </descrip><p> <sect><bf>SLang_do_key</bf><label id="SLang_do_key"><p><descrip> <tag> Synopsis </tag> Read a keysequence and return its keymap entry <tag> Usage </tag> <tt>SLang_Key_Type *SLang_do_key (kml, getkey)</tt> <tscreen><verb> SLKeyMap_List_Type *kml; int (*getkey)(void); </verb></tscreen> <tag> Description </tag> The <tt>SLang_do_key</tt> function reads characters using the function specified by the <tt>getkey</tt> function pointer and uses the key sequence to return the appropriate entry in the keymap specified by <tt>kml</tt>. <tt>SLang_do_key</tt> returns <tt>NULL</tt> if the key sequence is not defined by the keymap, otherwise it returns a pointer to an object of type <tt>SLang_Key_Type</tt>, which is defined in <tt>slang.h</tt> as <tscreen><verb> #define SLANG_MAX_KEYMAP_KEY_SEQ 14 typedef struct SLang_Key_Type { struct SLang_Key_Type *next; union { char *s; FVOID_STAR f; unsigned int keysym; } f; unsigned char type; /* type of function */ #define SLKEY_F_INTERPRET 0x01 #define SLKEY_F_INTRINSIC 0x02 #define SLKEY_F_KEYSYM 0x03 unsigned char str[SLANG_MAX_KEYMAP_KEY_SEQ + 1];/* key sequence */ } SLang_Key_Type; </verb></tscreen> The <tt>type</tt> field specifies which field of the union <tt>f</tt> should be used. If <tt>type</tt> is <tt>SLKEY_F_INTERPRET</tt>, then <tt>f.s</tt> is a string that should be passed to the interpreter for evaluation. If <tt>type</tt> is <tt>SLKEY_F_INTRINSIC</tt>, then <tt>f.f</tt> refers to function that should be called. Otherwise, <tt>type</tt> is <tt>SLKEY_F_KEYSYM</tt> and <tt>f.keysym</tt> represents the value of the keysym that is associated with the key sequence. <tag> See Also </tag> <tt>SLkm_define_keysym, SLkm_define_key</tt> </descrip><p> <sect><bf>SLang_find_key_function</bf><label id="SLang_find_key_function"><p><descrip> <tag> Synopsis </tag> Obtain a function pointer associated with a keymap <tag> Usage </tag> <tt>FVOID_STAR SLang_find_key_function (fname, km);</tt> <tscreen><verb> char *fname; SLKeyMap_List_Type *km; </verb></tscreen> <tag> Description </tag> The <tt>SLang_find_key_function</tt> routine searches through the <tt>SLKeymap_Function_Type</tt> list of functions associated with the keymap <tt>km</tt> for the function with name <tt>fname</tt>. If a matching function is found, a pointer to the function will be returned, otherwise <tt>SLang_find_key_function</tt> will return <tt>NULL</tt>. <tag> See Also </tag> <tt>SLang_create_keymap, SLang_find_keymap</tt> </descrip><p> <sect><bf>SLang_find_keymap</bf><label id="SLang_find_keymap"><p><descrip> <tag> Synopsis </tag> Find a keymap <tag> Usage </tag> <tt>SLKeyMap_List_Type *SLang_find_keymap (char *keymap_name);</tt> <tag> Description </tag> The <tt>SLang_find_keymap</tt> function searches through the list of keymaps looking for one whose name is <tt>keymap_name</tt>. If a matching keymap is found, the function returns a pointer to the keymap. It returns <tt>NULL</tt> if no such keymap exists. <tag> See Also </tag> <tt>SLang_create_keymap, SLang_find_key_function</tt> </descrip><p> <sect><bf>SLang_process_keystring</bf><label id="SLang_process_keystring"><p><descrip> <tag> Synopsis </tag> Un-escape a key-sequence <tag> Usage </tag> <tt>char *SLang_process_keystring (char *kseq);</tt> <tag> Description </tag> The <tt>SLang_process_keystring</tt> function converts an escaped key sequence to its raw form by converting two-character combinations such as <tt>^A</tt> to the <em>single</em> character <tt>Ctrl-A</tt> (ASCII 1). In addition, if the key sequence contains constructs such as <tt>^(XX)</tt>, where <tt>XX</tt> represents a two-character termcap specifier, the termcap escape sequence will be looked up and substituted. Upon success, <tt>SLang_process_keystring</tt> returns a raw key-sequence whose first character represents the total length of the key-sequence, including the length specifier itself. It returns <tt>NULL</tt> upon failure. <tag> Example </tag> Consider the following examples: <tscreen><verb> SLang_process_keystring ("^X^C"); SLang_process_keystring ("^[[A"); </verb></tscreen> The first example will return a pointer to a buffer of three characters whose ASCII values are given by <tt>{3,24,3}</tt>. Similarly, the second example will return a pointer to the four characters <tt>{4,27,91,65}</tt>. Finally, the result of <tscreen><verb> SLang_process_keystring ("^[^(ku)"); </verb></tscreen> will depend upon the termcap/terminfo capability <tt>"ku"</tt>, which represents the escape sequence associated with the terminal's UP arrow key. For an ANSI terminal whose UP arrow produces <tt>"ESC [ A"</tt>, the result will be <tt>5,27,27,91,65</tt>. <tag> Notes </tag> <tt>SLang_process_keystring</tt> returns a pointer to a static area that will be overwritten on subsequent calls. <tag> See Also </tag> <tt>SLang_define_key, SLang_make_keystring</tt> </descrip><p> <sect><bf>SLang_make_keystring</bf><label id="SLang_make_keystring"><p><descrip> <tag> Synopsis </tag> Make a printable key sequence <tag> Usage </tag> <tt>char *SLang_make_keystring (unsigned char *ks);</tt> <tag> Description </tag> The <tt>SLang_make_keystring</tt> function takes a raw key sequence <tt>ks</tt> and converts it to a printable form by converting characters such as ASCII 1 (ctrl-A) to <tt>^A</tt>. That is, it performs the opposite function of <tt>SLang_process_keystring</tt>. <tag> Notes </tag> This function returns a pointer to a static area that will be overwritten on the next call to <tt>SLang_make_keystring</tt>. <tag> See Also </tag> <tt>SLang_process_keystring</tt> </descrip><p> <sect><bf>SLextract_list_element</bf><label id="SLextract_list_element"><p><descrip> <tag> Synopsis </tag> Extract a substring of a delimited string <tag> Usage </tag> <tt>int SLextract_list_element (dlist, nth, delim, buf, buflen)</tt> <tscreen><verb> char *dlist; unsigned int nth; char delim; char *buf; unsigned int buflen; </verb></tscreen> <tag> Description </tag> <tt>SLextract_list_element</tt> may be used to obtain the <tt>nth</tt> element of a list of strings, <tt>dlist</tt>, that are delimited by the character <tt>delim</tt>. The routine copies the <tt>nth</tt> element of <tt>dlist</tt> to the buffer <tt>buf</tt> whose size is <tt>buflen</tt> characters. It returns zero upon success, or <tt>-1</tt> if <tt>dlist</tt> does not contain an <tt>nth</tt> element. <tag> Example </tag> A delimited list of strings may be turned into an array of strings as follows. For conciseness, all malloc error checking has been omitted. <tscreen><verb> int list_to_array (char *list, char delim, char ***ap) { unsigned int nth; char **a; char buf[1024]; /* Determine the size of the array */ nth = 0; while (0 == SLextract_list_element (list, nth, delim, buf, sizeof(buf))) nth++; ap = (char **) SLmalloc ((nth + 1) * sizeof (char **)); nth = 0; while (0 == SLextract_list_element (list, nth, delim, buf, sizeof(buf))) { a[nth] = SLmake_string (buf); nth++; } a[nth] = NULL; *ap = a; return 0; } </verb></tscreen> <tag> See Also </tag> <tt>SLmalloc, SLmake_string</tt> </descrip><p> </article>