[an error occurred while processing this directive]

HP OpenVMS Systems

C Programming Language
Content starts here HP C

HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


snprintf

Performs formatted output to a string in memory.

Format

#include <stdio.h>

int snprintf (char *str, size_t n, const char *format_spec, ...);


Arguments

str

The address of the string that will receive the formatted output.

n

The size of the buffer referred to by str.

format_spec

A pointer to a character string that contains the format specification. For more information about format specifications and conversion characters, see Chapter 2.

...

Optional expressions whose resultant types correspond to conversion specifications given in the format specification.

If no conversion specifications are given, you may omit the output sources. Otherwise, the function calls must have at least as many output sources as there are conversion specifications, and the conversion specifications must match the types of the output sources.

Conversion specifications are matched to output sources in left-to-right order. Excess output pointers, if any, are ignored.


Description

The snprintf function is identical to the sprintf function with the addition of the n argument, which specifies the size of the buffer referred to by str.

On successful completion, snprintf returns the number of bytes (excluding the terminating null byte) that would be written to str if n is sufficiently large.

If n is 0, nothing is written, the number of bytes (excluding the terminating null) that would be written if n were sufficiently large are returned, and str might be a NULL pointer. Otherwise, output bytes beyond the n - 1st are discarded instead of being written to the array, and a null byte is written at the end of the bytes actually written into the array.

If an output error is encountered, a negative value is returned.

For a complete description of the format specification and the output source, see Chapter 2.


Return Values

x The number of bytes (excluding the terminating null byte) that would be written to str if n is sufficiently large.
Negative value Indicates an output error occurred. The function sets errno . For a list of errno values set by this function, see fprintf .

sprintf

Performs formatted output to a string in memory.

Format

#include <stdio.h>

int sprintf (char *str, const char *format_spec, ...);


Arguments

str

The address of the string that will receive the formatted output. It is assumed that this string is large enough to hold the output.

format_spec

A pointer to a character string that contains the format specification. For more information about format specifications and conversion characters, see Chapter 2.

...

Optional expressions whose resultant types correspond to conversion specifications given in the format specification.

If no conversion specifications are given, you may omit the output sources. Otherwise, the function calls must have at least as many output sources as there are conversion specifications, and the conversion specifications must match the types of the output sources.

Conversion specifications are matched to output sources in left-to-right order. Excess output pointers, if any, are ignored.


Description

The sprintf function places output followed by the null character (\0) in consecutive bytes starting at *str. The user must ensure that enough space is available.

Consider the following example of a conversion specification:


#include <stdio.h> 
 
main() 
{ 
   int  temp = 4, temp2 = 17; 
   char s[80]; 
 
   sprintf(s, "The answers are %d, and %d.", temp, temp2); 
} 

In this example, character string s has the following contents:


The answers are 4, and 17. 

For a complete description of the format specification and the output source, see Chapter 2.


Return Values

x The number of characters placed in the output string, not including the final null character.
Negative value Indicates an output error occurred. The function sets errno . For a list of errno values set by this function, see fprintf .

sqrt

Returns the square root of its argument.

Format

#include <math.h>

double sqrt (double x);

float sqrtf (float x); (ALPHA, I64)

long double sqrtl (long double x); (ALPHA, I64)


Argument

x

A real number.

Return Values

val The square root of x, if x is nonnegative.
0 x is negative; errno is set to EDOM.
NaN x is NaN; errno is set to EDOM.

srand

Initializes the pseudorandom-number generator rand .

Format

#include <math.h>

void srand (unsigned int seed);


Argument

seed

An unsigned integer.

Description

The srand function uses the argument as a seed for a new sequence of pseudorandom numbers to be returned by subsequent calls to rand .

If srand is then called with the same seed value, the sequence of pseudorandom numbers is repeated.

If rand is called before any calls to srand , the same sequence of pseudorandom numbers is generated as when srand is first called with a seed value of 1.


srand48

Initializes a 48-bit random-number generator.

Format

#include <stdlib.h>

void srand48 (long int seed_val);


Argument

seed_val

The initialization value to begin randomization. Changing this value changes the randomization pattern.

Description

The srand48 function initializes the random-number generator. You can use this function in your program before calling the drand48 , lrand48 , or mrand48 functions. (Although it is not recommended practice, constant default initializer values are automatically supplied if you call drand48 , lrand48 , or mrand48 without calling an initialization function).

The function works by generating a sequence of 48-bit integer values, Xi, according to the linear congruential formula:


       Xn+1 = (aXn+c)mod m        n >= 0 

The argument m equals 248 , so 48-bit integer arithmetic is performed. Unless you invoke the lcong48 function, the multiplier value a and the addend value c are:


      a = 5DEECE66D16 = 2736731631558
      c = B16 = 138

The initializer function srand48 sets the high-order 32 bits of Xi to the low-order 32 bits contained in its argument. The low-order 16 bits of Xi are set to the arbitrary value 330E _16 .

See also drand48 , lrand48 , and mrand48 .


srandom

Initializes the pseudorandom-number generator random .

Format

int srandom (unsigned seed);


Argument

seed

An initial seed value.

Description

The srandom function uses the argument as a seed for a new sequence of pseudorandom numbers to be returned by subsequent calls to random . This function has virtually the same calling sequence and initialization properties as the srand function, but produce sequences that are more random.

The srandom function initializes the current state with the initial seed value. The srandom function, unlike the srand function, does not return the old seed because the amount of state information used is more than a single word.

See also rand , srand , random , setstate , and initstate .


Return Values

0 Indicates success. Initializes the state seed.
- 1 Indicates an error, further specified in the global errno .

sscanf

Reads input from a character string in memory, interpreting it according to the format specification.

Format

#include <stdio.h>

int sscanf (const char *str, const char *format_spec, ...);


Arguments

str

The address of the character string that provides the input text to sscanf .

format_spec

A pointer to a character string that contains the format specification. For more information about format specifications and conversion characters, see Chapter 2.

...

Optional expressions whose resultant types correspond to conversion specifications given in the format specification.

If no conversion specifications are given, you can omit the input pointers. Otherwise, the function calls must have at least as many input pointers as there are conversion specifications, and the conversion specifications must match the types of the input pointers.

Conversion specifications are matched to input sources in left-to-right order. Excess input pointers, if any, are ignored.


Description

The following is an example of a conversion specification:


main () 
{ 
   char str[] = "4 17"; 
   int   temp, 
         temp2; 
 
   sscanf(str, "%d %d", &temp, &temp2); 
   printf("The answers are %d and %d.", temp, temp2); 
} 

This example produces the following output:


$ RUN  EXAMPLE
The answers are 4 and 17.

For a complete description of the format specification and the input pointers, see Chapter 2.


Return Values

x The number of successfully matched and assigned input items.
EOF Indicates that a read error occurred before any conversion. The function sets errno . For a list of the values set by this function, see fscanf .

ssignal

Allows you to specify the action to take when a particular signal is raised.

Format

#include <signal.h>

void (*ssignal (int sig, void (*func) (int, ...))) (int, ...);


Arguments

sig

A number or mnemonic associated with a signal. The symbolic constants for signal values are defined in the <signal.h> header file (see Chapter 4).

func

The action to take when the signal is raised, or the address of a function that is executed when the signal is raised.

Description

The ssignal function is equivalent to the signal function except for the return value on error conditions.

Since the signal function is defined by the ANSI C standard and the ssignal function is not, use signal for greater portability.

See Section 4.2 for more information on signal handling.


Return Values

x The address of the function previously established as the action for the signal. The address may be the value SIG_DFL (0) or SIG_IGN (1).
0 Indicates errors. For this reason, there is no way to know whether a return status of 0 indicates failure, or whether it indicates that a previous action was SIG_DFL (0).

[w]standend

Deactivate the boldface attribute for the specified window. The standend function operates on the stdscr window.

Format

#include <curses.h>

int standend (void);

int wstandend (WINDOW *win);


Argument

win

A pointer to the window.

Description

The standend and wstandend functions are equivalent to clrattr and wclrattr called with the attribute _BOLD.

Return Values

OK Indicates success.
ERR Indicates an error.

[w]standout

Activate the boldface attribute of the specified window. The standout function acts on the stdscr window.

Format

#include <curses.h>

int standout (void);

int wstandout (WINDOW *win);


Argument

win

A pointer to the window.

Description

The standout and wstandout functions are equivalent to setattr and wsetattr called with the attribute _BOLD.

Return Values

OK Indicates success.
ERR Indicates an error.

stat

Accesses information about the specified file.

Format

#include <stat.h>

int stat (const char *file_spec, struct stat *buffer); (ISO POSIX-1)

int stat (const char *file_spec, struct stat *buffer, ...); (HP C EXTENSION)

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 stat function that is equivalent to the behavior before OpenVMS Version 7.0.

Compiling with the _USE_STD_STAT feature-test macro defined enables a variant of the stat function that uses an X/Open standard-compliant definition of the stat structure. The _USE_STD_STAT feature-test macro is mutually exclusive with the _DECC_V4_SOURCE and _VMS_V6_SOURCE macros.


Arguments

file_spec

A valid OpenVMS or UNIX style file specification (no wildcards). Read, write, or execute permission of the named file is not required, but you must be able to reach all directories listed in the file specification leading to the file. For more information about UNIX style file specifications, see Chapter 1.

buffer

A pointer to a structure of type stat . For convenience, a typedef stat_t is defined as struct stat in the <stat.h> header file.

This argument receives information about the particular file. The members of the structure pointed to by buffer are described in the Description section.

...

An optional default file-name string.

This is the only optional RMS keyword that can be specified for the stat function. See the description of the creat function for the full list of optional RMS keywords and their values.


Description

When the _USE_STD_STAT feature-test macro is not enabled, the legacy stat structure is used. When _USE_STD_STAT is enabled, the X/Open standard-compliant stat structure is used.

Legacy stat Structure

With the _USE_STD_STAT feature-test macro defined to DISABLE, the following legacy stat structure is used:

Member Type Definition
st_dev dev_t Pointer to the physical device name
st_ino[3] ino_t Three words to receive the file ID
st_mode mode_t File "mode" (prot, dir,...)
st_nlink nlink_t For UNIX system compatibility only
st_uid uid_t Owner user ID
st_gid gid_t Group member: from st_uid
st_rdev dev_t UNIX system compatibility -- always 0
st_size off_t File size, in bytes. For st_size to report a correct value, you need to flush both the C RTL and RMS buffers.
st_atime time_t File access time; always the same as st_mtime
st_mtime time_t Last modification time
st_ctime time_t File creation time
st_fab_rfm char Record format
st_fab_rat char Record attributes
st_fab_fsz char Fixed header size
st_fab_mrs unsigned Record size

The types dev_t , ino_t , off_t , mode_t , nlink_t , uid_t , gid_t , and time_t , are defined in the <stat.h> header file. However, when compiling for compatibility (/DEFINE=_DECC_V4_SOURCE), only dev_t , ino_t , and off_t are defined.

The off_t data type is either a 32-bit or 64-bit integer. The 64-bit interface allows for file sizes greater than 2 GB, and can be selected at compile time by defining the _LARGEFILE feature-test macro as follows:


CC/DEFINE=_LARGEFILE 

As of OpenVMS Version 7.0, times are given in seconds since the Epoch (00:00:00 GMT, January 1, 1970).

The st_mode structure member is the status information mode defined in the <stat.h> header file. The st_mode bits are described as follows:

Bits Constant Definition
0170000 S_IFMT Type of file
0040000 S_IFDIR Directory
0020000 S_IFCHR Character special
0060000 S_IFBLK Block special
0100000 S_IFREG Regular
0030000 S_IFMPC Multiplexed char special
0070000 S_IFMPB Multiplexed block special
0004000 S_ISUID Set user ID on execution
0002000 S_ISGID Set group ID on execution
0001000 S_ISVTX Save swapped text even after use
0000400 S_IREAD Read permission, owner
0000200 S_IWRITE Write permission, owner
0000100 S_IEXEC Execute/search permission, owner

The stat function does not work on remote network files.

If the file is a record file, the st_size field includes carriage-control information. Consequently, the st_size value will not correspond to the number of characters that can be read from the file.

Also be aware that for st_size to report a correct value, you need to flush both the C RTL and RMS buffers.

Standard-Compliant stat Structure

With OpenVMS Version 8.2, the _USE_STD_STAT feature-test macro and standard-compliant stat structure are introduced in support of UNIX compatibility.

With _USE_STD_STAT defined to ENABLE, you get the following behavior:

  • Old struct stat definitions
    Old definitions of struct stat are obsolete. You must recompile your applications to access the new features. Existing applications will continue to access the old definitions and functions unless they are recompiled to use the new features.
  • Function variants
    Calls to stat , fstat , lstat , and ftw accept pointers to structures of the new type. Calls to these functions are mapped to the new library entries __std_stat , __std_fstat , __std_lstat , and __std_ftw , respectively.
  • Compatibilities with other feature macros
    _DECC_V4_SOURCE source-code compatibility is not supported. You must not enable _DECC_V4_SOURCE and _USE_STD_STAT at the same time.
    _VMS_V6_SOURCE binary compatibility is not supported. You must not enable _VMS_V6_SOURCE and _USE_STD_STAT at the same time. As a result, only UTC (rather than local-time) is supported for the time_t fields.
  • Type changes
    The following type changes are in effect:
    • 32-bit gid type gid_t is used. _DECC_SHORT_GID_T is unsupported.
    • _LARGEFILE offsets are used. off_t is forced to 64 bits.
    • Type ino_t , representing the file number, is an unsigned int quadword (64 bits). Previously, it was an unsigned short .
    • Type dev_t , representing the device id, is an unsigned int quadword (64 bits). Previously, it was a 32-bit character pointer. The new type is standard because it is arithmetic.
    • Types blksize_t and blkcnt_t are added and defined as unsigned int quadwords (64 bits).
  • Structure member Changes