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


      a = 5DEECE66D16 = 2736731631558
      c = B16 = 138

The initializer function seed48 :

The returned pointer allows you to restart the pseudorandom sequence at a given point. Use the pointer to copy the previous Xi value into a temporary array. To resume where the original sequence left off, you can call seed48 with a pointer to this array.

See also drand48 , lrand48 , and mrand48 in this section.

Return Values

x A pointer to a 48-bit internal buffer.

seekdir

Sets the position of a directory stream.

Format

#include <dirent.h>

void seekdir (DIR *dir_pointer, long int location);

ARGUMENTS

dir_pointer

A pointer to the dir structure of an open directory.

location

The number of an entry relative to the start of the directory.

DESCRIPTION

This function sets the position of the next readdir operation on the directory stream specified by dir_pointer to the position specified by location. The value of location should be returned from an earlier call to telldir.

If the value of location was not returned by a call to the telldir function, or if there was an intervening call to the rewinddir function on this directory stream, the effect is unspecified.

The type dir , defined in the <dirent.h> header file, represents a directory stream. A directory stream is an ordered sequence of all the directory entries in a particular directory. Directory entries represent files. You can remove files from or add files to a directory asynchronously to the operation of the readdir function.

See readdir , rewinddir , and telldir in this section.

[w]setattr

Activate the video display attribute attr within the window. The setattr function acts on the stdscr window.

Format

#include <curses.h>

int setattr (int attr);

int wsetattr (WINDOW *win, int attr);

ARGUMENTS

win

A pointer to the window.

attr

One of a set of video display attributes, which are blinking, boldface, reverse video, and underlining, and are represented by the defined constants _BLINK, _BOLD, _REVERSE, and _UNDERLINE, respectively. You can set multiple attributes by separating them with a bitwise OR operator (|) as follows: 


setattr(_BLINK | _UNDERLINE);

DESCRIPTION

The setattr and wsetattr functions are specific to DEC C for OpenVMS Systems and are not portable.

Return Values

OK Indicates success.
ERR Indicates an error.

setbuf

Associates a new buffer with an input or output file and potentially modifies the buffering behavior.

Format

#include <stdio.h>

void setbuf (FILE *file_ptr, char *buffer);

ARGUMENTS

file_ptr

A file pointer.

buffer

A pointer to a character array, or a NULL pointer.

DESCRIPTION

You can use this function after the specified file is opened but before any I/O operations are performed.

If buffer is a NULL pointer, then the call is equivalent to a call to setvbuf with the same file_ptr, a NULL buffer pointer, a buffering type of _IONBF (no buffering), and a buffer size of 0.

If buffer is not a NULL pointer, then the call is equivalent to a call to setvbuf with the same file_ptr, the same buffer pointer, a buffering type of _IOFBF, and a buffer size given by the value BUFSIZ (defined in <stdio.h> ). You should, therefore, use BUFSIZ to allocate the buffer argument used in the call to setbuf . For example: 


#include <stdio.h> 
   .
   .
   .
char my_buf[BUFSIZ]; 
   .
   .
   .
setbuf(stdout, my_buf); 
   .
   .
   .

User programs must not depend on the contents of buffer once I/O has been performed on the stream. The DEC C RTL might or might not use buffer for any given I/O operation.

The setbuf function originally allowed programmers to substitute larger buffers in place of the system default buffers in obsolete versions of UNIX. The large default buffer sizes in modern implementations of C make the use of this function unnecessary most of the time. The setbuf function is retained in the ANSI C standard for compatibility with old programs, Digital recommends that new programs use setvbuf instead, since it allows the programmer to bind the buffer size at run time instead of compile time, and it returns a testable result value.

setenv

Inserts or resets the environment variable name in the current environment list.

Format

#include <stdlib.h>

int setenv (const char *name, const char *value, int overwrite);

ARGUMENTS

name

A variable name in the environment variable list.

value

The value for the environment variable.

overwrite

A value of 0 or 1 indicating whether to reset the environment variable, if it exists.

DESCRIPTION

This function inserts or resets the environment variable name in the current environment list. If the variable name does not exist in the list, it is inserted with the value argument. If the variable does exist, the overwrite argument is tested. When the overwrite argument value is:

Return Values

0 Indicates success.
--1 Indicates an error. errno is set to ENOMEM---Not enough memory available to expand the environment list.

setgid

Implemented for program portability and serves no function. It returns 0 (to indicate success).

Format

#include <unistd.h>

gid_t setgid (gid_t group_number);

ARGUMENT

group_number

The group number.

setitimer

Sets the value of interval timers.

Format

#include <time.h>

int setitimer (int which, struct itimerval *value, struct itimerval *ovalue);

ARGUMENTS

which

The type of interval timer. The DEC C RTL only supports ITIMER_REAL.

value

A pointer to an itimerval structure whose members specify a timer interval and the time left to the end of the interval.

ovalue

A pointer to an itimerval structure whose members specify a current timer interval and the time left to the end of the interval.

DESCRIPTION

This function sets the timer specified by which to the value specified by value, returning the previous value of the timer if ovalue is nonzero.

A timer value is defined by the itimerval structure: 


       struct itimerval { 
               struct  timeval it_interval; 
               struct  timeval it_value; 
       };

The value of the itimerval structure members are: as follows
itimerval Member Value Meaning
it_interval = 0 Disables a timer after its next expiration (Assumes it_value is nonzero).
it_interval = nonzero Specifies a value used in reloading it_value when the timer expires.
it_value = 0 Disables a timer.
it_value = nonzero Indicates the time to the next timer expiration.

Time values smaller than the resolution of the system clock are rounded up to this resolution.

The getitimer function provides one interval timer, defined in the <time.h> header file as ITIMER_REAL. This timer decrements in real time. When the timer expires, it delivers a SIGALARM signal.

Note
The interaction between setitimer and any of alarm , sleep , or usleep is unspecified.

Return Values

0 Indicates success.
--1 An error occurred; errno is set to indicate the error.

setjmp

Provides a way to transfer control from a nested series of function invocations back to a predefined point without returning normally. It does not use a series of return statements. The setjmp function saves the context of the calling function in an environment buffer.

Format

#include <setjmp.h>

int setjmp (jmp_buf env);

ARGUMENT

env

The environment buffer, which must be an array of integers long enough to hold the register context of the calling function. The type jmp_buf is defined in the <setjmp.h> header file. The contents of the general-purpose registers, including the program counter (PC), are stored in the buffer.

DESCRIPTION

When setjmp is first called, it returns the value 0. If longjmp is then called, naming the same environment as the call to setjmp , control is returned to the setjmp call as if it had returned normally a second time. The return value of setjmp in this second return is the value supplied by you in the longjmp call. To preserve the true value of setjmp , the function calling setjmp must not be called again until the associated longjmp is called.

The setjmp function preserves the hardware general purpose registers, and the longjmp function restores them. After a longjmp , all variables have their values as of the time of the longjmp except for local automatic variables not marked volatile . These variables have indeterminate values.

The setjmp and longjmp functions rely on the OpenVMS condition-handling facility to effect a nonlocal goto with a signal handler. The longjmp function is implemented by generating a DEC C RTL specified signal that allows the OpenVMS condition-handling facility to unwind back to the desired destination.

The DEC C RTL must be in control of signal handling for any DEC C image. For DEC C to be in control of signal handling, you must establish all exception handlers through a call to the vaxc$establish function. See Section 4.2.5 and the vaxc$establish function in this section for more information.

RESTRICTIONS

You cannot invoke the longjmp function from an OpenVMS condition handler. However, you may invoke longjmp from a signal handler that has been established for any signal supported by the DEC C RTL, subject to the following nesting restrictions:

Return Values

See the Description section.  

setlocale

Selects the appropriate portion of the program's locale as specified by the category and locale arguments. You can use this function to change or query one category or the program's entire current locale.

Format

#include <locale.h>

char *setlocale (int category, const char *locale);

ARGUMENTS

category

The name of the category. Specify LC_ALL to change or query the entire locale. Other valid category names are:

locale

Pointer to a string that specifies the locale.

DESCRIPTION

This function sets or queries the appropriate portion of the program's locale as specified by the category and locale arguments. Specifying LC_ALL for the category argument names the entire locale; specifying the other values name only a portion of the program's locale.

The locale argument points to a character string that identifies the locale to be used. This argument can be one of the following:

Return Values

x Pointer to a string describing the locale.
NULL Indicates an error occurred; errno is set.

Example


#include <errno.h> 
#include <stdio.h> 
#include <locale.h> 
 
/* This test calls setlocale() three times. The second call is for   */ 
/* a nonexistent locale. The third call is for an existing file that */ 
/* is not a locale file.                                             */ 
 
main() 
  { 
  char  *ret_str; 
 
  errno = 0; 
  printf ("setlocale (LC_ALL, \"POSIX\")"); 
  ret_str = (char *)setlocale (LC_ALL, "POSIX"); 
  if (ret_str == NULL) 
   perror("setlocale error"); 
  else 
   printf(" call was succesfull"); 
 
  errno = 0; 
  printf ("\n\nsetlocale (LC_ALL, \"junk.junk_codeset\")"); 
  ret_str = (char *)setlocale (LC_ALL, "junk.junk_codeset"); 
 
  if (ret_str == NULL) 
   perror("\rreturned error"); 
  else 
   printf(" call was succesfull"); 
 
  errno = 0; 
  printf ("\n\nsetlocale (LC_ALL, \"sys$login:login.com\")"); 
  ret_str = (char *)setlocale (LC_ALL, "sys$login:login.com"); 
 
  if (ret_str == NULL) 
   perror("\rreturned error"); 
  else 
   printf(" call was succesfull\n"); 
 
  }

Running the example program produces the following result: 


setlocale (LC_ALL, "POSIX") call was succesfull 
 
setlocale (LC_ALL, "junk.junk_codeset") 
returned error: no such file or directory 
 
setlocale (LC_ALL, "sys$login:login.com") 
returned error: non-translatable vms error code: 0x35C07C 
%c-f-localebad, not a locale file

setstate

Restarts, and changes random number generators.

Format

char *setstate (char *state;)

ARGUMENTS

state

Points to the array of state information.

DESCRIPTION

This function handles restarting and changing random number generators.

Once you initialize a state, the setstate function allows rapid switching between state arrays. The array defined by state is used for further random number generation until the initstate function is called or the setstate function is called again. The setstate function returns a pointer to the previous state array.

After initialization, you can restart a state array at a different point in one of two ways:

See also initstate , and srand48 in this section.

Return Values

x A pointer to the previous state array information.
0 Indicates an error. The state information is damaged. Further specified in the following errno value:
  • EINVAL---The state argument is invalid.

setuid

Implemented for program portability and serves no function. It returns 0 (to indicate success).

Format

#include <unistd.h>

uid_t setuid (uid_t member_number);

ARGUMENT

member_number

The member number.

setvbuf

Associates a buffer with an input or output file and potentially modifies the buffering behavior.

Format

#include <stdio.h>

int setvbuf (FILE *file_ptr, char *buffer, int type, size_t size);

ARGUMENTS

file_ptr

A pointer to a file.

buffer

A pointer to a character array, or a NULL pointer.

type

The buffering type. Use one of the following values defined in <stdio.h> : _IONBF, _IOFBF, _IOLBF.

size

The number of bytes to be used in buffer by the DEC C RTL for buffering this file. A minimum buffer size of 8192 is required.

DESCRIPTION

You can use this function after the file is opened but before any I/O operations are performed.

The ANSI C standard defines the following types of file buffering. In unbuffered I/O, each I/O operation is performed immediately. Output characters or lines are written to the output device before control is returned to the program. Input characters or lines are sent directly to the program without read-ahead by the DEC C RTL.

Previous Next Contents Index