HP C
Run-Time Library Reference Manual for OpenVMS Systems
Previous Contents Index

On successful completion, the glob function returns a value of 0 (zero). The pglob-> gl_pathc field returns the number of matched pathnames and the pglob-> gl_pathv field contains a pointer to a NULL-terminated list of matched and sorted pathnames. If the number of matched pathnames in the pglob-> gl_pathc argument is 0 (zero), the pointer in the pglob-> gl_pathv argument is undefined.

If the glob function terminates because of an error, the function returns one of the nonzero constants GLOB_ABORTED, GLOB_NOMATCH, or GLOB_NOSPACE, defined in the <glob.h> header file. In this case, the pglob argument values are still set as defined above.

If, during the search, a directory is encountered that cannot be opened or read and the errfunc argument value is not NULL, the glob function calls errfunc with the two arguments epath and eerno:

epath---The pathname that failed because a directory could not be opened or read.
eerno---The errno value from a failure specified by the epath argument as set by the opendir , readdir , or stat functions.

If errfunc is called and returns nonzero, or if the GLOB_ERR flag is set in flags, the glob function stops the scan and returns GLOB_ABORTED after setting the pglob argument to reflect the pathnames already scanned. If GLOB_ERR is not set and either errfunc is NULL or errfunc returns zero, the error is ignored.

No errno values are returned.

See also globfree , readdir , and stat .

Return Values

0 Successful completion.
GLOB_ABORTED The scan was stopped because GLOB_ERROR was set or errfunc returned a nonzero value.
GLOB_NOMATCH The pattern does not match any existing pathname, and GLOB_NOCHECK was not set in flags.
GLOB_NOSPACE An attempt to allocate memory failed.

globfree

Frees any space associated with the pglob argument resulting from a previous call to the glob function.

Format

#include <glob.h>

void globfree (glob_t *pglob);

Function Variants The globfree function has variants named _globfree32 and _globfree64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Argument

pglob

Pointer to a previously allocated glob_t structure.

Description

The globfree function frees any space associated with the pglob argument resulting from a previous call to the glob function. The globfree function returns no value.

gmtime, gmtime_r

Converts time units to the broken-down UTC time.

Format

#include <time.h>

struct tm *gmtime (const time_t *timer);

struct tm *gmtime_r (const time_t *timer, struct tm *result); (ISO POSIX-1)

Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-test macros defined enables a local-time-based entry point to the gmtime_r function that is equivalent to the behavior before OpenVMS Version 7.0.

Arguments

timer

Points to a variable that specifies a time value in seconds since the Epoch.

result

A pointer to a tm structure where the result is stored.

The tm structure is defined in the <time.h> header, and is also shown in Table REF-4 in the description of localtime .

Description

The gmtime and gmtime_r functions convert the time (in seconds since the Epoch) pointed to by timer into a broken-down time, expressed as Coordinated Universal Time (UTC), and store it in a tm structure.

The difference between the gmtime_r and gmtime functions is that the former puts the result into a user-specified tm structure where the result is stored. The latter puts the result into thread-specific static memory allocated by the HP C RTL, and which is overwritten by subsequent calls to gmtime ; you must make a copy if you want to save it.

On success, gmtime returns a pointer to the tm structure; gmtime_r returns its second argument. On failure, these functions return the NULL pointer.

Note
Generally speaking, UTC-based time functions can affect in-memory time-zone information, which is processwide data. However, if the system time zone remains the same during the execution of the application (which is the common case) and the cache of timezone files is enabled (which is the default), then the _r variant of the time functions asctime_r , ctime_r , gmtime_r and localtime_r , is both thread-safe and AST-reentrant.

If, however, the system time zone can change during the execution of the application or the cache of timezone files is not enabled, then both variants of the UTC-based time functions belong to the third class of functions, which are neither thread-safe nor AST-reentrant.

Return Values

x Pointer to a tm structure.
NULL Indicates an error; errno is set to the following value:
  • EINVAL -- The timer argument is NULL.

gsignal

Generates a specified software signal, which invokes the action routine established by a signal , ssignal , or sigvec function.

Format

#include <signal.h>

int gsignal (int sig [, int sigcode]);

Arguments

sig

The signal to be generated.

sigcode

An optional signal code. For example, signal SIGFPE---the arithmetic trap signal---has 10 different codes, each representing a different type of arithmetic trap.

The signal codes can be represented by mnemonics or numbers. The arithmetic trap codes are represented by the numbers 1 to 10, but the SIGILL codes are represented by the numbers 0 to 2. The code values are defined in the <signal.h> header file. See Table 4-4 for a list of signal mnemonics, codes, and corresponding OpenVMS exceptions.

Description

Calling the gsignal function has one of the following results:

See Chapter 4 for more information.

See also raise , signal , ssignal , and sigvec .

Return Values

0 Indicates a sig argument that is outside the range defined in the <signal.h> header file; errno is set to EINVAL.
sig Indicates that SIG_IGN (ignore signal) has been established as the action for the signal.
x Indicates that signal , ssignal , or sigvec has established an action function for the signal. That function is called, and its return value is returned by gsignal .

hypot

Returns the length of the hypotenuse of a right triangle.

Format

#include <math.h>

double hypot (double x, double y);

float hypotf (float x, float y); (INTEGRITY SERVERS, ALPHA)

long double hypotl (long double x, long double y); (INTEGRITY SERVERS, ALPHA)

Arguments

x

A real value.

y

A real value.

Description

The hypot functions return the length of the hypotenuse of a right triangle, where x and y represent the perpendicular sides of the triangle. The length is calculated as:

sqrt(x2 + y2)

On overflow, the return value is undefined, and errno is set to ERANGE.

Return Values

x The length of the hypotenuse.
HUGE_VAL Overflow occurred; errno is set to ERANGE.
0 Underflow occurred; errno is set to ERANGE.
NaN x or y is NaN; errno is set to EDOM.

iconv

Converts characters coded in one codeset to characters coded in another codeset.

Format

#include <iconv.h>

size_t iconv (iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);

Arguments

cd

A conversion descriptor. This is returned by a successful call to iconv_open .

inbuf

A pointer to a variable that points to the first character in the input buffer.

inbytesleft

Initially, this argument is a pointer to a variable that indicates the number of bytes to the end of the input buffer (inbuf). When the conversion is completed, the variable indicates the number of bytes in inbuf not converted.

outbuf

A pointer to a variable that points to the first available byte in the output buffer. The output buffer contains the converted characters.

outbytesleft

Initially, this argument is a pointer to a variable that indicates the number of bytes to the end of the output buffer (outbuf). When the conversion is completed, the variable indicates the number of bytes left in outbuf.

Description

The iconv function converts characters in the buffer pointed to by inbuf to characters in another code set. The resulting characters are stored in the buffer pointed to by outbuf. The conversion type is specified by the conversion descriptor cd. This descriptor is returned from a successful call to iconv_open .

If an invalid character is found in the input buffer, the conversion stops after the last successful conversion. The variable pointed to by inbytesleft is updated to reflect the number of bytes in the input buffer that are not converted. The variable pointed to by outbytesleft is updated to reflect the number of bytes remaining in the output buffer.

Return Values

x Number of nonidentical conversions performed. Indicates successful conversion. In most cases, 0 is returned.
( size_t ) - 1 Indicates an error condition. The function sets errno to one of the following:
  • EBADF -- The cd argument is not a valid conversion descriptor.
  • EILSEQ -- The conversion stops when an invalid character detected.
  • E2BIG -- The conversion stops because of insufficient space in the output buffer.
  • EINVAL -- The conversion stops because of an incomplete character at the end of the input buffer.

iconv_close

Deallocates a specified conversion descriptor and the resources allocated to the descriptor.

Format

#include <iconv.h>

int iconv_close (iconv_t cd);

Argument

cd

The conversion descriptor to be deallocated. A conversion descriptor is returned by a successful call to iconv_open .

Return Values

0 Indicates that the conversion descriptor was successfully deallocated.
- 1 Indicates an error occurred. The function sets errno to one of the following:
  • EBADF -- The cd argument is not a valid conversion descriptor.
  • EVMSERR -- Nontranslatable OpenVMS error occur. vaxc$errno contains the VMS error code.

iconv_open

Allocates a conversion descriptor for a specified codeset conversion.

Format

#include <iconv.h>

iconv_t iconv_open (const char *tocode, const char *fromcode);

Arguments

tocode

The name of the codeset to which characters are converted.

fromcode

The name of the source codeset. See Chapter 10 for information on obtaining a list of currently available codesets or for details on adding new codesets.

Return Values

x A conversion descriptor. Indicates the call was successful. This descriptor is used in subsequent calls to iconv
(iconv_t) - 1 Indicates an error occurred. The function sets errno to one of the following:
  • EMFILE -- The process does not have enough I/O channels to open a file.
  • ENOMEM -- Insufficient space is available.
  • EINVAL -- The conversion specified by fromcode and tocode is not supported.
  • EVMSERR -- Nontranslatable OpenVMS error occur. vaxc$errno contains the OpenVMS error code. A value of SS$_BADCHKSUM in vaxc$errno indicates that a conversion table file was found, but its contents is corrupted. A value of SS$_IDMISMATCH in vaxc$errno indicates that the conversion table file version does not match the version of the C Run-Time Library.

Example


#include <stdio.h> 
#include <iconv.h> 
#include <errno.h> 
 
 
int main() 
{ 
  /* Declare variables to be used                      */ 
 
  char fromcodeset[30]; 
  char tocodeset[30]; 
  int iconv_opened; 
  iconv_t iconv_struct;       /* Iconv descriptor      */ 
 
  /* Initialize variables                              */ 
 
  sprintf(fromcodeset, "DECHANYU"); 
  sprintf(tocodeset, "EUCTW"); 
  iconv_opened = FALSE; 
 
  /* Attempt to create a conversion descriptor for the */ 
  /* codesets specified. If the return value from      */ 
  /* iconv_open is -1 then an error has occurred.      */ 
  /*  Check the value of errno.                        */ 
 
  if ((iconv_struct = iconv_open(tocodeset, fromcodeset)) 
     == (iconv_t) - 1) { 
 
      /* Check the value of errno                      */ 
 
      switch (errno) { 
      case EMFILE: 
      case ENFILE: 
          printf("Too many iconv conversion files open\n"); 
          break; 
 
      case ENOMEM: 
          printf("Not enough memory\n"); 
          break; 
 
      case EINVAL: 
          printf("Unsupported conversion\n"); 
          break; 
 
      default: 
          printf("Unexpected error from iconv_open\n"); 
          break; 
     } 
  } 
  else 
 
      /* Successfully allocated a conversion descriptor   */ 
 
      iconv_opened = TRUE; 
 
  /*  Was a conversion descriptor allocated               */ 
 
   if (iconv_opened) { 
 
      /* Attempt to deallocate the conversion descriptor. */ 
      /* If iconv_close returns -1 then an error has      */ 
      /* occurred.                                        */ 
 
      if (iconv_close(iconv_struct) == -1) { 
 
          /* An error occurred. Check the value of errno  */ 
 
          switch (errno) { 
          case EBADF: 
              printf("Conversion descriptor is invalid\n"); 
              break; 
          default: 
              printf("Unexpected error from iconv_close\n"); 
              break; 
          } 
      } 
  } 
  return (EXIT_FAILURE); 
}

ilogb (INTEGRITY SERVERS, ALPHA)

Returns the exponent part of its argument.

Format

#include <math.h>

int ilogb (double x);

int ilogbf (float x);

int ilogbl (long double x);

Argument

x

A real value.

Description

The ilogb functions return the exponent part of their argument x. Formally, the return value is the integral part of logr|x| as a signed integral value, for nonzero x, where r is the radix of the machine's floating-point arithmetic, which is the value of FLT_RADIX defined in <float.h> .

Return Values

n Upon success, the exponent part of x as a signed integer value. These functions are equivalent to calling the corresponding logb function and casting the returned value to type int .

[w]inch

Return the character at the current cursor position on the specified window without making changes to the window. The inch function acts on the stdscr window.

Format

#include <curses.h>

char inch();

char winch (WINDOW *win);

Argument

win

A pointer to the window.

Return Values

x The returned character.
ERR Indicates an input error.

index

Searches for a character in a string.

Format

#include <strings.h>

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

Function Variants The index function has variants named _index32 and _index64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

s

The string to search.

c

The character to search for.

Description

The index function is identical to the strchr function, and is provided for compatibility with some UNIX implementations.

initscr

Initializes the terminal-type data and all screen functions. You must call initscr before using any of the curses functions.

Format

#include <curses.h>

void initscr (void);

Description

The OpenVMS Curses version of the initscr function clears the screen before doing the initialization. The BSD-based Curses version does not.

Previous Next Contents Index