Tru64 UNIX
Compaq C Language Reference Manual


Previous Contents Index

size_t strxfrm(char *s1, const char *s2, size_t n);

Transforms the string pointed to by s2 and places the resulting string into the array pointed to by s1.
See your Compaq C library routine documentation for a detailed description of this function.

char *strchr(const char *s, int c);

Locates the first occurrence of c (converted to a char ) in the string pointed to by s. The terminating null character is considered to be part of the string. The function returns a pointer to the located character, or a null pointer if the character was not found.

size_t strcspn(const char *s1, const char *s2);

Computes the length of the maximum initial segment of the string pointed to by s1 that consists entirely of characters not found in the string pointed to by s2. The strcspn function returns the length of the segment.

char *strpbrk(const char *s1, const char *s2);

Locates the first occurrence in the string pointed to by s1 of any character from the string pointed to by s2. The function returns a pointer to the character, or a null pointer if no character in s1 occurs in s2.

char *strrchr(const char *s, int c);

Locates the last occurrence of c (converted to a char ) in the string pointed to by s. The terminating null character is considered to be part of the string. The function returns a pointer to the located character, or a null pointer if the character was not found.

size_t strspn(const char *s1, const char *s2);

Computes the length of the maximum initial segment of the string pointed to by s1 that consists entirely of characters from the string pointed to by s2. The strspn function returns the length of the segment.

char *strstr(const char *s1, const char *s2);

Locates the first occurrence in the string pointed to by s1 of the sequence of characters (excluding the terminal null character) in the string pointed to by s2. The strstr function returns a pointer to the located string, or a null pointer if the string was not found. If s2 points to a string of zero length, the function returns s1.

char *strtok(const char *s1, char *s2);

Breaks the string pointed to by s1 into a sequence of tokens, each of which is delimited by a character from the string pointed to by s2. The first call to strtok () skips characters, looking for the first one that is not in s2. The function keeps track of its position in the string pointed to by s1 between calls and, as successive calls are made, the function works through this string, identifying the text token following the one identified by the previous call. When the function finds a character in s1 that matches a character in s2, it replaces the character in s1 with a null character. The strtok function returns a pointer to the first character of the token, or a null pointer if there is no token.

char *strerror(int errnum);

Maps the error number in errnum to an error message string; returns a pointer to the string. The string pointed to must not be modified by the program, but can be overwritten by a subsequent call to strerror .

size_t strlen(const char *s);

Computes the length of the string pointed to by s. The function returns the number of characters that precede the terminating null character.

9.16 Type-generic Math (<tgmath.h>)

The header <tgmath.h> includes the headers <math.h> and <complex.h> and defines several type-generic macros.

Of the <math.h> and <complex.h> functions without an f ( float ) or l ( long double ) suffix, several have one or more parameters whose corresponding real type is double . For each such function, except modf , there is a corresponding type-generic macro.1 The parameters whose corresponding real type is double in the function synopsis are generic parameters. Use of the macro invokes a function whose corresponding real type and type domain are determined by the arguments for the generic parameters.2

Note

The type-generic implementation of the absolute value function ( fabs ) is not available for complex types in this release. You must use the type-specific names ( cabs , cabsf , cabsl ) instead.

9.16.1 Real-Type Determination

Use of the macro invokes a function whose generic parameters have the corresponding real type determined as follows:

  1. First, if any argument for generic parameters has type long double , the type determined is long double .
  2. Otherwise, if any argument for generic parameters has type double or is of integer type, the type determined is double .
  3. Otherwise, the type determined is float .

9.16.2 Unsuffixed Functions in (<math.h>) and (<complex.h>) with the Same Name

For each unsuffixed function in <code_example>(<math.h>) for which there is a function in <code_example>(<complex.h>) with the same name except for a c prefix, the corresponding type-generic macro (for both functions) has the same name as the function in <code_example>(<math.h>). The corresponding type-generic macro for fabs and cabs is fabs . These functions are:


  <math.h>     <complex.h>    type-generic 
  function      function         macro 
 -----------   -------------  ------------- 
   acos           cacos          acos 
   asin           casin          asin 
   atan           catan          atan 
   acosh          cacosh         acosh 
   asinh          casinh         asinh 
   atanh          catanh         atanh 
   cos            ccos           cos 
   sin            csin           sin 
   tan            ctan           tan 
   cosh           ccosh          cosh 
   sinh           csinh          sinh 
   tanh           ctanh          tanh 
   exp            cexp           exp 
   log            clog           log 
   pow            cpow           pow 
   sqrt           csqrt          sqrt 
   fabs           cabs           fabs 

If at least one argument for a generic parameter is complex, then use of the macro invokes a complex function; otherwise, use of the macro invokes a real function.

9.16.3 Unsuffixed Functions in (<math.h>) with no c-prefixed Counterpart in (<complex.h>)

For each unsuffixed function in <code_example>(<math.h>) without a c-prefixed counterpart in <code_example>(<complex.h>), the corresponding type-generic macro has the same name as the function. These type-generic macros are:


atan2         fma           llround       remainder 
cbrt          fmax          log10         remquo 
ceil          fmin          log1p         rint 
copysign      fmod          log2          round 
erf           frexp         logb          scalbn 
erfc          hypot         lrint         scalbln 
exp2          ilogb         lround        tgamma 
expm1         ldexp         nearbyint     trunc 
fdim          lgamma        nextafter 
floor         llrint        nexttoward 

If all arguments for generic parameters are real, then use of the macro invokes a real function; otherwise, use of the macro results in undefined behavior.

9.16.4 Unsuffixed Functions in (<complex.h>) that are not c-prefixed Counterparts to Functions in (<math.h>)

For each unsuffixed function in <code_example>(<complex.h>) that is not a c-prefixed counterpart to a function in <code_example>(<math.h>), the corresponding type-generic macro has the same name as the function:


carg          conj          creal 
cimag         cproj 

Use of the macro with any real or complex argument invokes a complex function.

9.16.5 Example

Consider the following declarations:


#include <tgmath.h> 
int n; 
float f; 
double d; 
long double ld; 
float complex fc; 
double complex dc; 
long double complex ldc; 

Given these declarations, functions invoked by use of type-generic macros are as follows:


      macro use               invokes 
   ----------------       ----------------------------- 
   exp(n)                 exp(n), the function 
   acosh(f)               acoshf(f) 
   sin(d)                 sin(d), the function 
   atan(ld)               atanl(ld) 
   log(fc)                clogf(fc) 
   sqrt(dc)               csqrt(dc) 
   pow(ldc, f)            cpowl(ldc, f) 
   remainder(n, n)        remainder(n, n), the function 
   nextafter(d, f)        nextafter(d, f), the function 
   nexttoward(f, ld)      nexttowardf(f, ld) 
   copysign(n, ld)        copysignl(n, ld) 
   ceil(fc)               undefined behavior 
   rint(dc)               undefined behavior 
   fmax(ldc, ld)          undefined behavior 
   carg(n)                carg(n), the function 
   cproj(f)               cprojf(f) 
   creal(d)               creal(d), the function 
   cimag(ld)              cimagl(ld) 
   cabs(fc)               cabsf(fc) 
   carg(dc)               carg(dc), the function 
   cproj(ldc)             cprojl(ldc) 

9.16.6 Imaginary Arguments

Type-generic macros that accept complex arguments also accept imaginary arguments. If an argument is imaginary, the macro expands to an expression whose type is real, imaginary, or complex, as appropriate for the particular function: if the argument is imaginary, then the types of cos , cosh , fabs , carg , cimag , and creal are real; the types of sin , tan , sinh , tanh , asin , atan , asinh , and atanh are imaginary; and the types of the others are complex.

Given an imaginary argument, each of the type-generic macros cos , sin , tan , cosh , sinh , tanh , asin , atan , asinh , atanh is specified by a formula in terms of real functions:


   cos(iy)   = cosh(y) 
   sin(iy)   = i sinh(y) 
   tan(iy)   = i tanh(y) 
   cosh(iy)  = cos(y) 
   sinh(iy)  = i sin(y) 
   tanh(iy)  = i tan(y) 
   asin(iy)  = i asinh(y) 
   atan(iy)  = i atanh(y) 
   asinh(iy) = i asin(y) 
   atanh(iy) = i atan(y) 

Note

1 Like other function-like macros in Standard libraries, each type-generic macro can be suppressed to make available the corresponding ordinary function.

2 If the type of the argument is not compatible with the type of the parameter for the selected function, the behavior is undefined.

9.17 Date and Time (<time.h>)

The <time.h> header file defines two macros, and declares four types and several functions for manipulating time and date information. Some functions process local time, which may differ from calendar time because of time zone.

Types

size_t

An unsigned integral type of the result of the sizeof operator.


clock_t 
time_t 

Arithmetic types capable of representing times.

struct tm

Holds the components of a calendar time, called the broken-down time. The structure contains the following members:


int tm_sec;      /*  seconds after the minute -- [0,61]         */ 
int tm_min;      /*  minutes after the hour -- [0,59]           */ 
int tm_hour;     /*  hours since midnight -- [0,23]             */ 
int tm_mday;     /*  day of the month -- [1,31]                 */ 
int tm_mon;      /*  months since January -- [0,11]             */ 
int tm_year;     /*  years since 1900                           */ 
int tm_wday;     /*  days since Sunday -- [0,6]                 */ 
int tm_yday;     /*  days since January 1 -- [0,365]            */ 
int tm_isdst;    /*  Daylight Saving Time flag -- 0 if          */ 
                 /*  DST not in effect; positive if it is;      */ 
                 /*  negative if information is not available.  */ 

Macros

NULL

Expands to an implementation-defined null pointer constant.

CLOCKS_PER_SEC

The number per second of the value returned by the clock function.

Time Conversion Functions

char *asctime(const struct tm *timeptr);

Converts a broken-down time in the structure pointed to by timeptr into a 26-character string in the form of this example:


Sat Sep 08 08:10:32 1990\n\0 

A pointer to the string is returned.

char *ctime(const time_t *timer);

Converts the calendar time pointed to by timer to local time in a string of the form generated by the asctime function. A pointer to the string is returned. The ctime function is equivalent to the following:


asctime(localtime(timer)) 

struct tm *gmtime(const time_t *timer);

Converts the calendar time pointed to by timer into a broken-down time expressed as Coordinated Universal Time (UTC). The gmtime function returns a pointer to the broken-down time, or a null pointer if UTC is not available.

struct tm *localtime(const time_t *timer);

Converts the calendar time pointed to by timer into a broken-down time expressed as local time. The localtime function returns a pointer to the broken-down time.

size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr);

Places characters into the array pointed to by s as controlled by the string pointed to by format. The format string consists of zero or more conversion specifiers and ordinary multibyte characters. All ordinary multibyte characters (including the terminating null character) are copied unchanged into the array. Each conversion specifier is replaced by the appropriate characters as shown in Table 9-2. The appropriate characters are determined by the LC_TIME category of the current locale and by the values contained in the structure pointed to by timeptr.

Table 9-2 strftime Conversion Specifiers
Specifier Replaced by
%a The locale's abbreviated weekday name
%A The locale's full weekday name
%b The locale's abbreviated month name
%B The locale's full month name
%c The locale's appropriate date and time representation
%d The day of the month as a decimal number (01 -- 31)
%H The hour (24-hour clock) as a decimal number (00 -- 23)
%I The hour (12-hour clock) as a decimal number (01 -- 12)
%j The day of the year as a decimal number (001 -- 366)
%m The month as a decimal number (01 -- 12)
%M The minute as a decimal number (00 -- 59)
%p The locale's equivalent of the AM/PM designations associated with a 12-hour clock
%S The second as a decimal number (00 -- 61)
%U The week number of the year (the first Sunday as the first day of week 1) as a decimal number (00 -- 53)
%w The weekday as a decimal number (0 [Sunday] -- 6)
%W The week number of the year (the first Monday as the first day of week 1) as a decimal number (00 -- 53)
%x The locale's appropriate date representation
%X The locale's appropriate time representation
%y The year without century as a decimal number (00 -- 99)
%Y The year with century as a decimal number
%Z The time zone name or abbreviation, or by no characters if no time zone can be determined
%% %

If the total number of resulting characters including the terminating null character is not more than maxsize , the strftime function returns the number of characters placed into the array pointed to by s, not including the terminating null character. Otherwise, 0 is returned, and the array contents are indeterminate.

Time Manipulation Functions

clock_t clock(void);

Determines the processor time used. The clock function returns the processor time used by the program since the beginning of an event related to the program invocation. To determine the time in seconds, divide the return value by the value of the CLOCKS_PER_SEC macro. If the processor time is not available or cannot be represented, the value returned is (clock_t)-1 . (To measure the time spent in a program, call the clock function at the start of the program and subtract the return value from that of subsequent calls.)

double difftime(time_t time1, time_t time0);

Returns the difference between the two calendar times time1 and time0, expressed in seconds, as a double .

time_t mktime(struct tm*timeptr);

Converts the broken-down time, expressed as local time, in the structure pointed to by timeptr into a calendar time value with the same encoding as that of the values returned by the time function (that is, a value of type time_t ), which it returns. If the calendar time cannot be represented, the value (time_t)-1 is returned.
The original values of the tm_wday and tm_yday time components are ignored, and the original values of the other components are not restricted to the ranges indicated in the previous discussion of struct_tm . Upon successful completion of the function, the values of the tm_wday and tm_yday components are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to the ranges indicated in the discussion of struct_tm . The final value of tm_wday is not set until tm_mon and tm_year are determined.

time_t time(time_t *timer);

Returns the current calendar time. If the calendar time is not available, the value (time_t)-1 is returned.


Previous Next Contents Index
[an error occurred while processing this directive]