SIMATIC. System Software for M7-300 and M7-400 System and Standard Functions, Volume 2. Table of Contents. C Runtime Library 1.

Transcription

1 Table of Contents C Runtime Library 1 SIMATIC System Software for M7-300 and M7-400 System and Standard s, Volume 2 Socket Interface 2 Miscellaneous 3 Index Reference Manual This manual is part of the documentation package with the order number: 6ES7802 0FA14 8BA0

2 Safety Guidelines This manual contains notices which you should observe to ensure your own personal safety, as well as to protect the product and connected equipment. These notices are highlighted in the manual by a warning triangle and are marked as follows according to the level of danger:! Danger indicates that death, severe personal injury or substantial property damage will result if proper precautions are not taken.! Warning indicates that death, severe personal injury or substantial property damage can result if proper precautions are not taken.! Caution indicates that minor personal injury or property damage can result if proper precautions are not taken. Note draws your attention to particularly important information on the product, handling the product, or to a particular part of the documentation. Qualified Personnel Only qualified personnel should be allowed to install and work on this equipment. Qualified persons are defined as persons who are authorized to commission, to ground, and to tag circuits, equipment, and sys tems in accordance with established safety practices and standards. Correct Usage Note the following:! Warning This device and its components may only be used for the applications described in the catalog or the technical description, and only in connection with devices or components from other manufacturers which have been approved or recommended by Siemens. This product can only function correctly and safetly if it is transported, stored, set up and installed correctly, and operated and maintained as recommended. Trademarks SIMATIC, SIMATIC HMI and SIMATIC NET are registered trademarks of SIEMENS AG. Some of the other designations used in these documents are also registered trademarks; the owner s rights may be violated if they are used by third parties for their own purposes. Copyright Siemens AG 1998 All rights reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Siemens AG Automation and Drives Group Industrial Automation Systems P.O.Box 4848, D Nuremberg Index-2 Siemens Aktiengesellschaft Disclaimer of Liability We have checked the contents of this manual for agreement with the hardware and software described. Since deviations cannot be precluded entirely, we cannot guarantee full agreement. However, the data in this manual are reviewed regularly and any necessary corrections included in subsequent editions. Suggestions for improvement are welcomed. Siemens AG 1998 System Software for Technical M7-300 data and subject M7-400, to change. System and Standard s, Volume 2

3 Table of Contents 1 C Runtime Library Socket Library Miscellaneous Index i

4 Table of Contents ii

5 C Runtime Library 1 In this chapter Call Brief Page abort Terminate task 1-7 abs Determine the absolute value of an integer number 1-8 access Check file access 1-9 acos Arc cosine 1-10 asctime Convert date and time of the software clock to a string 1-11 asin Arc sine 1-13 assert Terminate task depending on condition 1-14 atan Arc tangent 1-15 atan2 Arc tangent of two double numbers 1-16 atexit Define routines to be executed on completion of a task 1-17 atof Convert a string to a double-precision number 1-18 atoi Convert a string to an integer number 1-19 atol Convert a string to a long integer number 1-20 bsearch Search for an element in a sorted table 1-21 calloc Request memory 1-23 ceil Round up a double-precision number 1-24 changevib Change volume identification block 1-25 chdir Change the current working directory (CWD) 1-26 checkpoint Store temporary buffer of file 1-27 chmod Change file attributes 1-28 clearerr Reset the error status of a stream 1-30 clock Dummy 1-31 close Close an open file, socket or unit of a loadable driver 1-32 cos Cosine 1-33 cosh Hyperbolic cosine 1-34 createvib Generate new volume identification block 1-35 ctime Convert date and time to a string 1-36 difftime Determine the length of a time interval 1-38 dismount Dismount a device of the HSFS file management system

6 C Runtime Library Call Brief Page div Integer division 1-40 duread Read character via an driver 1-41 duwrite Write character via an driver 1-43 efsstop Close connection between a net unit and the server unit 1-45 efsuse Open a connection between a net unit and the server unit 1-46 errno, errno2 Error numbers of system calls and library functions 1-47 exit Terminate task with clean-up operations and fixed status 1-49 exp Exponential function 1-50 fabs Determines the absolute value of a double-precision number 1-51 fclose Close stream 1-52 fduopen Open an driver stream 1-53 fdureopen Redirect a stream to a driver 1-54 feof Check the stream status for EOF 1-56 ferror Check the stream status for an I/O error 1-57 fflush Flush a stream buffer 1-58 fgetc Read a character from a stream 1-59 fgetpos Return the current position in a file 1-60 fgets Read string from a stream 1-61 fileno Determine descriptor 1-62 floor Round down a double number 1-63 fmod Determine remainder after division of two double numbers 1-64 fopen Open a stream 1-65 fprintf Route the formatted output to a stream 1-67 fputc Write a character to a stream 1-68 fputs Write a string to stream 1-69 fread Read data from a stream 1-70 free Free memory 1-71 freopen Swap the file assigned to a stream 1-72 frexp Split a double-precision number 1-75 fscanf Route the formatted input from a stream 1-76 fseek Position the file pointer in a stream 1-78 fsetpos Set the current position in a file 1-79 ftell Return the file pointer in a stream 1-80 fwrite Write data to a stream

7 C Runtime Library Call Brief Page getc Read a character from a stream 1-82 getchar Read a character from the standard input 1-83 getcwd Determine the current working directory (cwd) 1-84 getenv Determine environment variable 1-85 gets Read a string from a stream 1-86 getvolumestatus Get volume status information 1-87 getw Read word from a stream 1-91 gmtime Convert date and time to string to GMT 1-92 inhibitabort Inhibit or reenable task abort 1-94 ioctl Control functions for sockets or units of loadable drivers 1-95 isalnum Determine whether a character is alphanumeric 1-97 isalpha Determine whether a character is alphabetic 1-98 isascii iscntrl Determine whether a character is in the range of the ASCII character set Determine whether character is ASCII control character isdigit Determine whether a character is a decimal number isgraph Determine whether a character is a graphic character islower Determine whether a character is a lower case letter isprint Determine whether a character is a printable character ispunct Determine whether a character is a punctuation mark isspace Determine whether a character is a blank isupper Determine whether a character is an upper case letter isxdigit Determine whether a character is a hexadecimal number labs Determine the absolute value of a long integer ldexp Generate a double-precision number ldiv Long integer division localtime Convert date and time to local time log Natural logarithm log10 Logarithm to base longjmp Execute a non-local jump lseek Positions the file pointer in a file malloc Request memory matherr Provide user-specific error handling memccpy Copy characters from source area to the destination area memchr Search an area for a character

8 C Runtime Library Call Brief Page memcmp Compare the contents of two areas memcpy memmove Copy characters from a source area to a destination area Copy characters from a source area to a destination area memset Copy characters to an area mkdir Make directory mktime Convert the local time modf Split double number into integer part and fractional part mount Mount an HSFS device open Open a file for read or write access perror Output a CRUN error pow Power function printf Route the formatted output to the standard output putc Write a character to a stream putchar Write a character to the standard output putenv Modify or append an environment variable puts Write a string to a stream putw Write a word to a stream qsort Sorting function raise Generate signal rand Generate an integer random number read Read data from a file realloc Modify the size of a memory area remap Format a volume remove Delete a file rename Rename a file rewind Position the file pointer in a stream rmdir Delete a directory scanf Route a formatted input from the standard input search Search for files(s) setbuf Assign a buffer for an I/O stream setjmp Set a marker for a non-local jump setvbuf Assign a buffer to an I/O stream signal Set up functions for exception handling sin Sine sinh Hyperbolic sine

9 C Runtime Library Call Brief Page sleep Halt a task for a specific time sprintf Route the formatted output to a string sqrt Square root function srand Seed random number sequence sscanf Route a formatted input from a string strcat Append one string to a second string strchr Search for a character in a string strcmp Compare two strings strcpy Copy one string to a second string strcspn Compare two strings strerror Determine error text strftime Output formatted date and time strlen Determine the length of a string strncat Append a substring to another string strncmp Compare two substrings strncpy Copy a substring strpbrk Compare the characters in two strings strrchr Search for a character in a string strspn Compare two strings strstr Compare two strings strtod Convert a string to a double-precision number strtok Search for a character in string different from a delimiter strtol Convert a string to an integer number strtoul Convert a string to an unsigned long integer sys_errlist,sys_nerr String array with error messages tan Tangent tanh Hyperbolic tangent time Determine system time tmpfile Create a temporary file tmpnam Create a name for a temporary file toascii Convert a character to an integer number tolower,_tolower Convert a character to a lower-case character toupper,_toupper Convert a character to an upper-case character tzset Set a time zone ungetc Push a character back onto a stream unlink Delete a file

10 C Runtime Library Call Brief Page vfprintf Route a formatted output to a stream vprintf Route a formatted output to a stream vsprintf Route a formatted output to a stream write Write data to a file x_cr_gettaskid Determine the ID of the calling task x_cr_gettaskparam Determine stdin, stdout, stderr and the task environment x_cr_initenv Initialize the task environment x_cr_killtsk Delete a task x_cr_setexit Set a task-specific exit handler xinitc Initialize CRUN xinitt Perform task-specific runtime environment initialization

11 C Runtime Library abort abort Terminate task #include <stdlib.h> void abort (void); abort sends the signal SIGABRT to the requesting task. The default signal handler terminates a task using the CRUN function exit. exit, raise, signal 1-7

12 abs C Runtime Library abs Determine the absolute value of an integer number #include <stdlib.h> int abs (int value); value Integer number abs returns the absolute value of the integer number specified by value. Integer number Absolute value Example main () { int x,y; x = abs (23); /* Result is 23 */ y = abs (-105); /* Result is 105 */ } fabs, labs 1-8

13 C Runtime Library access access Check file access #include <io.h> int access( const char *pathname, int flags); pathname Pointer to a file name flags Reserved (must be 0) access checks whether the file specified by pathname is entered in the directory. The parameter flags must have the value 0. 0 File exists -1 File not found or error Error Codes In the event of an error, errno is set to one of the following values: Error Code EAGAIN EINVAL EIO EMFILE ENOENT ENOMEM ENOSPC ENOTDIR ERANGE Directory protected by lock option error in pathname Physical read/write error Too many open files File does not exist No memory available Volume full Pathname contained invalid component Unexpected HSFS error code 1-9

14 acos C Runtime Library acos Arc cosine #include <math.h> double acos (double x); x Double-precision number acos calculates the arc cosine of a double precision number. The returned value is in radians and assumes a value between 0 and π. The argument must be in the range from 1 to +1. If it is outside this range, acos calls the error handling routine matherr with exception type DOMAIN and sets errno to EDOM. The return value in this case is IND. Double number IND Arc cosine After matherr is called with exception type DOMAIN, errno is set to EDOM. asin, atan, atan2, matherr 1-10

15 C Runtime Library asctime asctime Convert date and time of the software clock to a string #include <time.h> char *asctime (struct tm *ptm); ptm Pointer to a structure of type tm asctime converts date and time of the software clock in a structure of type tm to a 26 character string and returns a pointer to this string. The structure tm is defined in TIME.H as follows: struct tm{ }; int tm_sec; /* Seconds (0-59) */ int tm_min; /* Minutes (0-59) */ int tm_hour; /* Hours (0-23) */ int tm_mday; /* Day of month (1-31) */ int tm_mon; /* Month (0-11) */ int tm_year; /* Year minus 1900 */ int tm_wday; /* Day of week (Sunday = 0) */ int tm_yday; /* Current day of year (0-365) */ int tm_isdst; /* 0 daylight saving time */ Pointer to string containing date and time Note The return values point to a static data area which is overwritten when next the function is called. The following example demonstrates the use of the various CRUN time functions: 1-11

16 asctime C Runtime Library Example #include <time.h> main () { struct tm *ptm; char *date; long tadd; putenv ( TZ=MEZ-1 ); time (&tadd); date = ctime (&tadd); printf ( today s date is %s, date); ptm = localtime (&tadd); date = asctime (ptm); printf ( today s date is %s, date); ptm = gmtime (&tadd); date = asctime (ptm); printf ( Greenwich mean time is %s, date); } ctime, gmtime, mktime, localtime, time, tzset 1-12

17 C Runtime Library asin asin Arc sine #include <math.h> double asin (double x); x Double-precison number asin calculates the arc sine of a double precision number. The returned value is in radians and assumes a value between -π/2 and +π/2. The argument must be in the range from 1 to +1. If it is outside this range, asin calls the error handling routine matherr with exception type DOMAIN and sets errno to EDOM. The return value in this case is IND. Double number IND Arc sine After matherr is called with exception type DOMAIN, errno is set to EDOM acos, atan, atan2, matherr 1-13

18 assert C Runtime Library assert Terminate task depending on condition #include <assert.h> void assert (<condition>); <condition> Boolean variable assert evaluates <condition>. For FALSE (value = 0), a message is output to the standard error output which lists the text of <condition>, the file name (value of the macro FILE ) and the line number (value of the macro LINE ) of the current assert macro. The program is then terminated by abort. 1-14

19 C Runtime Library atan atan Arc tangent #include <math.h> double atan (double x); x Double-precision number atan calculates the arctangent of a double precision number. The returned value is in radians and assumes a value between -π/2 and +π/2. The argument is the entire double precision number range. Double number Arc tangent asin, acos, atan2, matherr 1-15

20 atan2 C Runtime Library atan2 Arc tangent of two double numbers #include <math.h> double atan2( double x, double y); x y Double-precision number Double-precision number atan2 calculates the arc tangent from the quotient of two double precision numbers. The signs of the arguments are used to determnine the quadrant. The returned value is in radians and assumes a value between -π und +π. If both argument are 0, atan2 call the error handling routine matherr with exception type DOMAIN and sets errno to EDOM. The return value in this case is IND. Double number IND Arc tangent of the qotient After matherr is called with exception type DOMAIN, errno is set to EDOM acos, asin, atan, matherr 1-16

21 C Runtime Library atexit atexit Define the routines to be executed on completion of a task #include <stdlib.h> int atexit (void (_FIED * func)(void)); func Pointer to a function with a Pascal (or fixedparams) interface. Each time atexit is called, it registers another function func. All registered functions are called by the function exit at the end of the task. A maximum of 32 functions can be registered. s are called in reverse order of their registration. 0 registered 0 not registered exit 1-17

22 atof C Runtime Library atof Convert a string to a double-precision number #include <stdlib.h> double atof (const char *string); string Pointer to string atof returns a double-precision floating-point number. The result corresponds to the the value of the string pointed to by string. The string is scanned as long as valid values are found. Leading blanks (defined by isspace in CTYPE.H) are ignored. The floating-point number must have the format (in the order given): leading optional blanks and/or tabs an optional sign a sequence of decimal digits, followed by a decimal point and further digits (at least one of the digit blocks and the decimal point must be present) an optional exponent starting with e or with E and consisting of an optional sign and an obligatory integer string Double number Double-precision floating-point number 0.0 Double-precision floating-point number not generated Error Codes In the event of an error, errno is set to one of the following values: Error Code ERANGE After overflow or underflow. After an underflow atof returns the value 0.0. After an overflow atof returns the value HUGE_VAL with the appropriate sign. Note atof (string) is equivalent to strtod (string, NULL). isspace, strtod 1-18

23 C Runtime Library atoi atoi Convert a string to an integer number #include <stdlib.h> int atoi (char *string); string Pointer to string atoi returns as result an integer number. The value corresponds to the value of the string to which string points. The string is scanned until a character is encountered which is inconsistent with the number base 10; leading blanks (defined by isspace in CTYPE.H) are ignored. Integer number Decimal number Note atoi (string) is equivalent to (int) strtol (string, (char **) 0, 10). Overflow conditions are ignored. atol, strtol, strtoul 1-19

24 atol C Runtime Library atol Convert a string to a long integer number #include <stdlib.h> int atol (char *string); string Pointer to string atol returns as result a long integer number. The value corresponds to the value of the string to which string points. The string is scanned until a character is encountered which is inconsistent with the number base 10; leading blanks (defined by isspace in CTYPE.H) are ignored. Long-Integer Decimal number Note atol (string) is equivalent to strtol (string, (char **) 0, 10). Overflow conditions are ignored. atoi, strtol, strtoul 1-20

25 C Runtime Library bsearch bsearch Search for an element in a sorted table #include <stdlib.h> void *bsearch( const void *search, const void *table, size_t count, size_t size, int (_FIED *compar) (const void *p1, const void *p2)); search table count size compar Pointer to the element to be searched for Pointer to the first element of the table Number of elements in the table Size of an element in bytes Name of a user comparison function; this function has two arguments which point to the elements to be compared; compar must return an integer number which is less than, equal to, or greater than 0, depending on whether the first argument is less than, equal to, or greater than the second. The comparator function must have a Pascal (or fixedparams) interface, as for example: int compar (const void*p1, const void*p2) bsearch searches for a particular element in the specified table. The elements of table must have been sorted in ascending order according to a user defined comparison function compar. Pointer NULL pointer to the element (function successful) unsuccessful Note search and table should be of type pointer to element and converted to type pointer to character (casting). 1-21

26 bsearch C Runtime Library The return values should be converted to type pointer-to-element, even if they are declared as type pointer-to-character. The table elements may contain arbitrary data since compar does not necessarily have to compare each byte. qsort 1-22

27 C Runtime Library calloc calloc Request memory #include <malloc.h> void *calloc( size_t nmemb, size_t size); nmemb size Number of elemens of the array Length of one element calloc requests memory for an array of nmemb elements of length size; the memory space is initialized to 0. Pointer NULL pointer to a memory area of the requested size if size equal to 0 ist or no memory available Error Codes In the event of an errno, errno is set to the following value: Error Code ENOMEM No memory available Note The memory area is freed either directly by calling the function free, RmFree or RmFreeAll or automatically by terminating the task by exit, x_cr_killtsk, RmDeleteTask, RmEndTask or RmKillTask. free, malloc, realloc, RmFree, RmFreeAll 1-23

28 ceil C Runtime Library ceil Round up a double-precision number #include <math.h> double ceil (double x); x Double-precision number ceil rounds up argument to the next integer double-precision number. If the argument for ceil is already an integer value, or greater than the largest representable integer number (2^53-1, because of the 53-bit mantissa in double-precision numbers), the argument is not modified by the function. Double number Rounded up double number floor, fmod 1-24

29 C Runtime Library changevib changevib Change volume identification block #include <io.h> int changevib ( char *volume VOL_DATA *new_vib); volume new_vib Volume name (eg, C ) Pointer to a new VIB (structure of type VOL_DATA, see getvolumestatus) This call dynamically changes a statically configured volume identification block. The call can be used only for volume identification blocks which are dismounted. 0 successful 1 Error Error Codes In the event of an error, errno is set to one of the following values: Error Code EACCESS ENOENT ERANGE The specified volume is mounted Volume not found Unexpected HSFS error code createvib, getvolumestatus 1-25

30 chdir C Runtime Library chdir Change the current working directory (CWD) #include <direct.h> int chdir (char *path); path Pointer to access path of directory chdir set the directory specified by path as the current working directory (CWD). All names of files or directories specified for function calls (eg, fopen, chdir...) refer to this directory unless specified otherwise. The rules which apply for all path names also apply for path. The maximum absolute path length of the current working directory is the value CWD_MA specified in the header file DIRECT.H. As long as a task does not call chdir, the current working directory is empty; ie, absolute pathnames (including drive names) must be specified; this also applies for the first chdir call. 0 successful -1 The CWD was not changed Error Codes In the event of an error, errno is set to one of the following values (if the HSFS reported an error, the resultant error code is also stored in errno2): Error Code E2BIG EINVAL EIO EMFILE ENOTDIR The absolute path name of the new CWD exceeds CWD_MA characters error in path Physical read error Too many opened files or another HSFS limit has been reached A path component is not a directory getcwd 1-26

31 C Runtime Library checkpoint checkpoint Store temporary buffer of file #include <io.h> int checkpoint (int handle); handle Descriptor (return value of open) The function checkpoint forces an updating of the file by copying modified file areas which until then had resided in a temporary buffer to the actual volume. 0 successful 1 Error Error Codes In the event of an errno, errno is set to the following value: Error Code EBADF EINVAL EIO ERANGE handle is not a valid descriptor checkpoint cannot be applied to a socket descriptor Physical I/O error Unexpected HSFS error code open, fflush 1-27

32 chmod C Runtime Library chmod Change file attributes #include <direct.h> int chmod ( char *filename, int pmode); filename pmode Name of file whose attributes are to be set New attributes for the specified file. Valid values: ATR_SYSTEM System file (ignored under ) ATR_HIDDEN Hidden (ignored under ) ATR_RDONLY Write-protected ATR_DIREC Directory (use only for specifying a directory) ATR_LABEL Volume label ATR_ARCH Archive bit (set on file modification) ATR_DEVICE Device driver file Attributes can be ORed to specify several attributes. For the file specified by filename chmod sets the file attributes specified by pmode. 0 successful 1 unsuccessful Error Codes In the event of an error, errno is set to one of the following values: Error Code EACCESS EBUSY EIO EMFILE ENOENT ENOSPC ERANGE Invalid access rights for filename filename has already been with lock option Physical I/O error Internal HSFS limits reached Invalid filename Volume is full Unexpected HSFS error code 1-28

33 C Runtime Library chmod search 1-29

34 clearerr C Runtime Library clearerr Reset the error status of a stream #include <stdio.h> void clearerr(file *stream); stream Stream with structure of type FILE clearerr clears the error status of the specified stream. ferror, feof, fileno 1-30

35 C Runtime Library clock clock Dummy function #include <time.h> long clock (void); clock is designed to determine the time elapsed since the task start. In the CRUN, clock is a dummy function which returns the value -1 to comply with the ANSI standard. -1 is a dummy function 1-31

36 close C Runtime Library close Close an open file, unit of a loadable driver or socket #include <io.h> int close (int handle); handle Descriptor close closes the file or unit associated with handle or the socket associated with a socket descriptor. 0 successful -1 unsuccessful Error Codes In the event of an error, errno is set to one of the following values (if the HSFS reported an error, the resultant error code is also stored in errno2): Error Code EAGAIN EBADF EIO ENOENT ENOMEM ERANGE EPERM This error corresponds to HSFS error messages (-16) and (-22) (it occurs with illegal table of contents operations). Invalid descriptor Physical read/write error Addressed driver not (yet) correctly initialized Not enough memory could be taken from the specified pool. Internal error The socket identified by sd was not created by the calling task (for sockets only). open, fclose, ioctl, socket, nselect 1-32

37 C Runtime Library cos cos Cosine #include <math.h> double cos (double x); handle Descriptor cos calculates the cosine of a double-precision number. For cos the argument must be specified in radians. If the absolute value of the argument exceeds 2^52, cos calls the error handling routine matherr with exception type TLOSS. In this case the return value is IND. For an argument of this magnitude, successive double precision numbers represented in numerical format differ by 0.5. The argument precision, therefore, indicates at best the quadrant. For larger arguments even this information is lost. errno is not set, in line with the ANSI standard. Double number IND Cosine After matherr is called with exception type TLOSS (absolute value of the argument > 2^52) matherr, sin, tan 1-33

38 cosh C Runtime Library cosh Hyperbolic cosine #include <math.h> double cosh (double x); x Double-precision number cosh calculates the hyperbolic cosine (cosh(x) = (e^x + e^ x)/2) from a double-precision number. After an overflow cosh calls the error handling function matherr with exception type OVERFLOW and sets errno to ERANGE. The return value in this case is +HUGE_VAL. Double number +HUGE_VAL Hyperbolic cosine After matherr is called with exception type DOMAIN, errno is set to ERANGE (overflow) matherr, sinh, tanh 1-34

39 C Runtime Library createvib createvib Generate new volume identification block #include <io.h> int createvib ( VOL_DATA *new_vib, int pool_id); new_vib pool_id Pointer to a new VIB (structure of type VOL_DATA, see getvolumestatus) Memory pool from which the necessary data areas are to be allocated The call createvib allows a new VIB to be created dynamically. The volume name must not match the name of an already existing volume. needs 160 bytes for the VIB. If the parameter fat_buf of the structure VOL_DATA is passed a NULL pointer, the buffer size is derived from the boot sector data (the parameter sec_per_fat is multiplied by 512). 0 successful 1 Error Error Codes In the event of an error, errno is set to one of the following values: Error Code EEIST EINVAL ENOMEM ERANGE The new volume name is already known to the HSFS Invalid parameter Insufficient memory in pool Unexpected HSFS error code changevib, getvolumestatus 1-35

40 ctime C Runtime Library ctime Convert date and time to a string #include <time.h> char *ctime (time_t *clock); clock Pointer to an element of type time_t ctime converts a long integer number, as returned by time, to a string and returns a pointer to a 26-byte static data field which holds the date and time of day; the data field has the format: Weekday Month Day Hours:Minutes:Seconds Year\n. Example: Mon Jan \n Pointer to a string containing the date and time Note The return values point to a data area whose contents are overwritten with the next call of the function. ctime(clock) is equivalent to asctime(localtime(clock)). 1-36

41 C Runtime Library ctime Example The following example demonstrates the use of the various CRUN time functions: #include <time.h> main () { struct tm *ptm; char *date; long tadd; putenv ( TZ=MEZ-1 ); time (&tadd); date = ctime (&tadd); printf ( today s date is %s, date); ptm = localtime (&tadd); date = asctime (ptm); printf ( today s date is %s, date); ptm = gmtime (&tadd); date = asctime (ptm); printf ( Greenwich mean time is %s, date); } asctime, gmtime, mktime, localtime, time, tzset 1-37

42 difftime C Runtime Library difftime Determine the length of a time interval #include <time.h> double difftime( time_t time1, time_t time2); time1 time2 Start of time interval End of time interval difftime returns the difference between time1 and time2 in the form of a double-precision number. Double number Number of seconds between time1 and time2 time 1-38

43 C Runtime Library dismount dismount Dismount a device of the HSFS file management system #include <io.h> int dismount (const char *volume_name); volume_name Drive (volume) name dismount dismounts a device from the HSFS file management system. The parameter volume_name must be a valid drive specifier with a length of one or two characters (eg, A, C or M0 ). 0 successful -1 unsuccessful Error Codes In the event of an error, errno is set to one of the following values: Error Code EACCESS EIO ERANGE There are still files opened or volume is not mounted Physical read/write error Unexpected HSFS error code mount 1-39

44 div C Runtime Library div Integer division #include <stdlib.h> div_t div( int i1, int i2); i1 i2 Integer number (numerator) Integer number (denominator) div returns i1/i2 as the result of the division. The quotient is returned in div_t.quot and the remainder in div_t.rem. div_t is declared as follows: typedef struct {int quot; int rem; }div_t; div_t Structure with quotient and remainder ldiv 1-40

45 C Runtime Library duread duread Read character via an driver #include <io.h> size_t duread( int device, int unit, void *buf, size_t nbytes); device unit buf nbytes Device ID of device driver Unit ID of device driver Receive buffer Number of bytes to be transferred duread issues a read request for nbytes to the driver specified by the combination device/unit (eg, BYT driver). The driver completes the read request when nbytes characters have been read, or a CR character is encountered in the input stream. The call is issued with wait for completion. The specified driver must have a BYT driver compatible call interface. > 0 System call successful (the value corresponds to the number of bytes read) -1 System call unsuccessful Error Codes In the event of an error, errno is set to one of the following values: Error Code EBUSY EIO ENIO ERANGE Request was cancelled Unexpected interrupt Invalid device/unit combination Internal error 1-41

46 duread C Runtime Library Note The CRUN does not convert any data read. duwrite 1-42

47 C Runtime Library duwrite duwrite Write characters via an driver #include <io.h> size_t duwrite( int device, int unit, void *buf, size_t nbytes); device unit buf nbytes Device ID of device driver Unit ID of device driver Receive buffer Number of bytes to be transferred duwrite issues a write request for nbytes to the driver specified by the combination device/unit (eg, BYT driver). The characters are taken from the buffer buf. The driver cannot necessarily output all characters. The character \0 terminates the output. The call is issued with wait for completion. The specified driver must have a BYT driver compatible call interface. > 0 System call successful (the value corresponds to the number of bytes written) -1 System call unsuccessful Error Codes In the event of an error, errno is set to one of the following values: Error Code EBUSY EIO ENIO ERANGE Request was cancelled Unexpected interrupt Invalid device/unit combination Internal error 1-43

48 duwrite C Runtime Library Note The CRUN does not convert any data written. duread 1-44

49 C Runtime Library efsstop efsstop Close the connection between a net unit and the server unit #include <io.h> int efsstop ( char * volume ); volume Volume name (eg, N1 ) efsstop closes a connection opened with efsuse. After efsstop the net unit can again be assigned to a server by efsuse. 0 successful!=0 HSFS/EFS error code efsuse 1-45

50 efsuse C Runtime Library efsuse Open a connection between a net unit and the server unit #include <io.h> int efsuse ( char * volume, char *rvolume, efs_addr *naddr, char *nname ); volume rvolume naddr nname Volume name (eg, N1 ) Volume of the remote unit to which net unit access is to be routed. Pointer to a structure containing the net addresse of the remote unit; the net address has the form: typedef struct { short unsigned loctsapid; short unsigned remtsapid; long unsigned subnetid; char unsigned netaddress[6]; short unsigned nsapid; char res1; char medium; char res2; char res3; } efs_addr; Pointer to a string containing the name of the remote unit. This function allows a statically configured volume identification block to be defined dynamically. The function only be applied to dismounted volumes. 0 successful!=0 HSFS/EFS error code efsstop 1-46

51 C Runtime Library errno, errno2 errno, errno2 Error numbers of system calls and library functions #include <errno.h> extern int errno; extern int errno2; The numeric value associated with the symbolic name of an error message is assigned to the external variable errno, if an error occurs during execution of a system call or library function. errno need only be checked, if the return value of a system call indicates an error and it is stated in the call definition that the error number is specified by errno. The value 0 for errno is reserved and does not appear in any error message. An application program which checks the value of errno must contain the header file ERRNO.H. of error messages (numbers) E2BIG (26) The argument list is too long. EACCES (27) No access rights! An attempt was made to access a file while the protection mechanisms of the operating system prohibit an access of this type. EAGAIN (1) Operating resources currently not available, try again at a later stage. EBADF (28) Incorrect descriptor! The descriptor either refers to a file or a unit which has not been opened, or a file or unit is to be read (written) which can only be written (read). EBUSY (2) Device or system resource occupied! An attempt was made to connect a device to a file system which was already connected, or to disconnect a device which is used by a file (eg, an open file or the current directory). EDOM (31) Mathematical argument! The function argument from the library of mathematical functions is outside the valid range. EEIST (32) The object exists already. EFBIG (33) File too large! A file exceeds the maximum file length. EINVAL (5) Invalid parameter value! EIO (36) I/O error! A physical I/O error occurred; this error cannot be reported immediately, but only with the next call to follow the call which caused the error. EISDIR (38) Directory! An attempt was made to write to a directory file. 1-47

52 errno, errno2 C Runtime Library EMFILE (37) Too many open files, sockets and units of loadable drivers! ENODEV (38) Device does not exist! An invalid operation was attempted on a device (eg, read from a device which can only be written to). ENOENT (39) No file or directory exists with this name! A non existent file name was specified, or one of the directories in the pathname does not exist. ENOMEM (42) No memory space available! ENOSPC (44) No space available on the device! There is not enough space on the device to write a file, or to create a directory. ENOTFOUND (51) Object cannot be found. ENOTDIR (45) No directory! No directory was specified, although this was required. ERANGE (49) After arithmetic functions: Result too long or undefined! The function value from the library of mathematical functions cannot be represented with the processor s precision range. After I/O operations: An unkown error code was returned by HSFS. Error handling using errno2 If a function call returns an error number (errno) not equal to 0, a more detailed error check may be possible. This applies to all functions which execute I/O operations via the file system or the BYT driver. In this case an additional variable errno2 is initialized. This variable contains the original status value of the file system or the SVC RmIO. errno errno2 Example #include <errno.h>... errno = 0; errno2 = 0; fclose(fp); if (errno! = 0) { printf( errno: %d, errno2: %d\n, errno, errno2); }... perror, strerror, sys_errlist, sys_err 1-48

53 C Runtime Library exit exit Terminates a task with clean-up operations and fixed status #include <stdlib.h> void exit (int status); status Integer number exit terminates the calling task (DORMANT state). Tasks started by the CLI are deleted (NONEISTENT). Before the task is terminated, certain clean-up operations are performed: Processing routines which were installed with atexit. All streams opened by fopen and fduopen are closed. Files opened with open are not closed unless opened with flag O_CLOSEONEIT. Memory previously requested with malloc, calloc and realloc are returned. In addition, any memory requested with RmAlloc and RmReAlloc is freed unless RM_NOAUTOFREE mode was specified. Under, status is evaluated only by programs started by the CLI. atexit, x_cr_killtsk 1-49

54 exp C Runtime Library exp Exponential function #include <math.> double exp (double x); x Double-precision number exp calculates e^x. e is Euler s constant , the base of the natural logarithm. Both argument and return value are of type double. If the result of exp is outside the representable number range, exp calls the error handling routine matherr with exception type OVERFLOW and sets errno to ER- ANGE. The return value in this case is +HUGE_VAL. If the result is too small, exp calls matherr with exception type UNDERFLOW and sets errno to ERANGE. The return value in this case is IND. Double number IND +HUGE_VAL e^x After matherr is called with exception type UNDER- FLOW, errno is set to ERANGE (e^x too small) After matherr is called with exception type OVER- FLOW, errno is set to ERANGE (e^x outside representable number range) pow 1-50

55 C Runtime Library fabs fabs Determines the absolute value of a double-precision number #include <stdlib.h> double fabs (double value); value Double-precision number fabs returns the absolute value of the double-precision number specified by value. Double number Absolut value Example main () { double z; z = fabs(-7.28); /* Result is 7.28 */ } abs, labs 1-51

56 fclose C Runtime Library fclose Close stream #include <stdio.h> int fclose (FILE *stream); stream Stream with structure of type FILE fclose closes the file assigned to the specified stream. This function is applied automatically to all open files when exit is called. 0 successful EOF unsuccessful fopen, close 1-52

57 C Runtime Library fduopen fduopen Open an driver stream #include <stdio.h> FILE *fduopen( int device, int unit, const char *type); device unit type Device ID of device driver Unit ID of device driver Read/write mode; valid values: r open for read in text mode w open for write in text mode rb open for read in binary mode wb open for write in binary mode fduopen opens a stream. All read/write access operations (depending on *type) are routed via the driver specified by the combination device/ unit. The driver will not necessarily output all characters (eg, the character \0 ). The specified driver must have a BYT driver compatible call interface. Pointer NULL pointer to a stream (function successful) unsuccessful Note When writing in text mode, the character string \n is converted to \r\n ; when reading in text mode, the character string \r\n is converted to \n. No conversion occurs in binary mode. The stream is valid for the calling task only and may only be used by this task. Stream Pointer and descriptors are task specific and may not be interchanged between tasks. fopen 1-53

58 fdureopen C Runtime Library fdureopen Redirect a stream to a driver #include <stdio.h> FILE *fdureopen( int device, int unit, char *mode, FILE *stream); device unit type stream Device ID of device driver to which the stream is to be redirected Unit ID of device driver to which the stream is to be redirected Read/write mode; valid values: r open for read in text mode w open for write in text mode rb open for read in binary mode wb open for write in binary mode Stream which is to be redirected to the driver specified by device/unit fdureopen closes the file assigned to stream, opens the connection to the driver specified by device/unit and and assigns this connection to stream. The specified driver must have a BYT driver compatible call interface. stream NULL pointer successful unsuccessful Error Codes In the event of an error, errno is set to one of the following values: Error Code EBADF EINVAL stream does not specify a valid stream Invalid parameter (mode not valid) 1-54

59 C Runtime Library fdureopen Note Stream Pointer and descriptors are task specific and may not be interchanged between tasks. fduopen, freopen 1-55

60 feof C Runtime Library feof Check the stream status for EOF #include <stdio.h> int feof (FILE *stream); stream Stream with structure of type FILE feof checks whether an (EOF) (end-of-file) occurred during a read access to a stream. 0 File end not reached 0 File end reached ferror, clearerr, fileno 1-56

61 C Runtime Library ferror ferror Check the stream status for an I/O error #include <stdio.h> int ferror (FILE *stream); stream Stream with structure of type FILE ferror checks whether an I/O error occurred during a read/write access to the specified stream. 0 No error 0 Error feof, clearerr, fileno 1-57

62 fflush C Runtime Library fflush Flush a stream buffer #include <stdio.h> int fflush (FILE *stream); stream Stream with structure of type FILE fflush flushes the buffers assigned to stream; if the argument of fflush is an output stream, the associated buffers are output; if it is an input stream, the buffer is flushed; If stream is a NULL pointer the flush function performs the flushing action on buffers of all streams of the calling task. fflush does not close the buffers. 0 successful EOF unsuccessful fopen, close, setbuf, fclose 1-58

63 C Runtime Library fgetc fgetc Read a character from a stream #include <stdio.h> int fgetc (FILE *stream); stream Stream with structure of type FILE fgetc returns the next character in the buffer of the stream specified by stream and sets the file pointer in the stream to the next character. Character EOF successful EOF or error Note If integer values returned by the function fgetc are stored as character variables and compared with the integer constant EOF, the compare operation can terminate with an error, because whether a sign is appended on conversion from a character to an integer is processor-dependent. In text mode, \r\n is converted to \n. fopen, fread, gets, putc, scanf 1-59

64 fgetpos C Runtime Library fgetpos Return the current position in a file #include <stdio.h> int fgetpos( FILE *stream, fpos_t *pos); stream pos Stream with structure of type FILE File pointer fgetpos stores the current position of the file specified by stream in the variable specified by pos. 0 successful 0 unsuccessful Note This function must be used restrictively for streams which were opened in text mode because of the conversion of \n and \r\n. This function can only be used to determine the position in a stream by means of fgetpos and set to this position later using fsetpos. fseek, fsetpos 1-60

65 C Runtime Library fgets fgets Read string from a stream #include <stdio.h> char *fgets( char *s, int n, FILE *stream); s n stream Pointer to destination string number of characters to be read Stream with structure of type FILE fgets reads a string from stream and copies it to the string pointed to by s. It terminates when reading either a CR (\n) or the (n 1)th character. The CR is stored at the end of s. Additionally fgets appends a zero character (\0) in order to mark the end of the stream. s NULL pointer Pointer to destination string (function successful) No characters transferred (eg, EOF was reached before a character was read) or read error during access to a file opened for reading. Note In text mode \r\n is converted to \n. fopen, fread, getc, scanf, gets 1-61

66 fileno C Runtime Library fileno Determine descriptor #include <stdio.h> int fileno (FILE *stream); stream Stream with structure of type FILE fileno returns the descriptor assigned to the specified stream. descriptor of file assigned to stream ferror, feof, clearerr 1-62

67 C Runtime Library floor floor Round down a double number #include <math.h> double floor (double x); x Double-precision number floor rounds down the passed argument to the next integer double-precision number. If the argument for floor is already an integer value, or greater than the largest representable integer number (2^53 1, because of the 53-bit mantissa in double-precision numbers), the argument is not modified by the function. Double number Rounded down double-precision number ceil, fmod 1-63

68 fmod C Runtime Library fmod Determine the remainder after division of two double numbers #include <math.h> double fmod( double x, double y); x y Double precision number (numerator) Double precision number (denominator) fmod determines the remainder after division of x/y. If y equals 0.0, the returned result is 0.0. Double number Remainder ceil, floor 1-64

69 C Runtime Library fopen fopen Open a stream #include <stdio.h> FILE *fopen( char *fname, char *mode); fname mode Pointer to file specification Pointer to access mode fopen opens the file specified by fname with the specified access mode and assigns a stream with structure of type FILE to the file. The access mode can assume one of the following values: r open for read access in text mode w create for write access in text mode (truncate to 0 if the file already exists) a open for write access in text mode (append), or create, if the file does not exist r+ open to update in text mode (read and write access) w+ create to update in text mode (truncate to 0 if the file already exists) a+ open to update in text mode (append), or create, if the file does not exist rb open for read access in binary mode wb create for write access in binary mode (truncate to 0 if file already exists) ab open to append in binary mode (or create if the file does not exist) rb+ open to update (read/write) in binary mode wb+ create to update in binary mode (truncate to 0 if file already exists) ab+ open to update (append) in binary mode or create if file does not exist 1-65

70 fopen C Runtime Library NULL pointer Pointer File cannot be opened (file fname does not permit access, invalid mode, or not any free streams available) to the stream structure (file was opened) Error Codes In the event of an error, errno is set to one of the following values: Error Code EINVAL EIO ENOSPC EBUSY EMFILE ENOTDIR ENOENT EACCES Invalid parameter Physical read/write error Insufficient memory on drive, or directory full File opened by another task Internal buffer overflow Component of pathname prefix is not a directory The specified file or a component of fname does not exist, or the drive has not been mounted (mount). There are no search rights for a component of the pathname prefix, or the access mode specified in mode is not allowed for the file fname. Note When writing in text mode, \n is converted to \r\n. When reading in text mode \r\n is converted to \n. In binary mode there is no conversion. The stream is valid for the calling task only and may only be used by this task. Stream Pointer and descriptors are task specific and may not be interchanged between tasks. fclose, fduopen 1-66