OSDN Git Service

Fix "make dvi"
[pf3gnuchains/gcc-fork.git] / gcc / fortran / intrinsic.texi
1 @ignore
2 Copyright (C) 2005
3 Free Software Foundation, Inc.
4 This is part of the GFORTRAN manual.   
5 For copying conditions, see the file gfortran.texi.
6
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``GNU General Public License'' and ``Funding
11 Free Software'', the Front-Cover texts being (a) (see below), and with
12 the Back-Cover Texts being (b) (see below).  A copy of the license is
13 included in the gfdl(7) man page.
14
15
16 Some basic guidelines for editing this document:
17
18   (1) The intrinsic procedures are to be listed in alphabetical order.
19   (2) The generic name is to be use.
20   (3) The specific names are included in the function index and in a
21       table at the end of the node (See ABS entry).
22   (4) Try to maintain the same style for each entry.
23
24
25 @end ignore
26
27 @node Intrinsic Procedures
28 @chapter Intrinsic Procedures
29 @cindex Intrinsic Procedures
30
31 This portion of the document is incomplete and undergoing massive expansion 
32 and editing.  All contributions and corrections are strongly encouraged. 
33
34 @menu
35 * Introduction:   Introduction
36 * @code{ABORT}:   ABORT,    Abort the program     
37 * @code{ABS}:     ABS,      Absolute value     
38 * @code{ACHAR}:   ACHAR,    Character in @acronym{ASCII} collating sequence
39 * @code{ACOS}:    ACOS,     Arccosine function
40 * @code{ADJUSTL}: ADJUSTL,  Left adjust a string
41 * @code{ADJUSTR}: ADJUSTR,  Right adjust a string
42 @end menu
43
44 @node Introduction
45 @section Introduction to intrinsic procedures
46
47 Gfortran provides a rich set of intrinsic procedures that includes all
48 the intrinsic procedures required by the Fortran 95 standard, a set of
49 intrinsic procedures for backwards compatibility with Gnu Fortran 77
50 (i.e., @command{g77}), and a small selection of intrinsic procedures
51 from the Fortran 2003 standard.  Any description here, which conflicts with a 
52 description in either the Fortran 95 standard or the Fortran 2003 standard,
53 is unintentional and the standard(s) should be considered authoritative.
54
55 The enumeration of the @code{KIND} type parameter is processor defined in
56 the Fortran 95 standard.  Gfortran defines the default integer type and
57 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
58 respectively.  The standard mandates that both data types shall have
59 another kind, which have more precision.  On typical target architectures
60 supports by @command{gfortran}, this kind type parameter is @code{KIND=8}.
61 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
62 In the description of generic intrinsic procedures, the kind type parameter
63 will be specified by @code{KIND=*}, and in the description of specific
64 names for an intrinsic procedure the kind type parameter will be explicitly
65 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
66 brevity the optional @code{KIND=} syntax will be omitted.
67
68 Many of the intrinsics procedures take one or more optional arguments.
69 This document follows the convention used in the Fortran 95 standard,
70 and denotes such arguments by square brackets.
71
72 @command{Gfortran} offers the @option{-std=f95} and @option{-std=gnu} options,
73 which can be used to restrict the set of intrinsic procedures to a 
74 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
75 option, and so all intrinsic procedures describe here are accepted.  There
76 is one caveat.  For a select group of intrinsic procedures, @command{g77}
77 implemented both a function and a subroutine.  Both classes 
78 have been implemented in @command{gfortran} for backwards compatibility
79 with @command{g77}.  It is noted here that these functions and subroutines
80 cannot be intermixed in a given subprogram.  In the descriptions that follow,
81 the applicable option(s) is noted.
82
83
84
85 @node ABORT
86 @section @code{ABORT} --- Abort the program  
87 @findex @code{ABORT}
88 @cindex abort
89
90 @table @asis
91 @item @emph{Description}:
92 @code{ABORT} causes immediate termination of the program.  On operating
93 systems that support a core dump, @code{ABORT} will produce a core dump,
94 which is suitable for debugging purposes.
95
96 @item @emph{Option}:
97 gnu
98
99 @item @emph{Type}:
100 non-elemental subroutine
101
102 @item @emph{Syntax}:
103 @code{CALL ABORT}
104
105 @item @emph{Return value}:
106 Does not return.
107
108 @item @emph{Example}:
109 @smallexample
110 program test_abort
111   integer :: i = 1, j = 2
112   if (i /= j) call abort
113 end program test_abort
114 @end smallexample
115 @end table
116
117
118
119 @node ABS
120 @section @code{ABS} --- Absolute value  
121 @findex @code{ABS} intrinsic
122 @findex @code{CABS} intrinsic
123 @findex @code{DABS} intrinsic
124 @findex @code{IABS} intrinsic
125 @findex @code{ZABS} intrinsic
126 @findex @code{CDABS} intrinsic
127 @cindex absolute value
128
129 @table @asis
130 @item @emph{Description}:
131 @code{ABS(X)} computes the absolute value of @code{X}.
132
133 @item @emph{Option}:
134 f95, gnu
135
136 @item @emph{Type}:
137 elemental function
138
139 @item @emph{Syntax}:
140 @code{X = ABS(X)}
141
142 @item @emph{Arguments}:
143 @multitable @columnfractions .15 .80
144 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
145 @code{REAL(*)}, or @code{COMPLEX(*)}.
146 @end multitable
147
148 @item @emph{Return value}:
149 The return value is of the same type and
150 kind as the argument except the return value is @code{REAL(*)} for a
151 @code{COMPLEX(*)} argument.
152
153 @item @emph{Example}:
154 @smallexample
155 program test_abort
156   integer :: i = -1
157   real :: x = -1.e0
158   complex :: z = (-1.e0,0.e0)
159   i = abs(i)
160   x = abs(x)
161   x = abs(z)
162 end program test_abort
163 @end smallexample
164
165 @item @emph{Specific names}:
166 @multitable @columnfractions .24 .24 .24 .24
167 @item Name            @tab Argument            @tab Return type       @tab Option
168 @item @code{CABS(Z)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab f95, gnu
169 @item @code{DABS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab f95, gnu
170 @item @code{IABS(I)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab f95, gnu
171 @item @code{ZABS(Z)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab gnu
172 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab gnu
173 @end multitable
174 @end table
175
176
177
178 @node ACHAR
179 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 
180 @findex @code{ACHAR} intrinsic
181 @cindex @acronym{ASCII} collating sequence
182
183 @table @asis
184 @item @emph{Description}:
185 @code{ACHAR(I)} returns the character located at position @code{I}
186 in the @acronym{ASCII} collating sequence.
187
188 @item @emph{Option}:
189 f95, gnu
190
191 @item @emph{Type}:
192 elemental function
193
194 @item @emph{Syntax}:
195 @code{C = ACHAR(I)}
196
197 @item @emph{Arguments}:
198 @multitable @columnfractions .15 .80
199 @item @var{I} @tab The type shall be an @code{INTEGER(*)}.
200 @end multitable
201
202 @item @emph{Return value}:
203 The return value is of type @code{CHARACTER} with a length of one.  The
204 kind type parameter is the same as  @code{KIND('A')}.
205
206 @item @emph{Example}:
207 @smallexample
208 program test_achar
209   character c
210   c = achar(32)
211 end program test_abort
212 @end smallexample
213 @end table
214
215
216
217 @node ACOS
218 @section @code{ACOS} --- Arccosine function 
219 @findex @code{ACOS} intrinsic
220 @findex @code{DACOS} intrinsic
221 @cindex arccosine
222
223 @table @asis
224 @item @emph{Description}:
225 @code{ACOS(X)} computes the arccosine of its @var{X}.
226
227 @item @emph{Option}:
228 f95, gnu
229
230 @item @emph{Type}:
231 elemental function
232
233 @item @emph{Syntax}:
234 @code{X = ACOS(X)}
235
236 @item @emph{Arguments}:
237 @multitable @columnfractions .15 .80
238 @item @var{X} @tab The type shall be an @code{REAL(*)}.
239 @end multitable
240
241 @item @emph{Return value}:
242 The return value is of type @code{REAL(*)} and it lies in the
243 range @math{ 0 \leq \arccos (x) \leq \pi}.
244
245 @item @emph{Example}:
246 @smallexample
247 program test_acos
248   real(8) :: x = 0.866_8
249   x = achar(x)
250 end program test_acos
251 @end smallexample
252
253 @item @emph{Specific names}:
254 @multitable @columnfractions .24 .24 .24 .24
255 @item Name            @tab Argument          @tab Return type       @tab Option
256 @item @code{DACOS(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
257 @end multitable
258 @end table
259
260
261
262 @node ADJUSTL
263 @section @code{ADJUSTL} --- Left adjust a string 
264 @findex @code{ADJUSTL} intrinsic
265 @cindex adjust string
266
267 @table @asis
268 @item @emph{Description}:
269 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
270 Spaces are inserted at the end of the string as needed.
271
272 @item @emph{Option}:
273 f95, gnu
274
275 @item @emph{Type}:
276 elemental function
277
278 @item @emph{Syntax}:
279 @code{STR = ADJUSTL(STR)}
280
281 @item @emph{Arguments}:
282 @multitable @columnfractions .15 .80
283 @item @var{STR} @tab The type shall be @code{CHARACTER}.
284 @end multitable
285
286 @item @emph{Return value}:
287 The return value is of type @code{CHARACTER} where leading spaces 
288 are removed and the same number of spaces are inserted on the end
289 of @var{STR}.
290
291 @item @emph{Example}:
292 @smallexample
293 program test_adjustl
294   character(len=20) :: str = '   gfortran'
295   str = adjustl(str)
296   print *, str
297 end program test_adjustl
298 @end smallexample
299 @end table
300
301
302 @node ADJUSTR
303 @section @code{ADJUSTR} --- Right adjust a string 
304 @findex @code{ADJUSTR} intrinsic
305 @cindex adjust string
306
307 @table @asis
308 @item @emph{Description}:
309 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
310 Spaces are inserted at the start of the string as needed.
311
312 @item @emph{Option}:
313 f95, gnu
314
315 @item @emph{Type}:
316 elemental function
317
318 @item @emph{Syntax}:
319 @code{STR = ADJUSTR(STR)}
320
321 @item @emph{Arguments}:
322 @multitable @columnfractions .15 .80
323 @item @var{STR} @tab The type shall be @code{CHARACTER}.
324 @end multitable
325
326 @item @emph{Return value}:
327 The return value is of type @code{CHARACTER} where trailing spaces 
328 are removed and the same number of spaces are inserted at the start
329 of @var{STR}.
330
331 @item @emph{Example}:
332 @smallexample
333 program test_adjustr
334   character(len=20) :: str = 'gfortran'
335   str = adjustr(str)
336   print *, str
337 end program test_adjustr
338 @end smallexample
339 @end table
340
341
342
343 @comment gen   aimag
344 @comment       dimag 
345 @comment 
346 @comment gen   aint
347 @comment       dint
348 @comment 
349 @comment gen   all
350 @comment 
351 @comment gen   allocated 
352 @comment 
353 @comment gen   anint
354 @comment       dnint
355 @comment 
356 @comment gen   any
357 @comment 
358 @comment gen   asin
359 @comment       dasin
360 @comment 
361 @comment gen   associated
362 @comment 
363 @comment gen   atan
364 @comment       datan
365 @comment 
366 @comment gen   atan2
367 @comment       datan2
368 @comment 
369 @comment gen   besj0
370 @comment       dbesj0 
371 @comment 
372 @comment gen   besj1
373 @comment       dbesj1
374 @comment 
375 @comment gen   besjn
376 @comment       dbesjn
377 @comment 
378 @comment gen   besy0
379 @comment       dbesy0
380 @comment 
381 @comment gen   besy1
382 @comment       dbesy1
383 @comment 
384 @comment gen   besyn
385 @comment       dbesyn
386 @comment 
387 @comment gen   bit_size 
388 @comment 
389 @comment gen   btest
390 @comment 
391 @comment gen   ceiling
392 @comment 
393 @comment gen   char
394 @comment 
395 @comment gen   cmplx 
396 @comment 
397 @comment gen   command_argument_count
398 @comment 
399 @comment gen   conjg
400 @comment       dconjg
401 @comment 
402 @comment gen   cos
403 @comment       dcos
404 @comment       ccos
405 @comment       zcos,cdcos
406 @comment 
407 @comment gen   cosh
408 @comment       dcosh
409 @comment 
410 @comment gen   count
411 @comment 
412 @comment sub   cpu_time
413 @comment 
414 @comment gen   cshift
415 @comment 
416 @comment sub   date_and_time
417 @comment 
418 @comment gen   dble 
419 @comment       dfloat
420 @comment 
421 @comment gen   dcmplx
422 @comment 
423 @comment gen   digits
424 @comment 
425 @comment gen   dim
426 @comment       idim
427 @comment       ddim
428 @comment 
429 @comment gen   dot_product
430 @comment 
431 @comment gen   dprod
432 @comment 
433 @comment gen   dreal 
434 @comment 
435 @comment sub   dtime
436 @comment 
437 @comment gen   eoshift
438 @comment 
439 @comment gen   epsilon
440 @comment 
441 @comment gen   erf
442 @comment       derf
443 @comment 
444 @comment gen   erfc
445 @comment       derfc
446 @comment 
447 @comment gen   etime
448 @comment sub   etime
449 @comment 
450 @comment sub   exit
451 @comment 
452 @comment gen   exp
453 @comment       dexp
454 @comment       cexp
455 @comment       zexp,cdexp
456 @comment 
457 @comment gen   exponent
458 @comment 
459 @comment gen   floor
460 @comment 
461 @comment sub   flush
462 @comment 
463 @comment gen   fnum
464 @comment 
465 @comment gen   fraction
466 @comment 
467 @comment gen   fstat
468 @comment sub   fstat
469 @comment 
470 @comment sub   getarg
471 @comment 
472 @comment gen   getcwd
473 @comment sub   getcwd
474 @comment 
475 @comment sub   getenv
476 @comment 
477 @comment gen   getgid
478 @comment 
479 @comment gen   getpid
480 @comment 
481 @comment gen   getuid
482 @comment 
483 @comment sub   get_command
484 @comment 
485 @comment sub   get_command_argument
486 @comment 
487 @comment sub   get_environment_variable
488 @comment 
489 @comment gen   huge
490 @comment 
491 @comment gen   iachar
492 @comment 
493 @comment gen   iand
494 @comment 
495 @comment gen   iargc
496 @comment 
497 @comment gen   ibclr
498 @comment 
499 @comment gen   ibits
500 @comment 
501 @comment gen   ibset
502 @comment 
503 @comment gen   ichar
504 @comment 
505 @comment gen   ieor
506 @comment 
507 @comment gen   index
508 @comment 
509 @comment gen   int
510 @comment       ifix
511 @comment       idint
512 @comment 
513 @comment gen   ior
514 @comment 
515 @comment gen   irand
516 @comment 
517 @comment gen   ishft
518 @comment 
519 @comment gen   ishftc
520 @comment 
521 @comment gen   kind
522 @comment 
523 @comment gen   lbound
524 @comment 
525 @comment gen   len
526 @comment 
527 @comment gen   len_trim
528 @comment 
529 @comment gen   lge
530 @comment 
531 @comment gen   lgt
532 @comment 
533 @comment gen   lle
534 @comment 
535 @comment gen   llt
536 @comment 
537 @comment gen   log
538 @comment       alog
539 @comment       dlog
540 @comment       clog
541 @comment       zlog, cdlog
542 @comment 
543 @comment gen   log10
544 @comment       alog10
545 @comment       dlog10
546 @comment 
547 @comment gen   logical
548 @comment 
549 @comment gen   matmul
550 @comment 
551 @comment gen   max
552 @comment       max0
553 @comment       amax0
554 @comment       amax1
555 @comment       max1
556 @comment       dmax1
557 @comment 
558 @comment gen   maxexponent
559 @comment 
560 @comment gen   maxloc
561 @comment
562 @comment gen   maxval
563 @comment 
564 @comment gen   merge
565 @comment 
566 @comment gen   min
567 @comment       min0
568 @comment       amin0
569 @comment       amin1
570 @comment       min1
571 @comment       dmin1
572 @comment 
573 @comment gen   minexponent
574 @comment 
575 @comment gen   minloc
576 @comment 
577 @comment gen   minval
578 @comment 
579 @comment gen   mod
580 @comment       amod
581 @comment       dmod
582 @comment 
583 @comment gen   modulo
584 @comment 
585 @comment sub   mvbits
586 @comment 
587 @comment gen   nearest
588 @comment 
589 @comment gen   nint
590 @comment       idnint
591 @comment 
592 @comment gen   not
593 @comment 
594 @comment gen   null
595 @comment 
596 @comment gen   pack
597 @comment 
598 @comment gen   precision
599 @comment 
600 @comment gen   present
601 @comment 
602 @comment gen   product
603 @comment 
604 @comment gen   radix
605 @comment 
606 @comment gen   rand
607 @comment       ran 
608 @comment 
609 @comment sub   random_number
610 @comment 
611 @comment sub   random_seed
612 @comment 
613 @comment gen   range
614 @comment 
615 @comment gen   real
616 @comment       float
617 @comment       sngl
618 @comment 
619 @comment gen   repeat
620 @comment 
621 @comment gen   reshape
622 @comment 
623 @comment gen   rrspacing
624 @comment 
625 @comment gen   scale
626 @comment 
627 @comment gen   scan
628 @comment 
629 @comment gen   second
630 @comment sub   second
631 @comment 
632 @comment gen   selected_int_kind
633 @comment 
634 @comment gen   selected_real_kind
635 @comment 
636 @comment gen   set_exponent
637 @comment 
638 @comment gen   shape
639 @comment 
640 @comment gen   sign
641 @comment       isign
642 @comment       dsign
643 @comment 
644 @comment gen   sin
645 @comment       dsin
646 @comment       csin
647 @comment       zsin,cdsin
648 @comment 
649 @comment gen   sinh
650 @comment       dsinh
651 @comment 
652 @comment gen   size
653 @comment 
654 @comment gen   spacing
655 @comment 
656 @comment gen   spread
657 @comment 
658 @comment gen   sqrt
659 @comment       dsqrt
660 @comment       csqrt
661 @comment       zsqrt,cdsqrt
662 @comment 
663 @comment sub   srand
664 @comment 
665 @comment gen   stat
666 @comment sub   stat
667 @comment 
668 @comment gen   sum
669 @comment 
670 @comment gen   system
671 @comment sub   system
672 @comment 
673 @comment sub system_clock
674 @comment 
675 @comment gen   tan
676 @comment       dtan
677 @comment 
678 @comment gen   tanh
679 @comment       dtanh
680 @comment 
681 @comment gen   tiny
682 @comment 
683 @comment gen   transfer
684 @comment 
685 @comment gen   transpose
686 @comment 
687 @comment gen   trim
688 @comment 
689 @comment gen   ubound
690 @comment 
691 @comment gen   umask
692 @comment sub   umask
693 @comment 
694 @comment gen   unlink
695 @comment sub   unlink
696 @comment 
697 @comment gen   unpack
698 @comment 
699 @comment gen   verify
700
701  
702