Languages Library Guardian TNS C Library Calls Reference Manual Abstract This manual describes the C run-time library available to TNS and accelerated programs in the Guardian environment. Product Version TNS C Run-Time Library D40 Supported Releases This manual supports D40.00 and all subsequent releases until otherwise indicated in a new edition. Part Number Edition Published Release ID 128833 Second July 1996 D42.
Document History Edition Part Number Product Version Earliest Supported Release Published First 115745 TNS C Run-Time Library D40.00 November 1995 D40.00 July 1996 D40 Second 128833* TNS C Run-Time Library D40 New editions incorporate any updates since the previous edition. A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an interim product modification (IPM) or by a new product version on a .99 site update tape (SUT).
New and Changed Information This edition has the same content as the previous edition with any updates; the content has been reformatted to make it more readable online.
New and Changed Information iv 128833 —Guardian TNS C Library Calls Reference Manual
Contents New and Changed Information iii About This Manual xiii Notation Conventions xvii 1. Introduction to the Guardian TNS C Run-Time Library 2. Summary of Library Header Files 2-1 2-1 2-2 2-5 2-6 2-8 2-9 2-9 2-10 2-10 2-10 2-10 2-11 2-11 2-11 2-11 2-12 2-13 2-13 2-13 3.
3.
Contents 3.
3.
Contents 3.
3.
Contents trap_overflows (supplementary) 3-227 ungetc 3-228 unlink (supplementary) 3-229 va_arg 3-230 va_end 3-231 va_start 3-232 vfprintf 3-233 vprintf 3-234 vsprintf 3-235 wctomb 3-236 wcstombs 3-237 write (supplementary) 3-238 writeread (supplementary) 3-239 Index Index-1 Tables Table i. Table ii. Table 2-1.
Contents xii 128833 —Guardian TNS C Library Calls Reference Manual
About This Manual This manual describes the syntax and semantics of the Guardian TNS (Tandem NonStop Series) C run-time library. The Guardian TNS C run-time library is available to TNS and accelerated programs. This manual supports D40.00 or later releases of the Tandem TNS C compiler and Guardian TNS C run-time library. Refer to previous editions of the C Reference Manual if you are using a previous release.
Additional Information About This Manual Additional Information Table i describes manuals that provide information about writing C programs for the Guardian environment. Table i. Guardian Environment Manuals Manual Description C/C++ Programmer’s Guide Describes the syntax and semantics of C. Provides guidelines on writing C programs for Tandem NonStop systems.
About This Manual Your Comments Invited Your Comments Invited After using this manual, please take a moment to send us your comments. You can do this by returning a Reader Comment Card or by sending an Internet mail message. A Reader Comment Card is located at the back of printed manuals and as a separate file on the Tandem CD Read disc. You can either FAX or mail the card to us. The FAX number and mailing address are provided on the card.
Your Comments Invited xvi About This Manual 128833 —Guardian TNS C Library Calls Reference Manual
Notation Conventions General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name [ ] Brackets.
General Syntax Notation Notation Conventions … Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address-1 [ , new-value ]... [ - ] {0|1|2|3|4|5|6|7|8|9}... An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char..." Punctuation.
1 Intro Run-Time Library C is a relatively small, yet powerful and effective, programming language. With the extensive run-time library C provides, C becomes an excellent language for a wide variety of both systems and applications programming projects.
Introduction to the Guardian TNS C Run-Time Library One of the model-dependent libraries must be into your program, depending on the memory or data model used. Refer to the C/C++ Programmer’s Guide for a complete description on selecting the correct run-time library for your programs.
2 Summary of Library Header Files The macros and functions in the Guardian TNS C run-time library are declared in 20 header files. Each header contains declarations for a related set of library functions and macros, as well as variables and types that complete that set. If you use a function in the library, you should include the header file in which it is declared.
Summary of Library Header Files The header errnoh declares one function and several object-like macros that are used by several library functions to report errors. The function declared is errno, and returns a value of type int. The ISO/ANSI C standard requires that the C run-time library return only positive integral values to errno. Table 2-1 lists the macros and their symbolic meanings. Table 2-1.
Summary of Library Header Files Table 2-1.
Summary of Library Header Files Table 2-1.
Summary of Library Header Files Table 2-1.
Summary of Library Header Files Here are the macros defined for use in fcntl. The meanings of these macros are described in the discussion of fcntl in Section 3, “Reference to Library Calls”: F_FLUSH F_GETFN F_SETFL F_GETDTYPE F_OFF F_SETTAB F_GETFCODE F_ON F_GETFL F_SETBUF Note. The fcntlh header is not specified by the ISO/ANSI C standard. The header is specified by the POSIX.1 and XPG4 standards.
Summary of Library Header Files Here are the macros that describe the floating-point type double. Following each macro name is its defined value. DBL_DIG 16 DBL_EPSILON 2.7e-17 DBL_MANT_DIG 16 DBL_MAX 1.1579208923716189e77 DBL_MAX_10_EXP 77 DBL_MIN 8.6361685550944446e-78 DBL_MIN_10_EXP (-77) DBL_MIN_EXP (-254) DBL_MAX_EXP (256) Here are the macros that describe the floating-point type long double. Following each macro name is its defined value. LDBL_DIG 16 LDBL_EPSILON 2.
Summary of Library Header Files The header limitsh defines object-like macros that describe the representation and limits of integral types in the C language. Here are the macros that describe the integral types char, signed char, and unsigned char. Each macro name is followed by its value and its meaning.
Summary of Library Header Files Here are the macros that describe the integral types short and unsigned short. Each macro name is followed by its value and its meaning. SHRT_MIN -32768 Minimum value for a short variable SHRT_MAX 32767 Maximum short value USHRT_MAX 65535 Maximum unsigned short value Here are the macros that describe the integral type long long. Each macro name is followed by its value and its meaning.
Summary of Library Header Files The header memoryh declares three memory-management functions: movmem repmem setmem The header nonstoph declares six functions that support fault tolerant programming in C programs: __ns_fget_file_state __ns_fget_file_open_state __ns_fopen_special __ns_fset_file_state __ns_backup_fopen __ns_start_backup The header also declares two structures: __ns_std_io_file_open_state __ns_std_io_file_state The nonstoph header file is a Tandem extens
Summary of Library Header Files The signal handlers and signals are described in Section 3, “Reference to Library Calls,” under the signal function. The header sqlh declares the functions dec_to_longlong and longlong_to_dec, which convert data between representations as a decimal array and as a long long value. The header stdargh declares the type va_list and defines the function-like macros va_arg, va_end, and va_start.
Summary of Library Header Files The stdioh header also defines these object-like macros: • • • • • • • • • BUFSIZ specifies the size in bytes of the buffers the C language uses for streams. Refer to the C/C++ Programmer’s Guide for the maximum length in bytes of these buffers. EOF is the value returned by several functions to indicate the end of the file. FCHR_MAX specifies the maximum size (in bytes) of a file. FILENAME_MAX specifies the maximum length (in characters) of a file name.
Summary of Library Header Files The header stringh declares these string-handling functions: ecvt memswap stci_d stcu_d strcat strlen strspn memchr stcarg stcis stpblk strchr strncat strstr memcmp stccpy stcisn stpbrk strcmp strncmp strtok memcpy stcd_i stclen stpchr strcpy strncpy stscmp memmove stcd_l stcpm stpsym strcspn strpbrk memset stch_i stcpma stptok strerror strrchr The header talh defines the three objectlike macros—CCE, CCG, and CCL—that denote the condition-code
2- 14 Summary of Library Header Files 128833 —Guardian TNS C Library Calls Reference Manual
3 Reference to Library Calls This section describes the routines in the Guardian TNS C run-time library. The description of each routine shows: • • • What the routine does Whether the routine is a function or a macro Whether the routine is part of standard C or is a supplementary Tandem extension to the ISO/ANSI C standard.
acos Reference to Library Calls Usage Guidelines • The absolute value of the most negative integer (INT_MIN) cannot be represented. Example This example prints “The absolute value of -25 is 25.” #include #include int main(void) { int r, x; x = -25; r = abs(x); printf("The absolute value of %d is %d.", x, r); } acos The acos function computes the arc cosine of its argument.
Reference to Library Calls asctime asctime The asctime function converts the broken-down time pointed to by timeptr into a string. #include char *asctime (const struct tm *timeptr); timeptr points to the broken-down time. Return Value is a pointer to the string. Usage Guidelines • The structure pointed to by timeptr is of type struct tm.
asctime Reference to Library Calls Examples 1. This example converts the calendar time pointed to by &now to local time in the form of a string. #include #include time_t now; int main(void) { now = time(NULL); printf("%s%s\n", "asctime(localtime(&now)) = ", asctime(localtime(&now))); } 2. This example shows two alternate methods for converting the calendar time to local time in the form of a string.
Reference to Library Calls asin asin The asin function computes the arc sine of its argument. #include double asin(double expr); expr is an expression of type double whose value is in the range -1 to +1. Return Value is the arc sine of expr, expressed as a double value in the range -pi/2 to +pi/2 radians. If expr is not in the interval -1 to +1, asin returns the value zero and sets errno to EDOM (a domain error). Example This example prints “The arc sine is 1.570796.
assert Reference to Library Calls assert The assert macro enables you to insert run-time diagnostics, or assertions, into your program. After developing and debugging your program, you can disable the assertions by defining the identifier NDEBUG as a preprocessor symbol before including the asserth header. #include void assert(int expr); expr determines whether an invocation of assert generates a diagnostic message and terminates the program.
Reference to Library Calls atan atan The atan function computes the arc tangent of its argument. #include double atan(double expr); expr is an expression of type double. Return Value is the arc tangent of expr, expressed as a double value in the range -pi/2 to +pi/2 radians. Example This example prints “The arc tangent is 0.927295 radians.” #include #include int main(void) { double r, x, y, t; x = 4.0; y = 3.0; t = x/y; r = atan(t); printf ("The arc tangent is %f radians.
atan2 Reference to Library Calls atan2 The atan2 function computes the arc tangent of the quotient of its arguments. #include double atan2(double divid, double divis); divid is an expression of type double, specifying the dividend. divis is an expression of type double, specifying the divisor. Return Value is the arc tangent of (divid/divis), expressed as a double value in the range -pi to +pi radians.
Reference to Library Calls atexit atexit The atexit function registers a function for the run-time library to call at normal program termination. #include int atexit(void (*function)(void)); function(void) points to the function you want to register for execution at normal program termination. Return Value is zero if atexit successfully registers the function; otherwise, atexit returns a nonzero value.
atof Reference to Library Calls atof The atof function converts a string to a value of type double. #include double atof(const char *str_ptr); str_ptr points to the string to convert. Return Value is the floating-point value of the string *str_ptr, expressed as a double value. atof returns a value of zero if the first nonspace character in *str_ptr is not a sign, a decimal digit, or a decimal point.
Reference to Library Calls atoi atoi The atoi function converts a string to a value of type int. #include int atoi(const char *str_ptr); str_ptr points to the string to convert. Return Value is the numeric value of the string *str_ptr, expressed as an int value, atoi returns a value of zero if the first nonspace character in *str_ptr is not a sign or a decimal digit.
atol Reference to Library Calls atol The atol function converts a string to a value of type long. #include long atol( const char *str_ptr); str_ptr points to the string to convert. Return Value is the numeric value of the string *str_ptr, expressed as a long value, atol returns a value of zero if the first nonspace character in *str_ptr is not a sign or a decimal digit.
Reference to Library Calls bsearch bsearch The bsearch function searches an array of elements for an element matching a specified value. #include void *bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *)); key points to the value to match. base points to the first element in the array. nmemb specifies the number of elements in the array. size specifies the size in bytes of each element.
calloc Reference to Library Calls calloc The calloc function allocates memory for an array of elements and sets the allocated memory to zeros. #include void *calloc(size_t num_elts, size_t size_of_elt); num_elts specifies the number of elements in the array. size_of_elt specifies the size in bytes of a single element of the array. Return Value points to the allocated array, expressed as a pointer to void. If an error occurs, calloc returns the pointer value NULL.
Reference to Library Calls ceil 2. This example allocates memory for a structure of 20 elements that are each the size of the structure name: #include int main(void) { struct name { char *last; char *first; } *s_ptr; s_ptr = (struct name *)calloc(20, sizeof(struct name)); } ceil The ceil function returns the smallest integer not less than the value of its argument. #include double ceil(double expr); expr is an expression of type double.
chvol (supplementary) Reference to Library Calls chvol (supplementary) The chvol function changes the default volume and subvolume names used to qualify partial file names. #include short chvol(char *volume); volume points to a string containing a valid volume and subvolume name. Return Value is zero if the operation is successful, or -1 if an error occurs. Usage Guidelines • • The run-time library expands all partial file names using the default volume and subvolume names.
Reference to Library Calls clearerr clearerr The clearerr function resets the end-of-file and error indicators of a file opened for ANSI I/O. #include void clearerr(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value none. Usage Guidelines • • The clearerr function might be implemented as a macro in a future release. The end-of-file and error indicators are reset only when you open the file or explicitly call the clearerr, edfseek, fseek, or rewind function.
clock Reference to Library Calls clock The clock function determines how much processor time is used by the calling process up to the point that the process invokes the clock function. #include clock_t clock(void); Return Value is the process execution time of the CPU for this process. The time is given in microseconds. Usage Guidelines • 3- 18 The clock function returns the time in microseconds. This returned value can be divided by CLOCKS_PER_SEC to convert it to seconds.
Reference to Library Calls close (supplementary) close (supplementary) The close function closes a file opened for alternate I/O. #include int close(int file_des); file_des is the descriptor denoting a file opened for alternate I/O. Return Value is zero if the operation is successful, or -1 if an error occurs. Usage Guidelines • You must call the close function when you finish using a file. Example This example closes the file $a.b.
cos Reference to Library Calls cos The cos function computes the cosine of its argument. #include double cos(double expr); expr is an expression of type double, specifying an angle in radians. Return Value is the cosine of expr, expressed as a double value. Example This example prints “The cosine is 0.540302.” #include #include int main(void) { double r, x; x = -1.0; r = cos(x); printf ("The cosine is %f.
Reference to Library Calls creat (supplementary) cosh The cosh function computes the hyperbolic cosine of its argument. #include double cosh(double expr); expr is an expression of type double. Return Value is the hyperbolic cosine of expr, expressed as a double value. If the computation causes an overflow, cosh returns the value HUGE_VAL. Usage Guidelines • If expr has too great a magnitude, cosh sets errno to ERANGE (a range error). Example This example prints “The hyperbolic cosine is 1.
ctime Reference to Library Calls security specifies the security setting. See the FUP SECURE command description of integer encoding in the FUP Reference Manual for more information. pext specifies the number of pages (2048-byte blocks) in the primary extent; it must be in the range 1 through 65,535. If you omit pext, then creat uses the value 2. sext specifies the number of pages in each of the secondary extents; it must be in the range 1 through 65,535. If you omit sext, then creat uses the value 16.
Reference to Library Calls ctime timer points to the calendar time. Return Value is a pointer to the string. Usage Guidelines • The ctime function is equivalent to: asctime(localtime(*timer)); • Later calls to asctime and ctime overwrite the string. Refer to “asctime” on page 3-3 for more details. Examples 1. This example converts the calendar time pointed to by &now to local time in the form of a string.
dec_to_longlong (supplementary) Reference to Library Calls dec_to_longlong (supplementary) The dec_to_longlong function converts the SQL DECIMAL value stored in a C array of decimal to a C long long value. #include int dec_to_longlong(decimal *dec_ary, int chr_count, long long *ll_val); dec_ary points to the first character of the decimal array that contains the SQL DECIMAL value to convert. chr_count specifies the number of valid DECIMAL characters in *dec_ary.
Reference to Library Calls div difftime The difftime function computes the difference between two calendar times: time1 - time2. #include double difftime(time_t time1, time_t time2); time1 specifies a calendar time, and is of type type_t. Type type_t is defined in the header timeh. time2 specifies another calendar time, and is also of type type_t. Return Value is the difference time1 - time2. The difference is expressed in seconds as a floatingpoint number of type double.
ecvt (supplementary) Reference to Library Calls ecvt (supplementary) The ecvt function converts a numeric value to a string. #include char *ecvt(double value, short ndig, short *dec, short *sign); value is the value to convert. ndig is the number of digits in the converted string. Because the converted string does not include a sign or a decimal point, ndig does not include them in its count of digits.
Reference to Library Calls edfseek (supplementary) Example This example prints “num = -123.45670”: #include #include int main(void) { double num; int dp; int sign; char *string; int i; num = -123.4567; string = ecvt(num, 8, &dp, &sign); printf("num = "); if(sign != 0) printf("-"); /* print integer part of number */ for(i=0;i
edfseek (supplementary) Reference to Library Calls pos_base is one of the following alternatives: • • • SEEK_SET indicates that pos is a line number. The file is positioned at the first line whose line number is greater than or equal to the line number requested. SEEK_CUR indicates that pos is the number of lines from the file-position indicator; pos can be positive or negative. SEEK_END indicates that pos is the number of lines from the end of the file; pos can be either zero or negative.
Reference to Library Calls edftell (supplementary) edftell (supplementary) The edftell function retrieves the file-position indicator of an Edit file opened for ANSI I/O. #include long edftell(FILE *stream); stream denotes an Edit file opened for ANSI I/O. Return Value is the file-position indicator of the Edit file, expressed as a long value. This value is the Edit line number multiplied by 1000. For example, 23000L corresponds to line 23, and 44120L corresponds to line 44.12.
edlseek (supplementary) Reference to Library Calls edlseek (supplementary) The edlseek function sets the file-position indicator of an Edit file opened for alternate I/O to the beginning of the line that you request. #include long edlseek(short file_des, long pos, short pos_base); file_des is the descriptor denoting an Edit file opened for alternate I/O. pos specifies the desired file position. Depending on pos_base, the file position is either a line number or a line offset.
Reference to Library Calls exit exit The exit function writes to open files any data left in the buffers, closes files, and terminates execution of your C program. #include void exit(int status); status specifies the termination alternatives: • • • If the status value is zero, the compiler translates it to EXIT_SUCCESS which indicates normal termination. If the status value is less than zero, the compiler translates it to EXIT_FAILURE which indicates abnormal termination.
exp Reference to Library Calls exp The exp function computes the exponential function (base e) of its argument. #include double exp(double expr); expr is an expression of type double, specifying the power to which e is raised. Return Value is the exponential (e raised to the power) of expr, expressed as a double value. If the computation causes an overflow or underflow, exp returns the value HUGE_VAL or the value zero, respectively. In these cases, exp also sets errno to ERANGE (a range error).
Reference to Library Calls fabs fabs The fabs function computes the absolute value of its floating-point argument. #include double fabs(double expr); expr is an expression of type double. Return Value is the absolute value of expr, expressed as a double value. Example This example prints “The absolute value of -25.000000 is 25.000000.” #include #include int main(void) { double x, r; x = -25; r = fabs(x); printf("The absolute value of %f is %f.
fclose Reference to Library Calls fclose The fclose function closes a file opened for ANSI I/O and writes any data in the buffer to the file. #include int fclose(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value is zero if the operation is successful or the value EOF if an error occurs. Usage Guidelines • • If the file was written to, fclose writes any data in the buffer to the file.
Reference to Library Calls fcntl (supplementary) fcloseall (supplementary) The fcloseall function closes all files opened for ANSI I/O and alternate I/O, including stdin, stdout, and stderr. #include void fcloseall(void); Usage Guidelines • • If one of the files was written to, fcloseall writes any data in the buffer to the file. Whenever a program calls the exit function or returns from main, C closes all open files automatically.
fcntl (supplementary) Reference to Library Calls Return Value depends upon command: • • • • For F_GETFL, fcntl returns the file open-option flags. For F_GETDTYPE, fcntl returns the device type of the file. For F_GETFCODE, fcntl returns the file code if the file is a disk file, or -1 if it is not. For all others, fcntl returns 1 if the operation is successful, or -1 if an error occurs.
Reference to Library Calls fdopen (supplementary) fdopen (supplementary) The fdopen function opens a file for ANSI I/O that was opened for alternate I/O. #include FILE *fdopen(int file_des, char *access); file_des is the descriptor denoting a file opened for alternate I/O. access points to a string that specifies how you want to access the new file. Refer to “fopen” on page 3-48 for the possible values of *access.
fdtogfn (supplementary) Reference to Library Calls fdtogfn (supplementary) The fdtogfn function retrieves the file number of a file opened for alternate I/O. #include short fdtogfn(short file_des); file_des is the descriptor denoting a file opened for alternate I/O. Return Value is the Guardian file number of the file or -1 if file_des does not represent an open file. Example This example returns the file number of the file $a.b.
Reference to Library Calls feof feof The feof function checks whether the file-position indicator of a file opened for ANSI I/O is at the end of the file. #include int feof(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value is nonzero if the file-position indicator is at the end of the file; otherwise, feof returns a zero. Usage Guidelines • The feof function might be implemented as a macro in a future release.
ferror Reference to Library Calls ferror The ferror function checks the error indicator of a file opened for ANSI I/O. #include int ferror(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value is nonzero if an error occurred when reading or writing the file; otherwise, ferror returns a zero. Usage Guidelines • • • • • The ferror function might be implemented as a macro in a future release.
Reference to Library Calls fflush fflush The fflush function writes to disk any data that is in the buffer of a file opened for ANSI I/O. #include int fflush(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value is zero if the operation is successful or nonzero if an error occurs. Usage Guidelines • • If you pass NULL as the argument to fflush, the C compiler flushes all files currently opened for ANSI I/O.
fgetc Reference to Library Calls fgetc The fgetc function retrieves the next character from a file opened for ANSI I/O. #include int fgetc(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value is the character retrieved from the file. If fgetc encounters the end of the file or an error, it returns the value EOF. To distinguish between these two cases, use the feof or ferror function. Example This example returns the next character from the file $a.b.
Reference to Library Calls fgetpos fgetpos The fgetpos function gets the current value of the file-position indicator for the file associated with stream and stores it in the variable pointed to by pos. The stored value can be used later by the fsetpos function to reset the file-position indicator. #include int fgetpos(FILE *stream, fpos_t *pos); stream points to the file of which the fgetpos function ascertains the current value of the file-position indicator.
fgets Reference to Library Calls fgets The fgets function reads a string from a file opened for ANSI I/O. #include char *fgets(char *str_ptr, int str_size, FILE *stream); str_ptr points to the string where fgets stores the input. str_size specifies the size in bytes of *str_ptr. fgets reads up to str_size - 1 characters. stream denotes a file opened for ANSI I/O. Return Value is str_ptr if the operation is successful.
Reference to Library Calls fileno (supplementary) fileno (supplementary) The fileno function retrieves the file descriptor of a file opened for ANSI I/O. #include int fileno(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value is the file descriptor if *stream refers to an open file; otherwise, fileno returns the value -1.
floor Reference to Library Calls floor The floor function computes the largest integer not greater than its argument. #include double floor(double expr); expr is an expression of type double. Return Value is the largest integer not greater than expr, expressed as a double value. Example This example prints “The floor value of 1.090000 is 1.000000.”: #include #include int main(void) { double x, r; x = 1.09; r = floor(x); printf("The floor value of %f is %f.
Reference to Library Calls fmod fmod The fmod function computes the floating-point remainder of the division of its arguments. #include double fmod(double divid, double divis); divid is an expression of type double, specifying the dividend. divis is an expression of type double, specifying the divisor. Return Value is the floating-point remainder of the division of (divid/divis), expressed as a double value with the same sign as divid and a magnitude less than divis.
fopen Reference to Library Calls fopen The fopen function opens a file for ANSI I/O. #include FILE *fopen(const char *file_name, const char *access_mode); file_name points to a string containing a valid file name. access_mode points to a string that specifies how you want to access the file. The possible values for *access_mode are described under “Usage Guidelines.
Reference to Library Calls fopen Usage Guidelines • The possible values of the string *access_mode are: "r" Open an existing text file for read-only access. "w" Create a text file (or truncate an existing text file to length zero) and open it for write-only access. "a" Create a text file (or open an existing text file) and open it for append (write at the end of the file) access. "r+" Open an existing text file for update access (reading and writing).
fopen_std_file (supplementary) Reference to Library Calls Example This example opens a file named $a.b.c for update (reading and writing): #include FILE *fp; fp = fopen("$a.b.c", "r+"); fopen_std_file (supplementary) The fopen_std_file function opens a standard file stdin, stdout, or stderr if the file was not opened automatically because the NOSTDFILES pragma was specified or because the main function was not written in the C language.
Reference to Library Calls fprintf fprintf The fprintf function writes formatted data to a file opened for ANSI I/O. #include int fprintf(FILE *stream, const char *format, [expr...]); stream denotes a file opened for ANSI I/O. format points to a string that specifies how to format the data given by expr.... This format string is described under “Usage Guidelines.” expr... is a list of expressions whose values fprintf formats using *format and then prints to *stream.
fprintf Reference to Library Calls • precision is an optional decimal number that specifies the precision used when formatting the converted value. How fprintf uses this number depends upon the conversion code that follows it: • • • • For codes d, i, o, u, x, and X, precision is the minimum number of digits to print. For codes e, E, and f, precision is the number of digits to print following the decimal point. For codes g and G, precision is the maximum number of significant digits.
Reference to Library Calls • fprintf Conversion Modifiers Here are the possible values of modifier in a conversion specifier: • h For conversion codes d, i, o, u, x, and X, the h modifier indicates that the value is a short int, not an int. For conversion code n, the h modifier indicates that the value is a pointer to short int, not a pointer to int. l For conversion codes d, i, o, u, x, and X, the l modifier indicates that the value is a long int, not an int.
fprintf Reference to Library Calls n stores the number of characters printed thus far in the variable of type int that is referenced by the argument. The argument must have type pointer to int. o formats an int argument as an unsigned octal integer. p formats the value of a pointer to void argument using the format specified by the x conversion code. s formats the data referenced by a pointer to char argument as a string of characters.
Reference to Library Calls fputc fputc The fputc function writes a character to a file opened for ANSI I/O. #include int fputc(int character, FILE *stream); character is the character that is sent to the file. stream denotes a file opened for ANSI I/O. Return Value is the character written if the operation is successful; otherwise, fputc returns the value EOF. Example In this example, the fputc function writes a character to the file $a.b.
fputs Reference to Library Calls fputs The fputs function writes a string to a file opened for ANSI I/O. #include int fputs(const char *str_ptr, FILE *stream); str_ptr points to an array of characters. stream denotes a file opened for ANSI I/O. Return Value is the value EOF if an error occurs. Usage Guidelines • The fputs function writes characters from a string to a file until it encounters a null character. It does not write a newline character following the string.
Reference to Library Calls fread fread The fread function reads data blocks from a file opened for ANSI I/O and then stores the data blocks in an array. #include size_t fread(void *dest_ptr, size_t block_size, size_t block_count, FILE *stream); dest_ptr points to the array where fread stores the input blocks. block_size specifies the size in bytes of the blocks. block_count specifies the number of blocks to read. stream denotes a file opened for ANSI I/O.
free Reference to Library Calls free The free function releases a block of memory that you have allocated using calloc, malloc, or realloc. #include void free(void *blk_ptr); blk_ptr points to the block of memory to release. It must point to the first byte of the block returned by calloc, malloc, or realloc. Return Value none. Usage Guidelines • Attempts to free a block not allocated by calloc, malloc, or realloc cause an error when detected. Examples 1.
Reference to Library Calls freopen freopen The freopen function opens a file for ANSI I/O by reusing an existing file pointer. It first attempts to close the file (if any) that is already associated with the existing file pointer. #include FILE *freopen(const char *file_name, const char *access, FILE *stream); file_name points to a string that contains a valid file name, specifying the file that freopen is to open. access points to a string that specifies how you want to access the new file.
freopen Reference to Library Calls Example In this example, the freopen function automatically closes $a.b.c and attaches a new file named, $a.b.c to the same file pointer: #include FILE *fp; FILE *fpr; fp = fopen("$a.b.c", "r"); /* ... */ fpr = freopen("$a.b.
Reference to Library Calls fscanf frexp The frexp function splits a floating-point number into a normalized fraction and an integral power of 2. #include double frexp(double expr, int *binary_power); expr is an expression of type double. binary_power points to the variable of type int where frexp stores the integral power of 2. If expr is zero, the power of 2 is also zero. Return Value is the normalized fraction, expressed as a double value. If expr is zero, frexp returns the value zero.
fscanf Reference to Library Calls stream denotes a file opened for ANSI I/O. format points to a string that specifies how to convert the input text for assignment, using subsequent arguments as pointers to the variables to receive the converted input. This format string is described in the next subsection, “Usage Guidelines.” obj_ptr... is a list of pointers to variables, specifying where the results of the conversions defined in *format are to be stored.
Reference to Library Calls • fscanf Conversion Specifiers The format of a conversion specifier is: % [*] [width] [modifier] conv_code The percent sign indicates the start of a conversion specifier. Here are the components that follow it: • * Is the suppression flag; it specifies that the converted value should be discarded and not stored in the next variable referenced by *obj_ptr.... width Is an optional decimal number that specifies the maximum field width.
fscanf Reference to Library Calls • Conversion Codes As mentioned earlier, conv_code determines both how fscanf scans the input data and what type of value it converts that data to. This list shows the conversion codes and describes the scanning technique and data conversion specified by each code. 3- 64 c matches a sequence of width characters (1 if width is omitted).
Reference to Library Calls % fscanf matches a literal percent sign in the input; for example: count=fscanf(fp, “Stock went up %d%% ”, &increase); [ • introduces a scan set, which is a list of expected characters. The scan set consists of all characters between the left bracket [ and its matching right bracket ], which is the end of the conversion code. If the character following the left bracket is a circumflex (^), fscanf reads input until it encounters one of the characters in the scan set.
fseek Reference to Library Calls fseek The fseek function sets the file-position indicator of a byte-addressable file opened for ANSI I/O. #include int fseek(FILE *stream, long pos, int pos_base); stream denotes a file opened for ANSI I/O. pos specifies the desired file position. pos_base is one of the following alternatives: • • • SEEK_SET indicates that pos is the number of characters from the beginning of the file.
Reference to Library Calls fsetpos Example In this example, the fseek function sets the file-position indicator to the beginning of the file: #include FILE *fp; int status; long pos; fp = fopen("$a.b.c", "r+"); /* ... */ pos = 0; status = fseek(fp, pos, SEEK_SET); fsetpos The fsetpos function sets the file-position indicator for the file pointed to by stream to the value pointed to by pos. This value was obtained from an earlier call to the fgetpos function on the same file.
ftell Reference to Library Calls ftell The ftell function retrieves the file-position indicator of a byte-addressable file opened for ANSI I/O. This file-position indicator corresponds to the current byte offset from the beginning of the file. #include long ftell(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value is the file-position indicator, expressed as a long value. Example In this example, the ftell function returns the file-position indicator of $a.b.
Reference to Library Calls fwrite fwrite The fwrite function writes contiguous blocks of data to a file opened for ANSI I/O. #include size_t fwrite(const void *first_block, size_t block_size, size_t block_count, FILE *stream); first_block points to the first block of data to be written. block_size specifies the size (in bytes) of each block to be written. block_count specifies the number of blocks to be written. stream denotes a file opened for ANSI I/O.
get_assign_msg (supplementary) Reference to Library Calls get_assign_msg (supplementary) The get_assign_msg function retrieves a specified assign message. You define which assign message is retrieved by specifying the ordinal number that corresponds to the desired message’s position in the series of assign messages for a particular process.
Reference to Library Calls get_assign_msg (supplementary) Usage Guidelines • The type assign_msg_type is declared in the header stdlibh as: typedef struct { short msg_code; struct { char prognamelen; char progname[31]; char filenamelen; char filename [31]; } logical_unit_name; unsigned long field_mask; union { char whole[24]; struct { char volume[8]; char subvolume[8]; char file [8]; } parts; } filename; short primary_extent; short secondary_extent; short file_code; short exclusion_spec; short access_sp
get_assign_msg (supplementary) • Reference to Library Calls For portability, programs can specify logical units, such as TAPEFILE or PRINTER, instead of the names of actual files or devices. The TACL ASSIGN command, or the #ASSIGN built-in variable, associates a specific file or device with a given logical unit to represent that actual entity when you run the program.
Reference to Library Calls get_assign_msg_by_ name (supplementary) get_assign_msg_by_ name (supplementary) The get_assign_msg_by_name function retrieves the assign message that corresponds to the logical-unit name requested. #include short get_assign_msg_by_name(char *assign_name, assign_msg_type *assign_msg); assign_name points to the NULL terminated logical-unit name. assign_msg points to a structure of type assign_msg_type that is declared in the header stdlibh.
get_assign_msg_by_ name (supplementary) Reference to Library Calls Usage Guidelines • The type assign_msg_type is declared in the header stdlibh as: typedef struct { short msg_code; struct { char prognamelen; char progname[31]; char filenamelen; char filename [31]; } logical_unit_name; unsigned long field_mask; union { char whole[24]; struct { char volume[8]; char subvolume[8]; char file [8]; } parts; } filename; short primary_extent; short secondary_extent; short file_code; short exclusion_spec; short
Reference to Library Calls • get_assign_msg_by_ name (supplementary) For portability, programs can specify logical units, such as TAPEFILE or PRINTER, instead of the names of actual files or devices.
get_max_assign_msg_ordinal (supplementary) Reference to Library Calls get_max_assign_msg_ordinal (supplementary) The get_max_assign_msg_ordinal function determines how many assign messages are assigned to a particular process. #include short get_max_assign_msg_ordinal(void); Return Value is the number of assign messages that exist for a particular process. Usage Guidelines • To determine the number of assign messages, the get_max_assign_msg_ordinal function begins counting at 1.
Reference to Library Calls get_param_by_name (supplementary) param_name points to the NULL terminated name of the parameter. param_value points to the NULL terminated value assigned to the parameter name. max_len is the maximum length of the NULL terminated string that can be copied to param_value. This string is the parameter value.
get_param_msg (supplementary) Reference to Library Calls get_param_msg (supplementary) The get_param_msg function retrieves the param message. #include short get_param_msg(param_msg_type *param_msg, short *actual_len); param_msg points to a structure of type param_msg_type that is declared in the header stdlibh. See “Usage Guidelines” for more details regarding this type. The get_param_msg function copies the param message into the structure pointed to by this param_msg parameter.
Reference to Library Calls get_startup_msg (supplementary) get_startup_msg (supplementary) The get_startup_msg function retrieves the process startup message. #include short get_startup_msg(startup_msg_type *startup_msg, short *actual_len); startup-msg points to a structure of type startup_msg_type that is declared in the header . See “Usage Guidelines” on page 3-80 for more details regarding this type.
get_startup_msg (supplementary) Reference to Library Calls Usage Guidelines • The type startup_msg_type is declared in the header stdlibh as: typedef struct { short msg_code; union { char whole[16]; struct { char volume[8]; char subvolume[8]; } parts; } defaults; union { char whole[24]; struct { char volume[8]; char subvolume[8]; char file[8]; } parts; } infile; union { char whole[24]; struct { char volume[8]; char subvolume[8]; char file[8]; } parts; } outfile; char param[530]; } startup_msg_type; •
Reference to Library Calls get_startup_msg (supplementary) Examples 1. The C RUN command can have the form C/ IN in_file_name, OUT out_file_name/ c_object_file; pragma, pragma The startup message reflecting this command has the following components: msg_code -1 defaults user’s default volume and subvolume infile in_file_name outfile out_file_name char param[] c_object_file, pragma, pragma 2.
getc Reference to Library Calls getc The getc function reads a character from a file opened for ANSI I/O. #include int getc(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value is the character retrieved from the file. If getc encounters the end of the file or an error, it returns the value EOF. To distinguish between these two cases, use the feof or ferror function. Usage Guidelines • The getc function might be implemented as a macro in a future release.
Reference to Library Calls getenv getenv The getenv function retrieves the value of a run-time parameter from the environment array. #include char *getenv(const char *env_parm); env_parm points to a string containing the name of the run-time parameter whose value you want to retrieve. This string must be in uppercase. Possible values for *env_parm are described under “Usage Guidelines.” Return Value is the value of the run-time parameter you specified in *env_parm.
gets Reference to Library Calls gets The gets function reads a string from the standard input file, stdin. #include char *gets(char *str_ptr); str_ptr points to the string where gets stores the input string. Return Value is str_ptr if the operation is successful. If gets encounters the end of the file or an error, it returns the pointer value NULL. To distinguish between these two cases, use the feof or ferror function.
Reference to Library Calls gmtime gmtime The gmtime function converts the calendar time pointed to by timer to a broken-down time, and stores the broken-down time in a structure of type struct tm that is provided for you. The gmtime function returns the address of the structure. #include struct tm *gmtime(const time_t *timer); timer points to the calendar time. Return Value points to the structure of type struct tm that contains the Coordinated Universal Time (UTC).
heap_check (supplementary) Reference to Library Calls heap_check (supplementary) The heap_check function checks the consistency of the run-time heap used by the memory-management functions calloc, free, malloc, and realloc. #include void heap_check(void); Usage Guidelines • If heap_check discovers an inconsistency in the run-time heap, it prints an error message to stderr and then calls exit with the argument EXIT_FAILURE.
Reference to Library Calls _is_system_trap (supplementary) heap_min_block_size (supplementary) The heap_min_block_size function suggests to the run-time library what the minimum block size should be when an allocation is made from the heap. #include void heap_min_block_size(long min_block_size); min_block_size specifies the number of bytes to be allocated.
isalnum Reference to Library Calls isalnum The isalnum function tests whether its argument is alphanumeric. #include int isalnum(int character); character specifies the character to test. Return Value is nonzero if character is an uppercase or lowercase character or a digit; otherwise, isalnum returns the value zero. Usage Guidelines • 3- 88 The character-testing routine isalnum is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
Reference to Library Calls isalpha isalpha The isalpha function tests whether its argument is alphabetic. #include int isalpha(int character); character specifies the character to test. Return Value is nonzero if character is an uppercase or lowercase character; otherwise, isalpha returns the value zero. Usage Guidelines • The character-testing routine isalpha is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
isascii (supplementary) Reference to Library Calls isascii (supplementary) The isascii function tests whether its argument is in the range 0 through 127. #include int isascii(int character); character specifies the character to test. Return Value is nonzero if character is in the range 0 through 127; otherwise, isascii returns the value zero.
Reference to Library Calls iscntrl iscntrl The iscntrl function tests whether its argument is a control character. #include int iscntrl(int character); character specifies the character to test. Return Value is nonzero if character is a control character; otherwise, iscntrl returns the value zero. Usage Guidelines • The character-testing routine iscntrl is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
iscsym (supplementary) Reference to Library Calls iscsym (supplementary) The iscsym function tests whether its argument is a valid character for a C identifier. #include int iscsym(int character); character specifies the character to test. Return Value is nonzero if character is a character that can be used in a C identifier; otherwise, iscsym returns the value zero.
Reference to Library Calls iscsymf (supplementary) iscsymf (supplementary) The iscsymf function tests whether its argument is valid as the first character of a C identifier. #include int iscsymf(int character); character specifies the character to test. Return Value is nonzero if character is a character that can start a C identifier; otherwise, iscsymf returns the value zero.
isdigit Reference to Library Calls isdigit The isdigit function tests whether its argument is a decimal digit. #include int isdigit(int character); character specifies the character to test. Return Value is nonzero if character is a decimal digit; otherwise, isdigit returns the value zero. Usage Guidelines • 3- 94 The character-testing routine isdigit is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
Reference to Library Calls isgraph isgraph The isgraph function tests whether its argument is a printable character other than a blank (“ ”). #include int isgraph(int character); character specifies the character to test. Return Value is nonzero if character is a printable character other than a blank; otherwise, isgraph returns the value zero.
islower Reference to Library Calls islower The islower function tests whether its argument is a lowercase letter. #include int islower(int character); character specifies the character to test. Return Value is nonzero if character is a lowercase letter; otherwise, islower returns the value zero. Usage Guidelines • 3- 96 The character-testing routine islower is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
Reference to Library Calls isprint isprint The isprint function tests whether its argument is a printable character. #include int isprint(int character); character specifies the character to test. Return Value is nonzero if character is a printable character; otherwise, isprint returns the value zero. Usage Guidelines • The character-testing routine isprint is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
ispunct Reference to Library Calls ispunct The ispunct function tests whether its argument is a punctuation character. #include int ispunct(int character); character specifies the character to test. Return Value is nonzero if character is a punctuation character; otherwise, ispunct returns the value zero. Usage Guidelines • 3- 98 The character-testing routine ispunct is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
Reference to Library Calls isspace isspace The isspace function tests whether its argument is a space character (a blank, tab, or newline). #include int isspace(int character); character specifies the character to test. Return Value is nonzero if character is a space character (a blank, horizontal or vertical tab, or newline); otherwise, isspace returns the value zero.
isupper Reference to Library Calls isupper The isupper function tests whether its argument is an uppercase letter. #include int isupper(int character); character specifies the character to test. Return Value is nonzero if character is an uppercase letter; otherwise, isupper returns the value zero. Usage Guidelines • 3- 100 The character-testing routine isupper is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
Reference to Library Calls isxdigit isxdigit The isxdigit function tests whether its argument is a hexadecimal digit. #include int isxdigit(int character); character specifies the character to test. Return Value is nonzero if character is a hexadecimal digit; otherwise, isxdigit returns the value zero. Usage Guidelines • The character-testing routine isxdigit is implemented as a macro, but the C compiler provides an underlying function with the same name as the macro.
labs Reference to Library Calls labs The labs function returns the absolute value of its argument. #include long labs(long expr); expr is an expression whose value has type long. Return Value is the absolute value of expr. Usage Guidelines • The absolute value of the most negative long integer (LONG_MIN) cannot be represented. Example This example prints “The absolute value of -100000 is 100000.
Reference to Library Calls ldexp ldexp The ldexp function multiplies a floating-point number by an integral power of 2. #include double ldexp(double expr1, int expr2); expr1 is an expression of type double. expr2 is an expression of type int. Return Value is the value expr1*2expr2. If an overflow occurs, ldexp returns the value HUGE_VAL. If an underflow occurs, it returns the value zero. In either of these cases, ldexp sets errno to ERANGE (a range error).
ldiv Reference to Library Calls ldiv The ldiv function computes the long quotient and long remainder that result from the integral division of its two long arguments. #include ldiv_t ldiv(long dividend, long divisor); dividend specifies the dividend, or numerator, of the integral division equation. divisor specifies the divisor, or denominator, of the integral division equation.
Reference to Library Calls localeconv localeconv The localeconv function returns a pointer to a structure of type lconv that contains information that reflects the rules of the current locale. The standard C locale is the only locale supported in this release.
localtime Reference to Library Calls localtime The localtime function converts the calendar time pointed to by timer into a brokendown local time, and stores this broken-down local time in a structure of type struct tm that is provided for you. The localtime function returns the address of the structure. Local time is the calendar time expressed for some specific time zone. #include struct tm *localtime(const time_t *timer); timer points to the calendar time.
Reference to Library Calls log10 log10 The log10 function computes the common (base 10) logarithm of its argument. #include double log10(double expr); expr is an expression of type double with a value greater than zero. Return Value is the base 10 logarithm of expr. If expr is less than or equal to zero, log10 returns the value HUGE_VAL and sets errno to EDOM (a domain error). Example This example prints “The base 10 log of 256.000000 is 2.408240.
longjmp Reference to Library Calls longjmp The longjmp function restores the calling environment saved by the most recent call to setjmp. #include void longjmp(jmp_buf env, int val); env is a buffer of type jmp_buf used in an earlier call to setjmp. val specifies the value longjmp is to cause its corresponding setjmp to return. If val is zero, the setjmp call returns the value 1, as zero is reserved by the run-time library. Return Value none.
Reference to Library Calls longlong_to_dec (supplementary) longlong_to_dec (supplementary) The longlong_to_dec function converts a long long value to an SQL DECIMAL value and stores the converted value in a C array of decimal. #include int longlong_to_dec(long long ll_val, decimal *dec_ary, int ary_size, int sign_type); ll_val specifies the long long value to convert. dec_ary points to the first character of the decimal array where longlong_to_dec stores the converted DECIMAL value.
longlong_to_dec (supplementary) Reference to Library Calls Usage Guidelines • • 3- 110 When longlong_to_dec returns a nonzero value to indicate that the conversion was not successful, the value stored in *dec_ary is undefined. For more information regarding the representation of SQL DECIMAL values in C arrays of decimal, refer to the NonStop SQL/MP Programming Manual for C.
Reference to Library Calls lseek (supplementary) lseek (supplementary) The lseek function sets the file-position indicator of a byte-addressable file opened for alternate I/O. #include long lseek(int file_des, long pos, int pos_base); file_des is the descriptor denoting a file opened for alternate I/O. pos is a long value specifying the desired position. pos_base specifies whether pos denotes an offset from the beginning, current position, or end of the file.
malloc Reference to Library Calls malloc The malloc function allocates memory starting on a word boundary. #include void *malloc(size_t nbytes); nbytes specifies the number of bytes to allocate. Return Value points to the allocated memory if the operation is successful; otherwise, malloc returns the pointer value NULL. Usage Guidelines • • • Note that malloc returns a pointer of type void, which is compatible with any pointer type.
Reference to Library Calls _max (supplementary) _max (supplementary) The _max macro expands to the greater of its two arguments. #include _max( expr1, expr2); is the type of expr1, expr2, and the return value. It can be any arithmetic type. expr1 is an expression. expr2 is an expression of the same type as expr1. Return Value is the numerically greater of the two arguments, expr1 and expr2.
mblen Reference to Library Calls mblen The mblen function determines the length in bytes of a multibyte character. #include int mblen(const char *s, size_t n); s points to the multibyte character. n defines the maximum length in characters of the multibyte character. Return Value If s is a null pointer, the return value is 0.
Reference to Library Calls mbstowcs mbstowcs The mbstowcs function converts a sequence of multibyte characters to a corresponding sequence of wide characters. #include size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n); pwcs points to the array that will contain the sequence of wide characters. s points to the array that contains the sequence of multibyte characters. No multibyte characters that follow a null character will be examined or converted.
mbtowc Reference to Library Calls mbtowc The mbtowc function converts a multibyte character to a wide character. The argument s points to the beginning of a multibyte character that is not more than n characters long. The function converts the character to its wide character representation, storing the result in the variable pointed to by pwc, if pwc is not a null pointer.
Reference to Library Calls memchr memchr The memchr function searches for the first occurrence of a byte value within a block of memory. #include void *memchr(const void *block, int value, size_t block_size); block points to the block to search. value is the value to search for; it is converted to an unsigned char before the search. block_size is the size in bytes of the block to search.
memcmp Reference to Library Calls memcmp The memcmp function performs an unsigned byte comparison of two blocks of memory. #include int memcmp(const void *block1, const void *block2, size_t cmp_count); block1 points to the first block to compare. block2 points to the second block to compare. cmp_size is the number of bytes to compare. Return Value is zero if the two blocks are equal, a negative value if *block1 is less than *block2, or a positive value if *block1 is greater than *block2.
Reference to Library Calls memcpy memcpy The memcpy function copies one block of memory to another. If the destination block overlaps the source block, memcpy does not preserve the data in the overlapping portion of the source block. #include void *memcpy(void *dest_blk, const void *source_blk, size_t copy_count); dest_blk points to the block to copy data to. source_blk points to the block to copy data from. copy_count is the number of bytes to copy. Return Value is dest_blk.
memmove Reference to Library Calls memmove The memmove function moves one block of memory to another. If the destination block overlaps the source block, memmove preserves the data in the overlapping portion of the source block. Consequently, memmove is slower than memcpy. #include void *memmove(void *dest_blk, const void *source_blk, size_t move_count); dest_blk points to the block to move data to. source_blk points to the block to move data from. move_count is the number of bytes to move.
Reference to Library Calls memswap (supplementary) memswap (supplementary) The memswap function exchanges the contents of two non-overlapping blocks of memory. #include void memswap(void *blk1, void *blk2, size_t swap_count); blk1 points to one of the blocks to swap. blk2 points to the other block to swap. swap_count is the number of bytes to swap. Return Value none.
_min (supplementary) Reference to Library Calls _min (supplementary) The _min macro expands to the lesser of its two arguments. #include _min( expr1, expr2); is the type of expr1, expr2, and the return value. It can be any arithmetic type. expr1 is an expression. expr2 is an expression of the same type as expr1. Return Value is the numerically lesser of the two arguments, expr1 and expr2. Example This example prints “The minimum number is 5.
Reference to Library Calls mktime mktime The mktime function converts the broken down local time in the structure pointed to by timeptr into the corresponding calendar time. #include time_t mktime(struct tm *timeptr); timeptr points to the structure that contains the broken-down time, expressed as local time. This structure is of type struct tm. Return Value is the specified calendar time encoded as a value of type time_t.
mktime Reference to Library Calls Example This example finds the date 1000 days from now.
Reference to Library Calls modf modf The modf function splits a floating-point number into integral and fractional parts. #include double modf(double expr, double *int_part); expr is an expression of type double. int_part points to the variable of type double where modf stores the integral part of expr. Return Value is the fractional part of expr. Example This example prints “The fractional part is 0.234000. The integral part is 1.000000.
movmem (supplementary) Reference to Library Calls movmem (supplementary) The movmem function moves a block of memory. It performs the move so that data is preserved even if the source block overlaps the destination block. #include void movmem(char *blk_ptr, char *dest_ptr, size_t nbytes); blk_ptr points to the beginning of the block. dest_ptr points to the destination where movmem moves the block. nbytes specifies the number of bytes to move. Return Value none.
Reference to Library Calls __ns_backup_fopen (supplementary) Return Value 0 if the operation is successful, -1 if an error occurs. Usage Guidelines • • • • • • • • • • • • This function is called from the backup process to perform a backup open of the file. Before calling this function, the primary process must have first called the __ns_fget_file_open_state function to retrieve the file open state information and sent the state information through the $RECEIVE facility to the backup process.
__ns_fget_file_open_state (supplementary) Reference to Library Calls __ns_fget_file_open_state (supplementary) The __ns_fget_file_open_state function returns the file open state information for a file open for ANSI I/O. #include long __ns_fget_file_open_state( FILE *stream, __ns_std_io_file_open_state *file_open_state); stream denotes a file opened for ANSI I/O. file_open_state points to a variable that stores the file open state information.
Reference to Library Calls __ns_fget_file_state (supplementary) __ns_fget_file_state (supplementary) The __ns_fget_file_state function returns the state information for a file open for ANSI I/O. #include long __ns_fget_file_state( FILE *stream, __ns_std_io_file_state *file_state); stream denotes a file opened for ANSI I/O. file_state points to a variable that stores the file state information. Return Value 0 if the operation is successful, -1 if an error occurs.
__ns_fopen_special (supplementary) • • • • • • • Reference to Library Calls For output streams, a call to a write function in user code might leave a partially filled, unflushed buffer. To ensure that the buffer is flushed, you can: Perform a flush operation, such as a call to the fflush function, prior to calling the __ns_fget_file_state function. Ignore the effects of unflushed buffers, if the unflushed buffer contents are not critical to the application.
Reference to Library Calls __ns_fopen_special (supplementary) Usage Guidelines • • If you want to specify the sync depth, call the __ns_fopen_special function from primary process instead of the fopen function. Otherwise, __ns_fopen_special operates the same as the fopen function. For buffered file operations, a call to a write function in user code does not necessarily correspond to one write operation at the operating system level where the sync-depth value is meaningful.
__ns_fset_file_state (supplementary) Reference to Library Calls When you open a file in append mode, the file-position indicator is set to the end of the file before each write operation, regardless of previous positioning. • If you include a system name in the file name, you must precede the system name with two backslashes instead of one because backslash is an escape character in C. For example, to open the file \sys.$vol.svol.file, you would use the C string: "\\sys.$vol.svol.
Reference to Library Calls __ns_fset_file_state (supplementary) Return Value 0 if the operation is successful, -1 if an error occurs. Usage Guidelines • • • • • This function is called from the backup process to update its state information for the file. Before calling this function, the primary process must have first called the __ns_fget_file_state function to retrieve the file state information and sent the state information through the $RECEIVE facility to the backup process.
__ns_start_backup (supplementary) Reference to Library Calls __ns_start_backup (supplementary) The __ns_start_backup function creates a backup process for the primary process. #include _extensible long __ns_start_backup( short *error_detail, short backup_cpu, short *backup_process_handle, char *backup_hometerm, short backup_debug_options); error_detail is an optional output parameter that receives the error detail information from the Guardian procedure PROCESS_CREATE_.
Reference to Library Calls __ns_start_backup (supplementary) Usage Guidelines • • This function is called from the primary process to create and initialize the backup process. To create the backup process, __ns_start_backup: • • • • • • • • • • Returns the process handle of the backup process, if the process started successfully. To initialize the backup process, __ns_start_backup: • • Starts the backup process with a call to the PROCESS_CREATE_ Guardian procedure.
offsetof • • • Reference to Library Calls In addition to either the CLARGE or CWIDE library file, you must bind the CNONSTOP library file into programs that use this function. This function can only be used in the Guardian environment. Refer to the Guardian Programmer’s Guide for complete details on fault-tolerant programming in C. offsetof The offsetof macro expands to the offset in bytes of a structure member from the start of its structure.
Reference to Library Calls open (supplementary) open (supplementary) The open function opens a file for alternate I/O. #include int open(char *file_name, int flags, [int security], [int depth], [int pext], [int sext]); file_name points to a string containing a valid Guardian file name. flags is an integer value specifying the attributes of the file. Possible attribute values are described under “Usage Guidelines.” security specifies the security setting.
open (supplementary) Reference to Library Calls Usage Guidelines • • The following macros specify the possible attributes for flags. Select the attributes that represent attributes of the file to be opened. To specify more than one option, use the bit-wise OR operator (|). Macro Description O_APPEND Sets the file-position indicator to the end of the file before each write. O_BINARY Opens the file for binary I/O. O_CREAT Creates the file if it does not exist.
Reference to Library Calls • • • perror This function sets the file-position indicator to the start of the file (assuming that the file is successfully opened). For more information regarding file extents and pages, refer to the ENSCRIBE Programmer’s Guide. This manual does not include a discussion about waited I/O and nowait I/O because the C programming language does not provide this capability. For waited and nowait I/O, you must use Guardian system procedures.
pow Reference to Library Calls pow The pow function computes the value of its first argument raised to the power of its second argument. #include double pow(double expr1, double expr2); expr1 is an expression of type double. expr2 is an expression of type double, specifying the power to which to raise expr1. Return Value is the value of expr1 raised to the expr2 power (that is, expr1expr2).
Reference to Library Calls printf printf The printf function writes formatted data to the standard output file. #include int printf(const char *format, [expr...]); format points to a string that contains characters and conversion specifiers. Refer to “fprintf” on page 3-51 for a description of format and conversion specifiers. expr... is the list of arguments to be formatted using the conversion specifiers in *format.
printf Reference to Library Calls Example In this example, printf fetches two arguments, formats them as fixed-decimal floatingpoint numbers, and prints “The square root of 25.000000 is 5.
Reference to Library Calls putc putc The putc function writes a character to a file opened for ANSI I/O. #include int putc(int character, FILE *stream); character specifies the character to be written. stream denotes a file opened for ANSI I/O. Return Value is the character written if the operation is successful; otherwise, putc returns the value EOF. Usage Guidelines • • The putc function might be implemented as a macro in a future release.
putchar Reference to Library Calls putchar The putchar function writes a character to the standard output file. #include int putchar(int character); character specifies the character to be written. Return Value is the character written if the operation is successful; otherwise, putchar returns the value EOF. Usage Guidelines • The putchar function might be implemented as a macro in a future release.
Reference to Library Calls putenv putenv The putenv function sets the value of a run-time parameter from the environment array. #include int putenv(const char *env_parm); env_parm points to a string of the form name=value. name is the run-time parameter to set and value is the value to set the parameter to. This string must be in uppercase. Possible values for *env_parm are described under “Usage Guidelines.
puts Reference to Library Calls puts The puts function writes a string to the standard output file. #include int puts(const char *str_ptr); str_ptr points to an array of characters. Return Value is zero if the call is successful. Otherwise, a nonzero value is returned. Usage Guidelines • The puts function writes characters from the string to the standard output file until it encounters a null character. The function does not write the null character, but it does write a newline character.
Reference to Library Calls qsort qsort The qsort function sorts an array of elements in ascending order using a specified comparison routine. #include void qsort(void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *)); base points to the first element in the array to sort. nmemb specifies the number of elements in the array. size specifies the size in bytes of the array elements.
raise Reference to Library Calls raise The raise function causes the indicated signal to be raised in the current process. #include int raise(int sig); sig is the signal to be raised. Return Value is zero if the call is successful. Otherwise, a nonzero value is returned. Usage Guidelines • The ISO C Standard defined signals SIGABRT, SIGINT, and SIGTERM can only be generated by an explicit call to the raise function. The signal handler SIG_IGN can be registered for these signals.
Reference to Library Calls rand rand The rand function generates a pseudo-random number. #include int rand(void); Return Value is a pseudo-random value in the range 0 through 32767. Usage Guidelines • You can call srand to reset the pseudo-random sequence generator to a new starting point. See “srand” on page 3-171 for more information. Example This example generates a pseudo-random number and places it in x: #include /* ... */ int x; x = rand(); /* ...
read (supplementary) Reference to Library Calls read (supplementary) The read function reads a number of bytes from a file opened for alternate I/O, storing the input data in a buffer. #include short read(int file_des, char *buf, short nbytes); file_des is the descriptor denoting a file opened for alternate I/O. buf points to the buffer where read stores the input data. nbytes specifies the number of bytes to be read from the file.
Reference to Library Calls readupdate (supplementary) file_des is the descriptor denoting a file opened for alternate I/O. buf points to the string where readupdate stores the input message. read_bytes specifies the number of bytes to read. write_bytes specifies the number of bytes to write. Return Value depends upon the file type of file_des.
realloc Reference to Library Calls realloc The realloc function changes the size of a block of memory that you have allocated using malloc or calloc. #include void *realloc(void *str_ptr, size_t size); str_ptr points to an array of characters. size specifies the new size in bytes of the block of memory. Return Value points to the reallocated block of memory if the operation is successful; otherwise, realloc returns the pointer value NULL.
Reference to Library Calls rename remove The remove function purges a disk file. #include int remove(const char *file_name); file_name points to a string containing a valid Guardian file name. Return Value is zero if the operation is successful; otherwise, remove returns a nonzero value (and the file is not purged). Usage Guidelines • If the specified file is open, remove returns a nonzero value and does not close or purge the file. rename The rename function changes the name of a disk file.
reply (supplementary) Reference to Library Calls reply (supplementary) The reply function writes the response to a request made through the readupdate function. Requests and responses are messages that are read from the $RECEIVE files of two communicating processes. #include short reply(char *message, short write_count, [short message_tag], [short error_return]); message points to the string containing the reply message. write_count specifies the number of bytes to write from *message.
Reference to Library Calls repmem (supplementary) repmem (supplementary) The repmem function replicates values through memory; that is, it copies a small block of values (a template) repeatedly into a larger block of memory. #include void repmem(char *dest_blk, char *template, size_t tmpl_size, size_t rep_count); dest_blk points to the block of memory to fill. template points to the template to replicate through *dest_blk. tmpl_size specifies the size in bytes of the template.
rewind Reference to Library Calls rewind The rewind function resets the file-position indicator to the beginning of a C file opened for binary ANSI I/O. #include void rewind(FILE *stream); stream denotes a C file opened for binary ANSI I/O. Return Value none. Usage Guidelines • The rewind function might be implemented as a macro in a future release. Example This example resets the file-position indicator for the file $a.b.
Reference to Library Calls scanf scanf The scanf function reads formatted data from the standard input file, uses the format string to determine whether the data matches expectations and to determine the necessary conversions, and writes converted data to one or more supplied variables. #include int scanf(const char *format, [obj_ptr...
setbuf Reference to Library Calls setbuf The setbuf function attaches a user-supplied buffer to a file opened for ANSI I/O. This buffer is then used for all I/O buffering, thus freeing the system resources normally used for this purpose. #include void setbuf(FILE *stream, char *buffer); stream denotes a file opened for ANSI I/O. buffer points to the new file buffer. *buffer must accommodate at least BUFSIZ elements. Return Value none.
Reference to Library Calls setjmp setjmp The setjmp macro saves its calling environment in its argument for later use by the longjmp function. #include int setjmp(jmp_buf env); env is a buffer of type jmp_buf, where setjmp saves its calling environment. Return Value is zero from the direct invocation of setjmp. If the return results from a subsequent call to longjmp, the return value is determined by the val parameter in the longjmp call.
setlocale Reference to Library Calls setlocale The setlocale function sets the specified category to the named locale. The setlocale function can be used to change or query the program’s entire current locale or only portions of the current locale. #include char *setlocale(int category, const char *locale); category specifies the behavior to be changed.
Reference to Library Calls • setmem (supplementary) Most of the locale categories specify a portion of the locale to change or query. The sole exception is the LC_ALL category that specifies the entire locale.
setnbuf (supplementary) Reference to Library Calls setnbuf (supplementary) The setnbuf function disables buffering for a file opened for ANSI I/O. For an equivalent ANSI-standard function, refer to “setbuf” on page 3-158. #include void setnbuf(FILE *stream); stream denotes a file opened for ANSI I/O. Return Value none. Usage Guidelines • Once you call setnbuf, which disables buffering, all input and output operations on the specified file generate immediate I/O requests.
Reference to Library Calls setvbuf buf points to the new file buffer. The buffer that buf points to must accommodate at least BUFSIZ elements. mode indicates how stream will be buffered as follows: _IOFBF _IOLBF _IONBF I/O to be full buffered I/O to be line buffered I/O to be unbuffered The macros _IOFBF, _IOLBF, _IONBF are defined in the header stdioh. Full buffering (_IOFBF) is equivalent to line buffering (_IOLBF) as both will perform full buffering for a file opened for ANSI I/O.
signal Reference to Library Calls Example #include FILE *fp; char buf[BUFSIZ]; int ret_value; fp = fopen("$x.y.file1", "r+"); ret_value = setvbuf(fp, buf, _IOLBF, BUFSIZ); signal The signal function associates signal handlers with specific signals. #include void (*signal(int sig, void (*func) (int)))(int); sig is a specific signal. The signals are defined as symbolic constants in the header signalh such that an integer value is associated with each signal.
Reference to Library Calls signal Usage Guidelines • An exceptional condition, or signal, is generated by an abnormal event. For example, a floating point exception occurs when two very large floating point numbers are multiplied together. The exceptional conditions that can be handled by the operating system are defined as symbolic constants in the header signalh.
signal Reference to Library Calls • • The ANSI defined signals SIGFPE, SIGILL, and SIGSEGV correspond to the following operating system traps: SIGFPE Arithmetic overflow SIGILL Illegal instruction SIGSEGV Illegal address reference The Tandem defined signals that follow are Tandem C specific signals and directly correspond to a particular operating system trap. • SIGSTK The SIGSTK signal is equivalent to the STACK OVERFLOW trap.
Reference to Library Calls • sin The ANSI defined signals SIGABRT, SIGINT, and SIGTERM can only be generated by an explicit call to the raise function. The condition specified by each of these signals is: SIGABRT abnormal termination, such as is initiated by the abort function SIGINT receipt of an interactive attention signal SIGTERM a termination request sent to the program sin The sin function computes the sine of its argument.
sinh Reference to Library Calls sinh The sinh function computes the hyperbolic sine of its argument. #include double sinh(double expr); expr is an expression of type double. Return Value is the hyperbolic sine of expr. sinh returns HUGE_VAL if a positive overflow occurs, -HUGE_VAL if a negative overflow occurs, or zero if an underflow occurs. In all three of these cases, sinh also sets errno to ERANGE (a range error). Example This example prints “The hyperbolic sine is 2.301308.
Reference to Library Calls sprintf sprintf The sprintf function writes formatted data to a string. #include int sprintf(char *str_ptr, const char *format, [expr...]); str_ptr points to the string where sprintf stores the formatted data. format points to a string that contains characters and conversion specifiers. Refer to “fprintf” on page 3-51 for a description of format and conversion specifiers. expr... is the list of arguments to be formatted using the conversion specifiers in *format.
sqrt Reference to Library Calls sqrt The sqrt function computes the square root of its argument. #include double sqrt(double expr); expr is an expression of type double with a positive value. Return Value is the square root of expr. If expr is negative, sqrt returns zero and sets errno to EDOM (a domain error). Example This example prints “The square root of 25.000000 is 5.000000.”: #include #include int main(void) { double r; double x; x=25.
Reference to Library Calls srand srand The srand function resets the pseudo-random sequence generator to a new starting point. #include void srand(unsigned int seed); seed specifies the new starting point, or seed, for the pseudo-random sequence generator. Return Value none. Usage Guidelines • • At program startup, the generator’s seed is set to one. Calling srand with a given value of seed always produces the same sequence of pseudo-random numbers.
sscanf Reference to Library Calls sscanf The sscanf function reads formatted data from a character string, uses the format string to determine whether the data matches expectations and to determine the necessary conversions, and writes converted data to one or more supplied variables. #include int sscanf(const char *str_ptr, const char *format, [obj_ptr...]); str_ptr points to the data to scan and convert.
Reference to Library Calls sscanf Example This example reads input from a string, converts it to a long float (double) value, and stores it in a variable of type double: #include int status; double r, x; char sp[25]; /* ...
stcarg (supplementary) Reference to Library Calls stcarg (supplementary) The stcarg function scans a string until it finds one of the characters from another specified string. #include size_t stcarg(char *str1_ptr, char *str2_ptr); str1_ptr points to the string to scan. str2_ptr points to the string to scan for. Return Value is the number of characters scanned in *str1_ptr, or the length of *str1_ptr if none of the characters are found.
Reference to Library Calls stccpy (supplementary) stccpy (supplementary) The stccpy function copies not more than a specified number of characters from one string to another. For a similar ISO C Standard function, see“strncpy” on page 3-205. #include size_t stccpy(char *str1_ptr, char *str2_ptr, size_t max); str1_ptr points to the location to copy to. str2_ptr points to the string to copy. max specifies the maximum number of characters to copy. max must be a positive integer.
stcd_i (supplementary) Reference to Library Calls stcd_i (supplementary) The stcd_i function converts a string of decimal characters to an integer. #include int stcd_i(char *str_ptr, int *int_ptr); str_ptr points to the string to convert. int_ptr points to the variable of type int where stcd_i stores the converted value. Return Value is the number of characters scanned. Usage Guidelines • • • The string to convert can contain an optional sign and then a string of digits.
Reference to Library Calls stcd_l (supplementary) stcd_l (supplementary) The stcd_l function converts a string of decimal characters to a long integer. #include int stcd_l(char *str_ptr, long *int_ptr); str_ptr points to the string to convert. int_ptr points to the variable of type long where stcd_l stores the converted value. Return Value is the number of characters scanned. Usage Guidelines • • • The string to convert can contain an optional sign and then a string of digits.
stch_i (supplementary) Reference to Library Calls stch_i (supplementary) The stch_i function converts a string of hexadecimal characters to an integer. #include int stch_i(char *str_ptr, int *int_ptr); str_ptr points to the string to convert. int_ptr points to the variable of type int where stch_i stores the converted value. Return Value is the number of characters scanned, or zero if *str_ptr does not begin with a valid hexadecimal digit.
Reference to Library Calls stci_d (supplementary) stci_d (supplementary) The stci_d function converts a signed integer to a string of decimal characters. #include int stci_d(char *str_ptr, int integer, int outlen); str_ptr points to the string where stci_d stores the converted decimal value. integer is the integer to convert. outlen is the size of the array pointed to by str_ptr. Return Value is the length of the resulting string, excluding the terminating null character.
stcis (supplementary) Reference to Library Calls stcis (supplementary) The stcis function scans one string until it finds a character not specified in another string. For an equivalent ISO C Standard function, refer to “strspn” on page 3-208. #include size-t stcis(char *str1_ptr, char *str2_ptr); str1_ptr points to the string to scan. str2_ptr points to the string to scan for. This string can contain any legal character.
Reference to Library Calls stcisn (supplementary) stcisn (supplementary) The stcisn function scans one string until it finds a character that is specified in another string. For an equivalent ISO C Standard function, refer to “strcspn” on page 3-197. #include size-t stcisn(char *str1_ptr, char *str2_ptr); str1_ptr points to the string to scan. str2_ptr points to the string to scan for. This string can contain any legal character.
stclen (supplementary) Reference to Library Calls stclen (supplementary) The stclen function computes the length of a string. See “strlen” on page 3-201 for an equivalent ISO C Standard function. #include size_t stclen(char *str_ptr); str_ptr points to the string to measure. Return Value is the number of characters in *str_ptr, except for the terminating null character.
Reference to Library Calls stcpm (supplementary) Usage Guidelines • • Note that match_ptr has type pointer to pointer to char. This function returns the length of the first matching substring; a pointer to it is returned through match_ptr. You can use the backslash (\) as an escape character to match one of the special characters. If you specify pat_ptr as a string literal, you must use two backslashes.
stcpma (supplementary) Reference to Library Calls stcpma (supplementary) The stcpma function scans a string to determine whether it starts with a substring that matches a specified pattern. #include int stcpma(char *str_ptr, char *pat_ptr); str_ptr points to the string to scan. pat_ptr points to the pattern string.
Reference to Library Calls stcpma (supplementary) Example This example scans a string for the pattern “st?rs s???e”: #include #include int main(void) { int indx; size_t length; char *string, *pattern; string = "stars shine on alabama"; pattern = "st?rs s???e"; length = stcpma(string, pattern); for(indx=0; indx
stcu_d (supplementary) Reference to Library Calls stcu_d (supplementary) The stcu_d function converts an unsigned integer to a string of decimal characters. #include int stcu_d(char *str_ptr, unsigned value, int str_size); str_ptr points to the string where stcu_d stores the converted decimal value. value is the integer to convert. str_size specifies the number of bytes in *str_ptr. Return Value is the length of the resulting string, except for the terminating null character.
Reference to Library Calls stpblk (supplementary) stpblk (supplementary) The stpblk function scans a string for a nonspace character. #include char *stpblk(char *str_ptr); str_ptr points the string to scan. Return Value points to the first nonspace character in *str_ptr. Usage Guidelines • A nonspace character is any character for which the isspace returns zero.
stpbrk (supplementary) Reference to Library Calls stpbrk (supplementary) The stpbrk function scans a string for a character that is in a given list of characters. See “strpbrk” on page 3-206 for an equivalent ISO C Standard function. #include char *stpbrk(char *scan_str, char *chr_list); scan_str points to the string to scan. chr_list points to the string containing the characters to scan for. Return Value points to the first occurrence in *scan_str of one of the characters in *chr_list.
Reference to Library Calls stpsym (supplementary) stpsym (supplementary) The stpsym function gets a symbol from a string and stores it in another specified string. #include char *stpsym(char *str_ptr, char *dest_ptr, int dest_size); str_ptr points to the string to scan. dest_ptr points to the string where stpsym stores the symbol. dest_size specifies the size in bytes of *dest_ptr. Return Value points to the next character in the string after the symbol.
stpsym (supplementary) Reference to Library Calls Example This example scans the string text until it encounters a non-alphanumeric character; it then writes the string to symbol: #include #include int main(void) { char *text; char symbol[10]; char *r; text = "alpha1 2"; r = stpsym(text,symbol,10); printf("%s",symbol); /* prints "alpha1" */ } 3- 190 128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls stptok (supplementary) stptok (supplementary) The stptok function scans a source string for a token and copies the token to another string. The token consists of all characters in the source string up to, but not including, the first delimiter. #include char *stptok(char *sstr_ptr, char *tstr_ptr, int tmax, char *bstr_ptr); sstr_ptr points to the string to scan. tstr_ptr points to the string where stptok copies the token.
strcat Reference to Library Calls strcat The strcat function concatenates two strings. #include char *strcat(char *str1_ptr, const char *str2_ptr); str1_ptr points to the string to which the second string is concatenated. str2_ptr points to the string that is concatenated to the first string. Return Value points to the resulting string. Usage Guidelines • • The strcat function assumes that *str1_ptr can accommodate both *str1_ptr and *str2_ptr.
Reference to Library Calls strchr strchr The strchr function scans a string for the first occurrence of a given character. #include char *strchr(const char *str_ptr, int chr); str_ptr points to the string to scan. chr is the character to scan for. Return Value points to the first occurrence in *str_ptr of chr. If *str_ptr does not contain chr, then strchr returns the pointer value NULL.
strcmp Reference to Library Calls strcmp The strcmp function compares two strings alphabetically. #include int strcmp(const char *str1_ptr, const char *str2_ptr); str1_ptr points to the first string. str2_ptr points to the second string. Return Value is zero if the two strings are equal, a negative value if *str1_ptr is less than *str2_ptr, or a positive value if *str1_ptr is greater than *str2_ptr.
Reference to Library Calls strcoll strcoll The strcoll function compares two strings according to the rules of the current locale collating sequence. The strcoll function compares each byte, the same as the strcmp function does, because there exists no defined collating sequence for a 2-byte character set. #include int strcoll(const char *s1, const char *s2); s1 points to the first string. s2 points to the second string.
strcpy Reference to Library Calls strcpy The strcpy function copies one string to another. #include char *strcpy(char *str1_ptr, const char *str2_ptr); str1_ptr points to the target string. str2_ptr points to the string to be copied. Return Value points to the target string; that is, the return value is str1_ptr. Usage Guidelines • If the strings overlap, the strcpy function does not preserve data.
Reference to Library Calls strcspn strcspn The strcspn function scans a string until it finds a character that is found in another specified string. #include size_t strcspn(const char *str1_ptr, const char *str2_ptr); str1_ptr points to the string to scan. str2_ptr points to the string containing the characters to scan for. Return Value is the length of the initial segment of the *str1_ptr that consists entirely of characters not listed in *str2_ptr.
strerror Reference to Library Calls strerror The strerror function retrieves the textual error message corresponding to one of the predefined values that errno can acquire. #include char *strerror(int errval); errval is the error value whose corresponding textual message strerror retrieves. For a list of the predefined error values, refer to “” on page 2-2. Return Value points to a string containing the textual error message corresponding to errval.
Reference to Library Calls strftime strftime The strftime function writes characters into the array pointed to by s under the direction of the format string pointed to by format. At most maxsize characters are written. If more than maxsize characters are required, the function returns zero and the contents of s is indeterminate; otherwise the length of s is returned, not counting the null terminator.
strftime Reference to Library Calls Usage Guidelines • 3- 200 The format string consists of zero or more conversion specifiers. A conversion specifier consists of a % character followed by a character that determines the behavior of the conversion specifier.
Reference to Library Calls strlen strlen The strlen function computes the length of a string. #include size_t strlen(const char *str_ptr); str_ptr points to the string to measure. Return Value is the number of characters in *str_ptr, except for the terminating null character.
strncat Reference to Library Calls strncat The strncat function concatenates not more than a specified number of characters from one string to another. #include char *strncat(char *str1_ptr, const char *str2_ptr, size_t max); str1_ptr points to the string to append to. str2_ptr points to the string that is concatenated to the first string. max specifies the maximum number of characters from *str2_ptr to append to *str1_ptr. max must be a positive integer.
Reference to Library Calls strncmp strncmp The strncmp function compares two strings alphabetically for a given maximum number of characters. #include int strncmp(const char *str1_ptr, const char *str2_ptr, size_t max); str1_ptr points to the first string to compare. str2_ptr points to the second string to compare. max specifies the maximum number of characters to compare. max must be a positive integer.
strncmp Reference to Library Calls Example This example prints “s1 equals s2” because the first 10 characters match: #include #include int main(void) { int value; char *s1, *s2; s1 = "Opus is a penguin"; s2 = "Opus is a flightless waterfowl"; value = strncmp(s1,s2,10); if (value<0) printf("s1 is less than s2\n"); else if (value>0) printf("s1 is greater than s2\n"); else printf("s1 equals s2\n"); } 3- 204 128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls strncpy strncpy The strncpy function copies not more than a specified number of characters from one string to another. #include char *strncpy(char *str1_ptr, const char *str2_ptr, size_t max); str1_ptr points to the destination string. *str1_ptr must accommodate at least max characters. str2_ptr points to the string to copy. max specifies the maximum number of characters to copy; max must be a positive integer. Return Value points to the resulting string.
strpbrk Reference to Library Calls strpbrk The strpbrk function scans a string to find the first occurrence of a character from another string. #include char *strpbrk(const char *str1_ptr, const char *str2_ptr); str1_ptr points to the string to scan. str2_ptr points to the string containing the characters to scan for. Return Value points to the first occurrence in *str1_ptr of any character in *str2_ptr.
Reference to Library Calls strrchr strrchr The strrchr function scans a string backwards for the last occurrence of a given character. #include char *strrchr(const char *str_ptr, int chr); str_ptr points to the string to scan. chr is the character to scan for. Return Value points to the last occurrence in *str_ptr of the character chr. If *str_ptr does not contain chr, then strrchr returns the pointer value NULL.
strspn Reference to Library Calls strspn The strspn function scans a string until it finds a character that is not found in another specified string. #include size_t strspn(const char *str1_ptr, const char *str2_ptr); str1_ptr points to the string to scan. str2_ptr points to the string containing the characters to scan for. Return Value is the length of the initial segment of *str1_ptr that consists entirely of characters in *str2_ptr.
Reference to Library Calls strstr strstr The strstr function searches a string for the first occurrence of a given substring. #include char *strstr(const char *str, const char *substr); str points to the string to search. substr points to the substring to search for. Return Value points to the first occurrence in *str of *substr. If the string does not contain the substring, strstr returns the pointer value NULL. If the length of *substr is zero, strstr returns str.
strtod Reference to Library Calls strtod The strtod function converts the initial portion of a string to a double value. #include double strtod(const char *str_ptr, char **end_ptr_ptr); str_ptr points to the string to convert. end_ptr_ptr points to the variable of type pointer to char where strtod stores a pointer to the first unrecognized character in *str_ptr. Return Value is the converted double value if the conversion is successful. If strtod could perform no conversion, it returns zero.
Reference to Library Calls strtok strtok The strtok function gets a token from a specified string. #include char *strtok(char *str1_ptr, const char *str2_ptr); str1_ptr is either a pointer to the source string for the first token or a null pointer for subsequent tokens. str2_ptr points to a string that specifies the list of token delimiter characters; these characters cannot be part of a token. Return Value points to the next token in the string.
strtol Reference to Library Calls strtol The strtol function converts a string of characters to a long int value using a specified base. #include long strtol(const char *str_ptr, char **end_ptr_ptr, int base); str_ptr points to the string to convert. end_ptr_ptr points to the variable of type pointer to char where strtol stores a pointer to the first unrecognized character in *str_ptr. base specifies the base of the long integer. It can be in the range from 0 to 36.
Reference to Library Calls strtol Example This example prints “138051”, which is the decimal equivalent of the hexadecimal number 21B43: #include #include int main(void) { char *string; char *end_of_num; long num; string = "21B43"; num = strtol(string, &end_of_num, 16); printf("%ld",num); } Guardian TNS C Library Calls Reference Manual—128833 3 -213
strtoul Reference to Library Calls strtoul The strtoul function converts a string of characters to an unsigned long int value using a specified base. #include unsigned long strtoul(const char *str_ptr, char **end_ptr_ptr, int base); str_ptr points to the string to convert. end_ptr_ptr points to the variable of type pointer to char where strtoul stores a pointer to the first unrecognized character in *str_ptr. base specifies the base of the long integer. It can be in the range from 0 to 36.
Reference to Library Calls strxfrm strxfrm The strxfrm function “transforms” a string into another such that the strcmp function can be used to correctly compare two “transformed” strings. The result is the same as if the strcoll function had been used on the original strings. #include size_t strxfrm(char *s1, const char *s2, size_t n); s1 points to an array that will contain the transformed string. If n is zero, s1 is permitted to be a null pointer.
stscmp (supplementary) Reference to Library Calls stscmp (supplementary) The stscmp function compares two strings. See “strcmp” on page 3-194 for an equivalent ISO C Standard function. #include int stscmp(char *str1_ptr, char *str2_ptr); str1_ptr points to the first of the two strings to compare. str2_ptr points to the second of the two strings to compare.
Reference to Library Calls system system The system function sends a string of characters to the TACL command process for execution. #include int system(const char *string); string points to an array of characters. Return Value is 0 if the system function sends a string and no error occurs. A non-zero return value other than 1 indicates that a Guardian error occurred.
tan Reference to Library Calls tan The tan function computes the tangent of its argument. #include double tan(double expr); expr specifies an angle in radians. Return Value is the tangent of expr. Example This example prints “The tangent is 1.000004.”: #include #include int main(void) { double x; x = 0.7854; printf("The tangent is %f.
Reference to Library Calls tanh tanh The tanh function computes the hyperbolic tangent of its argument. #include double tanh(double expr); expr is any valid expression. Return Value is the hyperbolic tangent of expr. Example This example prints “The hyperbolic tangent is 0.655795.”: #include #include int main(void) { double r, x; x = 0.7854; r = tanh(x); printf("The hyperbolic tangent is %f.
terminate_program (supplementary) Reference to Library Calls terminate_program (supplementary) The terminate_program function writes to open files any data left in the buffers, closes files, passes all of the allowed information to the Guardian system procedure PROCESS_STOP_, and terminates execution of your C program.
Reference to Library Calls terminate_program (supplementary) text_length if used, the value of text must be exactly text_length bytes long. The maximum length is 80 bytes. Usage Guidelines • • • The terminate_program function is similar to the exit function but allows you to pass all of the allowed information to the Guardian system procedure PROCESS_STOP_.
time Reference to Library Calls time The time function determines the current calendar time, expressed as the number of seconds that have elapsed since January 1, 1970, Coordinated Universal Time (UTC). #include time_t time(time_t *timer); timer is a pointer. If timer is not NULL, the current calendar time also gets stored in the variable pointed to by timer. Return Value is the current calendar time.
Reference to Library Calls tmpnam tmpfile The tmpfile function creates a temporary C binary file, opening it for ANSI I/O and binary update access (“wb+”). This temporary file is automatically removed when it is closed or when the program terminates. #include FILE *tmpfile(void); Return Value points to the FILE structure denoting the opened temporary file if the operation is successful; otherwise, tmpfile returns the pointer value NULL.
toascii (supplementary) Reference to Library Calls toascii (supplementary) The toascii function determines the ASCII equivalent of a nonASCII character. #include int toascii(int character); character is the character whose ASCII value you desire. Return Value is the ASCII equivalent of character.
Reference to Library Calls tolower tolower The tolower function determines the lowercase equivalent of an uppercase letter. #include int tolower(int character); character is the character whose lowercase equivalent you desire. Return Value is the lowercase equivalent of character. Usage Guidelines • • If character is not an uppercase letter, tolower simply returns it unchanged.
toupper Reference to Library Calls toupper The toupper function determines the uppercase equivalent of a lowercase letter. #include int toupper(int character); character is the character whose uppercase equivalent you desire. Return Value is the uppercase equivalent of character. Usage Guidelines • • 3- 226 If character is not a lowercase letter, toupper simply returns it unchanged.
Reference to Library Calls trap_overflows (supplementary) trap_overflows (supplementary) The trap_overflows function allows you to control the treatment of arithmetic overflows. #include void trap_overflows(short enable_flag); enable_flag is an integer that requests overflow trapping be enabled or disabled. If enable_flag is nonzero, overflow trapping is enabled. If enable_flag is zero, overflows are ignored. Return Value none.
ungetc Reference to Library Calls ungetc The ungetc function pushes a single character back into an input file opened for ANSI I/O. #include int ungetc(int character, FILE *stream); character specifies the character to be pushed back into the input stream. stream denotes a file opened for ANSI I/O. Return Value is character if the operation is successful, or the value EOF if an error occurs. Usage Guidelines • • • The EOF value cannot be pushed back.
Reference to Library Calls unlink (supplementary) unlink (supplementary) The unlink function purges a disk file. Refer to “remove” on page 3-153 for an equivalent standard function. #include short unlink(char *file_name); file_name points to a string that contains a valid file name. Return Value is zero if the operation is successful, or -1 if an error occurs. Usage Guidelines • You can call unlink only for closed files. Example This example purges the file $a.b.
va_arg Reference to Library Calls va_arg The va_arg macro expands to an expression whose value is that of the next argument in the argument list that contains a variable number of arguments. This expression has the type you specify in the invocation of va_arg. #include va_arg(va_list ap, ); ap is a variable of type va_list that has been initialized by a previous invocation of the va_start macro.
Reference to Library Calls va_end Example The function defined in this example uses va_start, va_arg, and va_end to compute the average of a variable number of double values: #include /* ... */ double dbl_average(int count, ...) { va_list ap; double div,avg; if (count<=0) return 0.0; va_start(ap, count); if (count==1) { avg=va_arg(ap, double); va_end(ap); return avg; } div=count; for (avg=0.
va_start Reference to Library Calls va_start The va_start macro initializes its first argument for use as the retainer of a list that contains the variable number of arguments. This first argument, ap, can then be used by va_arg and va_end to extract arguments from the list. #include void va_start(va_list ap, ); ap is the variable of type va_list that va_start initializes for use as a retainer for the list that contains the variable number of arguments.
Reference to Library Calls vfprintf vfprintf The vfprintf function writes formatted data to a file opened for ANSI I/O, extracting the data values from a variable argument list. #include #include int vfprintf(FILE *stream, const char *format, va_list ap); stream denotes a file opened for ANSI I/O. format points to a string that contains characters and conversion specifiers, which indicate how to format the values of the arguments denoted by ap.
vprintf Reference to Library Calls vprintf The vprintf function writes formatted data to the standard output file, extracting the data values from a variable argument list. #include #include int vprintf(const char *format, va_list ap); format points to a string that contains characters and conversion specifiers, which indicate how to format the values of the arguments denoted by ap. Refer to “fprintf” on page 3-51 for a description of format and conversion specifiers.
Reference to Library Calls vsprintf vsprintf The vsprintf function writes formatted data to a string, extracting the data values from a variable argument list. #include #include int vsprintf(char *str, const char *format, va_list ap); str points to the string where vsprintf stores the formatted data. format points to a string that contains characters and conversion specifiers, which indicate how to format the values of the arguments denoted by ap.
wctomb Reference to Library Calls wctomb The wctomb function converts a wide character to a multibyte character. #include int wctomb(char *s, wchar_t wchar); s points to a character array that will contain the multibyte character. This character array should be at least MB_CUR_MAX characters long. wchar is a variable of type wchar_t that contains the wide character that the wctomb function converts. Return value If s is a null pointer, the return value is 0.
Reference to Library Calls wcstombs wcstombs The wcstombs function converts a sequence of wide characters into a sequence of multibyte characters. #include size_t wcstombs(char *s, const wchar_t *pwcs, size_t n); s points to the array that will hold the multibyte characters. pwcs points to the array that contains the sequence of wide characters to be converted. n specifies the total number of bytes that can be modified in the array pointed to by s.
write (supplementary) Reference to Library Calls write (supplementary) The write function writes a specified number of bytes from a buffer to a file opened for alternate I/O. #include short write(int file_des, char *buf, short nbytes); file_des is the descriptor of a file opened for alternate I/O. buf points to the buffer to be written. nbytes specifies the number of bytes to write from the buffer.
Reference to Library Calls writeread (supplementary) writeread (supplementary) The writeread function writes a message and then reads the resulting input. More specifically, writeread: 1. Writes a number of bytes from a buffer to a file 2. Begins to read a number of bytes from the file to the buffer 3. Causes suspension of C program execution until the read operation is complete 4.
writeread (supplementary) 3- 240 Reference to Library Calls 128833 —Guardian TNS C Library Calls Reference Manual
Index A abort function 3-1 abs function 3-1 acos function 3-2 ANSI C standard 1-1 asctime function 3-3 asin function 3-5 assert macro 3-6 asserth header 2-1 atan function 3-7 atan2 function 3-8 atexit function 3-9 atof function 3-10 atoi function 3-11 atol function 3-12 B bsearch function 3-13 C C run-time library introduction 1-1 standards compliance 1-1 calloc function 3-14 ceil function 3-15 chvol function 3-16 CLARGE 1-1 clearerr function 3-17 CLIB 1-1 clock function 3-18 close function 3-19 CNONSTOP
G Index fcntl function 3-35 fcntlh header 2-5 fdopen function 3-37 fdtogfn function 3-38 feof function 3-39 ferror function 3-40 fflush function 3-41 fgetc function 3-42 fgetpos function 3-43 fgets function 3-44 fileno function 3-45 Files, header 2-1 floath header 2-6 floor function 3-46 fmod function 3-47 fopen function 3-48 fopen_std_file function 3-50 Format strings for printf family 3-51 for scanf family 3-62 fprintf function 3-51 fputc function 3-55 fputs function 3-56 fread function 3-57 free functi
Index P Library asserth header 2-1 ctypeh header 2-1 errnoh header 2-2 fcntlh header 2-5 floath header 2-6 headers 2-1 limitsh header 2-8 localeh header 2-9 mathh header 2-9 memoryh header 2-10 nonstoph header 2-10 setjmph header 2-10 signalh header 2-10 sqlh header 2-11 stdargh header 2-11 stddefh header 2-11 stdioh header 2-11 stdlibh header 2-12 stringh header 2-13 talh header 2-13 timeh header 2-13 limitsh header 2-8 localeconv function 3-105 localeh header 2-9 localtime function 3-106 log function 3-
Q Q qsort function 3-147 R raise function 3-148 rand function 3-149 read function 3-150 readupdate function 3-150 realloc function 3-152 remove function 3-153 rename function 3-153 reply function 3-154 repmem function 3-155 rewind function 3-156 Run-time libraries 1-1 S scanf function 3-157 SEEK_CUR macro used in edfseek 3-28 used in edlseek 3-30 used in fseek 3-66 used in lseek 3-111 SEEK_END macro used in edfseek 3-28 used in edlseek 3-30 used in fseek 3-66 used in lseek 3-111 SEEK_SET macro used in ed
Index strcspn function 3-197 strerror function 3-198 strftime function 3-199 stringh header 2-13 strlen function 3-201 strncat function 3-202 strncmp function 3-203 strncpy function 3-205 strpbrk function 3-206 strrchr function 3-207 strspn function 3-208 strstr function 3-209 strtod function 3-210 strtok function 3-211 strtol function 3-212 strtoul function 3-214 strxfrm function 3-215 stscmp function 3-216 system function 3-217 T talh header 2-13 tan function 3-218 tanh function 3-219 terminate_program
Special Characters Index- 6 Index 128833 —Guardian TNS C Library Calls Reference Manual
