| Previous | Contents | Index |
See also ctime , localtime , mktime , strftime , and wcsftime in this section.
| #1 |
|---|
EST5EDT4,M4.1.0,M10.5.0 |
This sample TZ specification describes the rule defined in 1987 for the Eastern time zone in the US:
- EST (Eastern Standard Time) is the designation for standard time, which is 5 hours behind UTC.
- EDT (Eastern Daylight Time) is the designation for summer time, which is 4 hours behind UTC. EDT starts on the first Sunday in April and ends on the last Sunday in October.
Because time was not specified in either case, the changes occur at the default time, which is 2:00 a.m. The start and end dates did not need to be specified, because they are the defaults.
Sets or changes the timeout of interval timers.
#include <unistd.h>useconds_t ualarm (useconds_t mseconds, useconds_t interval);
mseconds
Specifies a number of real time microseconds.interval
Specifies the interval for repeating the timer.
This function causes the sigalrm signal to be generated for the calling process after the number of real-time microseconds specified by useconds has elapsed. When the interval argument is nonzero, repeated timeout notification occurs with a period in microseconds specified by interval. If the notification signal sigalrm is not caught or is ignored, the calling process is terminated.If you call a combination of ualarm and setitimer functions, and the AST status is disabled, the return value is invalid.
If you call a combination of ualarm and setitimer functions, and the AST status is enabled, the return value is valid.
This is because you cannot invoke an AST handler to clear the previous value of the timer when ASTs are disabled or invoked from a handler that was invoked at AST level.
Note
Interactions between ualarm and either alarm , or sleep are unspecified.See also setitimer in this section.
n The number of microseconds remaining from the previous ualarm or setitimer call. 0 No timeouts are pending or ualarm not previously called. --1 Indicates an error.
Creates a file protection mask that is used when a new file is created, and returns the previous mask value.
#include <stat.h>mode_t umask (mode_t mode_complement);
mode_complement
Shows which bits to turn off when a new file is created. See the description of chmod to determine what the bits represent.
Initially, the file protection mask is set from the current process's default file protection. This is done when the C main program starts up or when decc$crtl_init (or vaxc$crtl_init ) is called. You can change this for all files created by your program by calling umask or you can use chmod to change the file protection on individual files. The file protection of a file created by open or creat is the bitwise AND of the open and creat mode argument with the complement of the value passed to umask on the previous call.
Note
The way to create files with OpenVMS RMS default protections using the UNIX system-call functions umask , mkdir , creat , and open is to call mkdir , creat , and open with a file-protection mode argument of 0777 in a program that never specifically calls umask . These default protections include correctly establishing protections based on ACLs, previous versions of files, and so on.
In programs that do vfork / exec calls, the new process image inherits whether umask has ever been called or not from the calling process image. The umask setting and whether the umask function has ever been called are both inherited attributes.
x The old mask value.
Gets system identification information.
#include <utsname.h>int uname (struct utsname *name);
name
The current system identifier.
This function stores null-terminated strings of information identifying the current system into the structure referenced by the name argument.The utsname structure is defined in the <utsname.h> header file and contains the following members:
sysname Name of the operating system implementation nodename Network name of this machine release Release level of the operating system version Version level of the operating system machine Machine hardware platform
0 Indicates success. --1 Indicates an error; errno or vaxc$errno is set as appropriate.
Pushes a character back into the input stream and leaves the stream positioned before the character.
#include <stdio.h>int ungetc (int character, FILE *file_ptr);
character
A value of type int .file_ptr
A file pointer.
When using this function, the character is pushed back onto the file indicated by file_ptr.One pushback is guaranteed, even if there has been no previous activity on the file. The fseek function erases all memory of pushed-back characters. The pushed-back character is not written to the underlying file. If the character to be pushed back is EOF, the operation fails, the input stream is left unchanged, and EOF is returned.
See also fseek and getc in this section.
x The push-back character. EOF Indicates it cannot push the character back.
Pushes a wide character back into the input stream.
#include <wchar.h>wint_t ungetwc (wint_t wc, FILE *file_ptr);
wc
A value of type wint_t .file_ptr
A file pointer.
When using this function, the wide character is pushed back onto the file indicated by file_ptr.One push-back is guaranteed, even if there has been no previous activity on the file. If a file positioning function (such as fseek ) is called before the pushed back character is read, the bytes representing the pushed back character are lost.
If the character to be pushed back is WEOF, the operation fails, the input stream is left unchanged, and WEOF is returned.
See also getwc in this section.
x The push-back character. WEOF Indicates that the function cannot push the character back. errno is set to one of the following:
- EBADF -- The file descriptor is not valid.
- EALREADY -- Operation is already in progress on the same file.
- EILSEQ -- Invalid wide-character code detected.
Deletes all instances of the environment variable name from the environment list.
#include <stdlib.h>void unsetenv (const char *name);
name
The environment variable to delete from the environment list.
This function deletes all instances of the variable name pointed to by the name argument from the environment list.
Suspends execution for an interval.
#include <unistd.h>int usleep (unsigned int mseconds);
mseconds
The number of microseconds to suspend execution for.
This function suspends the current process from execution for the number of microseconds specified by the mseconds argument. This argument must be less than 1,000,000. However, if its value is 0, then the call has no effect.There is one real-time interval timer for each process. The usleep function does not interfere with a previous setting of this timer. If the process set this timer before calling usleep and if the time specified by mseconds equals or exceeds the interval timer's prior setting, then the process is awakened shortly before the timer was set to expire.
0 Indicates success. --1 Indicates an error occurred; errno is set to EINVAL.
Allows you to call the DEC C RTL from other languages or to use the DEC C RTL when your main function is not in C. It initializes the run-time environment and establishes both an exit and condition handler. vaxc$crtl_init is a synonym for decc$crtl_init . Either name invokes the same routine.
#include <signal.h>void VAXC$CRTL_INIT();
The following example shows a Pascal program that calls the DEC C RTL using the vaxc$crtl_init function:On OpenVMS VAX systems:
$ PASCAL EXAMPLE $ LINK EXAMPLE,SYS$LIBRARY:DECCRTL/LIB $ TY EXAMPLE.PAS PROGRAM TESTC(input, output); PROCEDURE VAXC$CRTL_INIT; extern; BEGIN VAXC$CRTL_INIT; END $On OpenVMS Alpha systems:
$ PASCAL EXAMPLE $ LINK EXAMPLE,SYS$LIBRARY:VAXCRTL/LIB $ TY EXAMPLE.PAS PROGRAM TESTC(input, output); PROCEDURE VAXC$CRTL_INIT; extern; BEGIN VAXC$CRTL_INIT; END $A shareable image need only call this function if it contains a DEC C function for signal handling, environment variables, I/O, exit handling, a default file protection mask, or if it is a child process that should inherit context.
Although many of the initialization activities are performed only once, decc$crtl_init can safely be called multiple times. On OpenVMS VAX systems, decc$crtl_init establishes the DEC C RTL internal OpenVMS exception handler in the frame of the routine that calls decc$crtl_init each time decc$crtl_init is called.
At least one frame in the current call stack must have that handler established for OpenVMS exceptions to get mapped to UNIX signals.
Used for establishing an OpenVMS exception handler for a particular routine. This function establishes a special DEC C RTL exception handler in the routine that called it. This special handler catches all RTL-related exceptions that occur in later routines, and passes on all other exceptions to your handler.
#include <signal.h>void VAXC$ESTABLISH (unsigned int (*exception_handler)(void *sigarr, void *mecharr));
exception_handler
The name of the function that you want to establish as an OpenVMS exception handler. You pass a pointer to this function as the parameter to VAXC$ESTABLISH.sigarr
A pointer to the signal array.mecharr
A pointer to the mechanism array.
vaxc$establish must be used in place of LIB$ESTABLISH when programs use the DEC C RTL routines setjmp or longjmp . See setjmp and longjmp , or sigsetjmp and siglongjmp in this section.You can only invoke the vaxc$establish function from a DEC C for OpenVMS function, because it relies on the allocation of data space on the run-time stack by the DEC C compiler. Calling the OpenVMS system library routine LIB$ESTABLISH directly from a DEC C function results in undefined behavior from the setjmp and longjmp functions.
To cause an OpenVMS exception to generate a UNIX style signal, user exception handlers must return SS$_RESIGNAL upon receiving any exception that they do not want to handle. Returning SS$_NORMAL prevents the generation of a UNIX style signal. UNIX signals are generated as if by an exception handler in the stack frame of the main C program. Not all OpenVMS exceptions correspond to UNIX signals. See Chapter 4 for more information on the interaction of OpenVMS exceptions and UNIX style signals.
Calling vaxc$establish with an argument of NULL cancels an existing handler in that routine.
Notes
- On OpenVMS Alpha systems, VAXC$ESTABLISH is implemented as a compiler built-in function, not as a DEC C RTL function. (ALPHA ONLY)
- On OpenVMS VAX systems, programs compiled with /NAMES=AS_IS should link against SYS$LIBRARY:DECCRTL.OLB to resolve the name VAXC$ESTABLISH, whether or not the program is compiled with the /PREFIX_LIBRARY_ENTRIES switch. This is a restriction in the implementation. (VAX ONLY)
Used for returning the next item in the argument list.
#include <stdarg.h>(ANSI C) #include <varargs.h>
(DEC C EXTENSION) type va_arg (va_list ap, type);
ap
A variable list containing the next argument to be obtained.type
A data type that is used to determine the size of the next item in the list. An argument list can contain items of varying sizes, but the calling routine must determine what type of argument is expected since it cannot be determined at run time.
This function interprets the object at the address specified by the list incrementor according to type. If there is no corresponding argument, the behavior is undefined.When using va_arg to write portable applications, include the <stdarg.h> header file (defined by the ANSI C standard), not the <varargs.h> header file, and use va_arg only in conjunction with other functions and macros defined in <stdarg.h> .
For an example of argument-list processing using the <stdarg.h> functions and definitions, see Chapter 3, Example 3-6.
Returns the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) in the argument list.
#include <varargs.h>(DEC C EXTENSION) #include <stdargs.h>
(DEC C EXTENSION) void va_count (int count);
count
An integer variable name in which the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) is returned.
This function places the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) in the argument list into count. The value returned in count is the number of longwords (VAX ONLY) or quadwords (ALPHA ONLY) in the function argument block not counting the count field itself.If the argument list contains items whose storage requirements are a longword (VAX ONLY) or quadword (ALPHA ONLY) of memory or less, the number in the count argument is also the number of arguments. However, if the argument list contains items that are longer than a longword (VAX ONLY) or a quadword (ALPHA ONLY), count must be interpreted to obtain the number of arguments. Because a double is 8 bytes, it occupies two argument-list positions on OpenVMS VAX systems, and one argument-list position on OpenVMS Alpha systems.
This function is specific to DEC C for OpenVMS Systems and is not portable.
Finishes the <varargs.h> or <stdarg.h> session.
#include <stdarg.h>(ANSI C) #include <varargs.h>
(DEC C EXTENSION) void va_end (va_list ap);
ap
The object used to traverse the argument list length. You must declare and use the argument ap as shown in this format section.
You can execute multiple traversals of the argument list, each delimited by va_start ... va_end . The va_end function sets ap equal to NULL.When using this function to write portable applications, include the <stdarg.h> header file (defined by the ANSI C standard), not the <varargs.h> header file, and use va_end only in conjunction with other routines defined in <stdarg.h> .
For an example of argument-list processing using the <stdarg.h> functions and definitions, see Chapter 3, Example 3-6.
Used for initializing a variable to the beginning of the argument list.
#include <varargs.h>(DEC C EXTENSION) void va_start (va_list ap);
void va_start_1 (va_list ap, int offset);
ap
An object pointer. You must declare and use the argument ap as shown in the format section.offset
The number of bytes by which ap is to be incremented so that it points to a subsequent argument within the list (that is, not to the start of the argument list). Using a nonzero offset can initialize ap to the address of the first of the optional arguments that follow a number of fixed arguments.
The va_start macro initializes the variable ap to the beginning of the argument list.The va_start_1 macro initializes ap to the address of an argument that is preceded by a known number of defined arguments. The printf function is an example of a DEC C RTL function that contains a variable-length argument list offset from the beginning of the entire argument list. The variable-length argument list is offset by the address of the formatting string.
When determining value of the offset argument used in va_start_1 the implications of the OpenVMS calling standard must be considered.
On OpenVMS VAX, most argument items are a longword. For example, OpenVMS VAX arguments of types char and short use a full longword of memory when they are present in argument lists. However, OpenVMS VAX arguments of type float use two longwords because they are converted to type double .
On OpenVMS Alpha, each argument item is a quadword.
Note
When accessing argument lists, especially those passed to a subroutine (written in C) by a program written in another programming language, consider the implications of the OpenVMS calling standard. For more information about the OpenVMS calling standard, see the DEC C User's Guide for OpenVMS Systems or the OpenVMS Calling Standard.The preceding version of va_start and va_start_1 is specific to the DEC C RTL, and is not portable.
The following syntax describes the va_start macro in the <stdarg.h> header file, as defined in the ANSI C standard:
#include <stdarg.h>(ANSI C) void va_start (va_list ap, parmN);
ap
An object pointer. You must declare and use the argument ap as shown in the format section.parmN
The name of the last of the known fixed arguments.
The pointer ap is initialized to point to the first of the optional arguments that follow parmN in the argument list.Always use this version of va_start in conjunction with functions that are declared and defined with function prototypes. Also use this version of va_start to write portable programs.
For an example of argument-list processing using the <stdarg.h> functions and definitions, see Chapter 3, Example 3-6.
Creates an independent child process. This function is nonreentrant.
#include <unistd.h>int vfork (void);
This function provided by DEC C for OpenVMS Systems differs from the fork function provided by other C implementations. Table REF-12 shows the two major differences.
Table REF-12 The vfork and fork Functions The vfork Function The fork Function Used with the exec functions. Can be used without an exec function for asynchronous processing. Creates an independent child
process that shares some of
the parent's characteristics.Creates an exact duplicate of the parent process that branches at the point where vfork is called, as if the parent and the child are the same process at different stages of execution.
Previous Next Contents Index