1UnixLabels(3)                    OCaml library                   UnixLabels(3)
2
3
4

NAME

6       UnixLabels - Interface to the Unix system.
7

Module

9       Module   UnixLabels
10

Documentation

12       Module UnixLabels
13        : sig end
14
15
16       Interface to the Unix system.
17
18       To use the labeled version of this module, add module Unix = UnixLabels
19       in your implementation.
20
21       Note: all the functions of this module (except UnixLabels.error_message
22       and  UnixLabels.handle_unix_error  )  are  liable  to raise the UnixLa‐
23       bels.Unix_error exception whenever the underlying system  call  signals
24       an error.
25
26
27
28
29
30
31
32   Error report
33       type error = Unix.error =
34        | E2BIG  (* Argument list too long
35        *)
36        | EACCES  (* Permission denied
37        *)
38        | EAGAIN  (* Resource temporarily unavailable; try again
39        *)
40        | EBADF  (* Bad file descriptor
41        *)
42        | EBUSY  (* Resource unavailable
43        *)
44        | ECHILD  (* No child process
45        *)
46        | EDEADLK  (* Resource deadlock would occur
47        *)
48        | EDOM  (* Domain error for math functions, etc.
49        *)
50        | EEXIST  (* File exists
51        *)
52        | EFAULT  (* Bad address
53        *)
54        | EFBIG  (* File too large
55        *)
56        | EINTR  (* Function interrupted by signal
57        *)
58        | EINVAL  (* Invalid argument
59        *)
60        | EIO  (* Hardware I/O error
61        *)
62        | EISDIR  (* Is a directory
63        *)
64        | EMFILE  (* Too many open files by the process
65        *)
66        | EMLINK  (* Too many links
67        *)
68        | ENAMETOOLONG  (* Filename too long
69        *)
70        | ENFILE  (* Too many open files in the system
71        *)
72        | ENODEV  (* No such device
73        *)
74        | ENOENT  (* No such file or directory
75        *)
76        | ENOEXEC  (* Not an executable file
77        *)
78        | ENOLCK  (* No locks available
79        *)
80        | ENOMEM  (* Not enough memory
81        *)
82        | ENOSPC  (* No space left on device
83        *)
84        | ENOSYS  (* Function not supported
85        *)
86        | ENOTDIR  (* Not a directory
87        *)
88        | ENOTEMPTY  (* Directory not empty
89        *)
90        | ENOTTY  (* Inappropriate I/O control operation
91        *)
92        | ENXIO  (* No such device or address
93        *)
94        | EPERM  (* Operation not permitted
95        *)
96        | EPIPE  (* Broken pipe
97        *)
98        | ERANGE  (* Result too large
99        *)
100        | EROFS  (* Read-only file system
101        *)
102        | ESPIPE  (* Invalid seek e.g. on a pipe
103        *)
104        | ESRCH  (* No such process
105        *)
106        | EXDEV  (* Invalid link
107        *)
108        | EWOULDBLOCK  (* Operation would block
109        *)
110        | EINPROGRESS  (* Operation now in progress
111        *)
112        | EALREADY  (* Operation already in progress
113        *)
114        | ENOTSOCK  (* Socket operation on non-socket
115        *)
116        | EDESTADDRREQ  (* Destination address required
117        *)
118        | EMSGSIZE  (* Message too long
119        *)
120        | EPROTOTYPE  (* Protocol wrong type for socket
121        *)
122        | ENOPROTOOPT  (* Protocol not available
123        *)
124        | EPROTONOSUPPORT  (* Protocol not supported
125        *)
126        | ESOCKTNOSUPPORT  (* Socket type not supported
127        *)
128        | EOPNOTSUPP  (* Operation not supported on socket
129        *)
130        | EPFNOSUPPORT  (* Protocol family not supported
131        *)
132        | EAFNOSUPPORT  (* Address family not supported by protocol family
133        *)
134        | EADDRINUSE  (* Address already in use
135        *)
136        | EADDRNOTAVAIL  (* Can't assign requested address
137        *)
138        | ENETDOWN  (* Network is down
139        *)
140        | ENETUNREACH  (* Network is unreachable
141        *)
142        | ENETRESET  (* Network dropped connection on reset
143        *)
144        | ECONNABORTED  (* Software caused connection abort
145        *)
146        | ECONNRESET  (* Connection reset by peer
147        *)
148        | ENOBUFS  (* No buffer space available
149        *)
150        | EISCONN  (* Socket is already connected
151        *)
152        | ENOTCONN  (* Socket is not connected
153        *)
154        | ESHUTDOWN  (* Can't send after socket shutdown
155        *)
156        | ETOOMANYREFS  (* Too many references: can't splice
157        *)
158        | ETIMEDOUT  (* Connection timed out
159        *)
160        | ECONNREFUSED  (* Connection refused
161        *)
162        | EHOSTDOWN  (* Host is down
163        *)
164        | EHOSTUNREACH  (* No route to host
165        *)
166        | ELOOP  (* Too many levels of symbolic links
167        *)
168        | EOVERFLOW  (* File size or position not representable
169        *)
170        | EUNKNOWNERR of int
171         (* Unknown error
172        *)
173
174
175       The  type of error codes.  Errors defined in the POSIX standard and ad‐
176       ditional errors from UNIX98 and BSD.  All other errors  are  mapped  to
177       EUNKNOWNERR.
178
179
180
181       exception Unix_error of error * string * string
182
183
184       Raised  by  the  system  calls below when an error is encountered.  The
185       first component is the error code; the second component is the function
186       name;  the  third component is the string parameter to the function, if
187       it has one, or the empty string otherwise.
188
189
190       UnixLabels.Unix_error and Unix.Unix_error are the  same,  and  catching
191       one will catch the other.
192
193
194
195       val error_message : error -> string
196
197       Return a string describing the given error code.
198
199
200
201       val handle_unix_error : ('a -> 'b) -> 'a -> 'b
202
203
204       handle_unix_error  f  x  applies f to x and returns the result.  If the
205       exception UnixLabels.Unix_error is raised, it prints a message describ‐
206       ing the error and exits with code 2.
207
208
209
210
211   Access to the process environment
212       val environment : unit -> string array
213
214       Return  the process environment, as an array of strings with the format
215       ``variable=value''.  The returned array is empty  if  the  process  has
216       special privileges.
217
218
219
220       val unsafe_environment : unit -> string array
221
222       Return  the process environment, as an array of strings with the format
223       ``variable=value''.  Unlike UnixLabels.environment , this function  re‐
224       turns  a  populated  array  even if the process has special privileges.
225       See the documentation for UnixLabels.unsafe_getenv for more details.
226
227
228       Since 4.12.0
229
230
231
232       val getenv : string -> string
233
234       Return the value associated to a variable in the  process  environment,
235       unless the process has special privileges.
236
237
238       Raises  Not_found if the variable is unbound or the process has special
239       privileges.
240
241       This function is identical to Sys.getenv .
242
243
244
245       val unsafe_getenv : string -> string
246
247       Return the value associated to a variable in the process environment.
248
249       Unlike UnixLabels.getenv , this function returns the value even if  the
250       process  has  special  privileges.  It is considered unsafe because the
251       programmer of a setuid or setgid program must be careful to avoid using
252       maliciously  crafted  environment variables in the search path for exe‐
253       cutables, the locations for temporary files or logs, and the like.
254
255
256       Since 4.06.0
257
258
259       Raises Not_found if the variable is unbound.
260
261
262
263       val putenv : string -> string -> unit
264
265
266       putenv name value sets the  value  associated  to  a  variable  in  the
267       process environment.  name is the name of the environment variable, and
268       value its new associated value.
269
270
271
272
273   Process handling
274       type process_status = Unix.process_status =
275        | WEXITED of int
276         (* The process terminated normally by exit ; the argument is the  re‐
277       turn code.
278        *)
279        | WSIGNALED of int
280         (*  The  process  was  killed by a signal; the argument is the signal
281       number.
282        *)
283        | WSTOPPED of int
284         (* The process was stopped by a signal; the argument  is  the  signal
285       number.
286        *)
287
288
289       The  termination  status  of a process.  See module Sys for the defini‐
290       tions of the standard signal numbers.  Note that they are not the  num‐
291       bers used by the OS.
292
293
294       type wait_flag = Unix.wait_flag =
295        |  WNOHANG   (* Do not block if no child has died yet, but immediately
296       return with a pid equal to 0.
297        *)
298        | WUNTRACED  (* Report also the children that receive stop signals.
299        *)
300
301
302       Flags for UnixLabels.waitpid .
303
304
305
306       val execv : prog:string -> args:string array -> 'a
307
308
309       execv ~prog ~args execute the program in file prog , with the arguments
310       args  ,  and  the  current process environment.  These execv* functions
311       never return: on success, the current program is replaced  by  the  new
312       one.
313
314
315       Raises Unix_error on failure
316
317
318
319       val execve : prog:string -> args:string array -> env:string array -> 'a
320
321       Same  as UnixLabels.execv , except that the third argument provides the
322       environment to the program executed.
323
324
325
326       val execvp : prog:string -> args:string array -> 'a
327
328       Same as UnixLabels.execv , except that the program is searched  in  the
329       path.
330
331
332
333       val  execvpe  : prog:string -> args:string array -> env:string array ->
334       'a
335
336       Same as UnixLabels.execve , except that the program is searched in  the
337       path.
338
339
340
341       val fork : unit -> int
342
343       Fork  a  new  process. The returned integer is 0 for the child process,
344       the pid of the child process for the parent process.
345
346
347       Raises Invalid_argument on Windows.  Use  UnixLabels.create_process  or
348       threads instead.
349
350
351
352       val wait : unit -> int * process_status
353
354       Wait  until  one  of the children processes die, and return its pid and
355       termination status.
356
357
358       Raises Invalid_argument on Windows. Use UnixLabels.waitpid instead.
359
360
361
362       val waitpid : mode:wait_flag list -> int -> int * process_status
363
364       Same as UnixLabels.wait , but waits for the child process whose pid  is
365       given.   A  pid  of -1 means wait for any child.  A pid of 0 means wait
366       for any child in the same process group as the current process.   Nega‐
367       tive pid arguments represent process groups.  The list of options indi‐
368       cates whether waitpid should return immediately  without  waiting,  and
369       whether it should report stopped children.
370
371       On Windows: can only wait for a given PID, not any child process.
372
373
374
375       val system : string -> process_status
376
377       Execute  the  given  command,  wait until it terminates, and return its
378       termination status. The string is interpreted by the shell /bin/sh  (or
379       the  command  interpreter cmd.exe on Windows) and therefore can contain
380       redirections, quotes, variables, etc.  To properly quote whitespace and
381       shell  special characters occurring in file names or command arguments,
382       the use of Filename.quote_command is recommended.  The  result  WEXITED
383       127 indicates that the shell couldn't be executed.
384
385
386
387       val _exit : int -> 'a
388
389       Terminate  the  calling process immediately, returning the given status
390       code to the operating system: usually 0 to indicate no  errors,  and  a
391       small  positive  integer to indicate failure.  Unlike exit , Unix._exit
392       performs no finalization whatsoever: functions registered with  at_exit
393       are  not  called,  input/output  channels  are  not  flushed, and the C
394       run-time system is not finalized either.
395
396       The typical use of Unix._exit is after a Unix.fork operation, when  the
397       child  process runs into a fatal error and must exit.  In this case, it
398       is preferable to not perform  any  finalization  action  in  the  child
399       process,  as  these  actions  could interfere with similar actions per‐
400       formed by the parent process.  For example, output channels should  not
401       be  flushed  by the child process, as the parent process may flush them
402       again later, resulting in duplicate output.
403
404
405       Since 4.12.0
406
407
408
409       val getpid : unit -> int
410
411       Return the pid of the process.
412
413
414
415       val getppid : unit -> int
416
417       Return the pid of the parent process.
418
419
420       Raises Invalid_argument on Windows (because it is meaningless)
421
422
423
424       val nice : int -> int
425
426       Change the process priority. The  integer  argument  is  added  to  the
427       ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
428       ties.) Return the new nice value.
429
430
431       Raises Invalid_argument on Windows
432
433
434
435
436   Basic file input/output
437       type file_descr = Unix.file_descr
438
439
440       The abstract type of file descriptors.
441
442
443
444       val stdin : file_descr
445
446       File descriptor for standard input.
447
448
449
450       val stdout : file_descr
451
452       File descriptor for standard output.
453
454
455
456       val stderr : file_descr
457
458       File descriptor for standard error.
459
460
461       type open_flag = Unix.open_flag =
462        | O_RDONLY  (* Open for reading
463        *)
464        | O_WRONLY  (* Open for writing
465        *)
466        | O_RDWR  (* Open for reading and writing
467        *)
468        | O_NONBLOCK  (* Open in non-blocking mode
469        *)
470        | O_APPEND  (* Open for append
471        *)
472        | O_CREAT  (* Create if nonexistent
473        *)
474        | O_TRUNC  (* Truncate to 0 length if existing
475        *)
476        | O_EXCL  (* Fail if existing
477        *)
478        | O_NOCTTY  (* Don't make this dev a controlling tty
479        *)
480        | O_DSYNC  (* Writes complete as `Synchronised I/O data integrity com‐
481       pletion'
482        *)
483        |  O_SYNC  (* Writes complete as `Synchronised I/O file integrity com‐
484       pletion'
485        *)
486        | O_RSYNC  (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
487        *)
488        | O_SHARE_DELETE  (* Windows only: allow the file to be deleted  while
489       still open
490        *)
491        |  O_CLOEXEC  (* Set the close-on-exec flag on the descriptor returned
492       by UnixLabels.openfile .  See UnixLabels.set_close_on_exec for more in‐
493       formation.
494        *)
495        |  O_KEEPEXEC  (* Clear the close-on-exec flag.  This is currently the
496       default.
497        *)
498
499
500       The flags to UnixLabels.openfile .
501
502
503       type file_perm = int
504
505
506       The type of file access rights, e.g.  0o640 is read and write for user,
507       read for group, none for others
508
509
510
511       val  openfile  :  string  ->  mode:open_flag  list -> perm:file_perm ->
512       file_descr
513
514       Open the named file with the given flags. Third argument is the permis‐
515       sions to give to the file if it is created (see UnixLabels.umask ). Re‐
516       turn a file descriptor on the named file.
517
518
519
520       val close : file_descr -> unit
521
522       Close a file descriptor.
523
524
525
526       val fsync : file_descr -> unit
527
528       Flush file buffers to disk.
529
530
531       Since 4.12.0
532
533
534
535       val read : file_descr -> buf:bytes -> pos:int -> len:int -> int
536
537
538       read fd ~buf ~pos ~len reads len bytes from  descriptor  fd  ,  storing
539       them  in  byte  sequence buf , starting at position pos in buf . Return
540       the number of bytes actually read.
541
542
543
544       val write : file_descr -> buf:bytes -> pos:int -> len:int -> int
545
546
547       write fd ~buf ~pos ~len writes len bytes to descriptor fd , taking them
548       from  byte sequence buf , starting at position pos in buff . Return the
549       number of bytes actually written.  write repeats the writing  operation
550       until all bytes have been written or an error occurs.
551
552
553
554       val single_write : file_descr -> buf:bytes -> pos:int -> len:int -> int
555
556       Same  as  UnixLabels.write , but attempts to write only once.  Thus, if
557       an error occurs, single_write guarantees that no data has been written.
558
559
560
561       val write_substring : file_descr -> buf:string -> pos:int -> len:int ->
562       int
563
564       Same as UnixLabels.write , but take the data from a string instead of a
565       byte sequence.
566
567
568       Since 4.02.0
569
570
571
572       val single_write_substring : file_descr ->  buf:string  ->  pos:int  ->
573       len:int -> int
574
575       Same  as  UnixLabels.single_write , but take the data from a string in‐
576       stead of a byte sequence.
577
578
579       Since 4.02.0
580
581
582
583
584   Interfacing with the standard input/output library
585       val in_channel_of_descr : file_descr -> in_channel
586
587       Create an input channel reading from the given descriptor.  The channel
588       is  initially  in  binary mode; use set_binary_mode_in ic false if text
589       mode is desired.  Text mode is supported only if the descriptor  refers
590       to a file or pipe, but is not supported if it refers to a socket.
591
592       On  Windows:  set_binary_mode_in  always fails on channels created with
593       this function.
594
595       Beware that input channels are buffered, so more  characters  may  have
596       been  read  from the descriptor than those accessed using channel func‐
597       tions.  Channels also keep a copy of the current position in the file.
598
599       Closing  the  channel  ic  returned  by  in_channel_of_descr  fd  using
600       close_in ic also closes the underlying descriptor fd .  It is incorrect
601       to close both the channel ic and the descriptor fd .
602
603       If several channels are created on the  same  descriptor,  one  of  the
604       channels  must  be  closed, but not the others.  Consider for example a
605       descriptor s connected to a socket  and  two  channels  ic  =  in_chan‐
606       nel_of_descr s and oc = out_channel_of_descr s .  The recommended clos‐
607       ing protocol is to perform close_out oc , which flushes buffered output
608       to  the  socket  then  closes  the  socket.  The ic channel must not be
609       closed and will be collected by the GC eventually.
610
611
612
613       val out_channel_of_descr : file_descr -> out_channel
614
615       Create an output channel writing on the given descriptor.  The  channel
616       is  initially  in binary mode; use set_binary_mode_out oc false if text
617       mode is desired.  Text mode is supported only if the descriptor  refers
618       to a file or pipe, but is not supported if it refers to a socket.
619
620       On  Windows:  set_binary_mode_out always fails on channels created with
621       this function.
622
623       Beware that output channels are buffered, so you may have to call flush
624       to ensure that all data has been sent to the descriptor.  Channels also
625       keep a copy of the current position in the file.
626
627       Closing the  channel  oc  returned  by  out_channel_of_descr  fd  using
628       close_out  oc  also closes the underlying descriptor fd .  It is incor‐
629       rect to close both the channel ic and the descriptor fd .
630
631       See Unix.in_channel_of_descr for a discussion of the  closing  protocol
632       when several channels are created on the same descriptor.
633
634
635
636       val descr_of_in_channel : in_channel -> file_descr
637
638       Return the descriptor corresponding to an input channel.
639
640
641
642       val descr_of_out_channel : out_channel -> file_descr
643
644       Return the descriptor corresponding to an output channel.
645
646
647
648
649   Seeking and truncating
650       type seek_command = Unix.seek_command =
651        |  SEEK_SET   (*  indicates positions relative to the beginning of the
652       file
653        *)
654        | SEEK_CUR  (* indicates positions relative to the current position
655        *)
656        | SEEK_END  (* indicates positions relative to the end of the file
657        *)
658
659
660       Positioning modes for UnixLabels.lseek .
661
662
663
664       val lseek : file_descr -> int -> mode:seek_command -> int
665
666       Set the current position for a file descriptor, and return the  result‐
667       ing offset (from the beginning of the file).
668
669
670
671       val truncate : string -> len:int -> unit
672
673       Truncates the named file to the given size.
674
675
676
677       val ftruncate : file_descr -> len:int -> unit
678
679       Truncates  the  file corresponding to the given descriptor to the given
680       size.
681
682
683
684
685   File status
686       type file_kind = Unix.file_kind =
687        | S_REG  (* Regular file
688        *)
689        | S_DIR  (* Directory
690        *)
691        | S_CHR  (* Character device
692        *)
693        | S_BLK  (* Block device
694        *)
695        | S_LNK  (* Symbolic link
696        *)
697        | S_FIFO  (* Named pipe
698        *)
699        | S_SOCK  (* Socket
700        *)
701
702
703
704
705       type stats = Unix.stats = {
706        st_dev : int ;  (* Device number
707        *)
708        st_ino : int ;  (* Inode number
709        *)
710        st_kind : file_kind ;  (* Kind of the file
711        *)
712        st_perm : file_perm ;  (* Access rights
713        *)
714        st_nlink : int ;  (* Number of links
715        *)
716        st_uid : int ;  (* User id of the owner
717        *)
718        st_gid : int ;  (* Group ID of the file's group
719        *)
720        st_rdev : int ;  (* Device ID (if special file)
721        *)
722        st_size : int ;  (* Size in bytes
723        *)
724        st_atime : float ;  (* Last access time
725        *)
726        st_mtime : float ;  (* Last modification time
727        *)
728        st_ctime : float ;  (* Last status change time
729        *)
730        }
731
732
733       The information returned by the UnixLabels.stat calls.
734
735
736
737       val stat : string -> stats
738
739       Return the information for the named file.
740
741
742
743       val lstat : string -> stats
744
745       Same as UnixLabels.stat , but in case the file is a symbolic link,  re‐
746       turn the information for the link itself.
747
748
749
750       val fstat : file_descr -> stats
751
752       Return  the information for the file associated with the given descrip‐
753       tor.
754
755
756
757       val isatty : file_descr -> bool
758
759       Return true if the given file descriptor refers to a terminal  or  con‐
760       sole window, false otherwise.
761
762
763
764
765   File operations on large files
766       module LargeFile : sig end
767
768
769       File  operations on large files.  This sub-module provides 64-bit vari‐
770       ants of the functions  UnixLabels.LargeFile.lseek  (for  positioning  a
771       file  descriptor),  UnixLabels.LargeFile.truncate and UnixLabels.Large‐
772       File.ftruncate (for changing the size of a file), and UnixLabels.Large‐
773       File.stat  ,  UnixLabels.LargeFile.lstat and UnixLabels.LargeFile.fstat
774       (for obtaining information on files).  These alternate functions repre‐
775       sent  positions  and  sizes by 64-bit integers (type int64 ) instead of
776       regular integers (type int ), thus allowing operating  on  files  whose
777       sizes are greater than max_int .
778
779
780
781
782   Mapping files into memory
783       val  map_file : file_descr -> ?pos:int64 -> kind:('a, 'b) Bigarray.kind
784       -> layout:'c Bigarray.layout -> shared:bool -> dims:int array  ->  ('a,
785       'b, 'c) Bigarray.Genarray.t
786
787       Memory  mapping  of  a  file  as a Bigarray.  map_file fd ~kind ~layout
788       ~shared ~dims returns a Bigarray of kind kind , layout layout , and di‐
789       mensions  as  specified  in dims .  The data contained in this Bigarray
790       are the contents of the file referred to by the file descriptor fd  (as
791       opened  previously  with  UnixLabels.openfile  , for example).  The op‐
792       tional pos parameter is the byte offset in the file of the  data  being
793       mapped; it defaults to 0 (map from the beginning of the file).
794
795       If  shared  is  true , all modifications performed on the array are re‐
796       flected in the file.  This requires that fd be opened with  write  per‐
797       missions.   If  shared  is false , modifications performed on the array
798       are done in memory only, using copy-on-write of the modified pages; the
799       underlying file is not affected.
800
801
802       Genarray.map_file is much more efficient than reading the whole file in
803       a Bigarray, modifying that Bigarray, and writing it afterwards.
804
805       To adjust automatically the dimensions of the Bigarray  to  the  actual
806       size of the file, the major dimension (that is, the first dimension for
807       an array with C layout, and the last dimension for an array  with  For‐
808       tran  layout)  can  be given as -1 .  Genarray.map_file then determines
809       the major dimension from the size of the file.  The file  must  contain
810       an  integral number of sub-arrays as determined by the non-major dimen‐
811       sions, otherwise Failure is raised.
812
813       If all dimensions of the Bigarray are given, the file size  is  matched
814       against  the  size of the Bigarray.  If the file is larger than the Bi‐
815       garray, only the initial portion of the file is mapped to the Bigarray.
816       If  the  file  is smaller than the big array, the file is automatically
817       grown to the size of the Bigarray.  This requires write permissions  on
818       fd .
819
820       Array accesses are bounds-checked, but the bounds are determined by the
821       initial call to map_file . Therefore, you should  make  sure  no  other
822       process modifies the mapped file while you're accessing it, or a SIGBUS
823       signal may be raised. This  happens,  for  instance,  if  the  file  is
824       shrunk.
825
826
827       Invalid_argument or Failure may be raised in cases where argument vali‐
828       dation fails.
829
830
831       Since 4.06.0
832
833
834
835
836   Operations on file names
837       val unlink : string -> unit
838
839       Removes the named file.
840
841       If the named file is a directory, raises:
842
843       - EPERM on POSIX compliant system
844
845       - EISDIR on Linux >= 2.1.132
846
847       - EACCESS on Windows
848
849
850
851
852       val rename : src:string -> dst:string -> unit
853
854
855       rename ~src ~dst changes the name of a file from src to dst , moving it
856       between  directories  if  needed.   If dst already exists, its contents
857       will be replaced with those of src .  Depending on the  operating  sys‐
858       tem,  the  metadata (permissions, owner, etc) of dst can either be pre‐
859       served or be replaced by those of src .
860
861
862
863       val link : ?follow:bool -> src:string -> dst:string -> unit
864
865
866       link ?follow ~src ~dst creates a hard link named dst to the file  named
867       src .
868
869
870       Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
871       able.
872
873
874       Raises ENOSYS On Windows if ~follow:false is requested.
875
876
877
878       val realpath : string -> string
879
880
881       realpath p is an absolute pathname for p obtained by resolving all  ex‐
882       tra / characters, relative path segments and symbolic links.
883
884
885       Since 4.13.0
886
887
888
889
890   File permissions and ownership
891       type access_permission = Unix.access_permission =
892        | R_OK  (* Read permission
893        *)
894        | W_OK  (* Write permission
895        *)
896        | X_OK  (* Execution permission
897        *)
898        | F_OK  (* File exists
899        *)
900
901
902       Flags for the UnixLabels.access call.
903
904
905
906       val chmod : string -> perm:file_perm -> unit
907
908       Change the permissions of the named file.
909
910
911
912       val fchmod : file_descr -> perm:file_perm -> unit
913
914       Change the permissions of an opened file.
915
916
917       Raises Invalid_argument on Windows
918
919
920
921       val chown : string -> uid:int -> gid:int -> unit
922
923       Change the owner uid and owner gid of the named file.
924
925
926       Raises Invalid_argument on Windows
927
928
929
930       val fchown : file_descr -> uid:int -> gid:int -> unit
931
932       Change the owner uid and owner gid of an opened file.
933
934
935       Raises Invalid_argument on Windows
936
937
938
939       val umask : int -> int
940
941       Set  the  process's  file  mode  creation mask, and return the previous
942       mask.
943
944
945       Raises Invalid_argument on Windows
946
947
948
949       val access : string -> perm:access_permission list -> unit
950
951       Check that the process has the given permissions over the named file.
952
953       On Windows: execute permission X_OK cannot be tested,  just  tests  for
954       read permission instead.
955
956
957       Raises Unix_error otherwise.
958
959
960
961
962   Operations on file descriptors
963       val dup : ?cloexec:bool -> file_descr -> file_descr
964
965       Return a new file descriptor referencing the same file as the given de‐
966       scriptor.  See UnixLabels.set_close_on_exec for  documentation  on  the
967       cloexec optional argument.
968
969
970
971       val dup2 : ?cloexec:bool -> src:file_descr -> dst:file_descr -> unit
972
973
974       dup2  ~src  ~dst duplicates src to dst , closing dst if already opened.
975       See UnixLabels.set_close_on_exec for documentation on the  cloexec  op‐
976       tional argument.
977
978
979
980       val set_nonblock : file_descr -> unit
981
982       Set  the  ``non-blocking''  flag  on  the  given  descriptor.  When the
983       non-blocking flag is set, reading on a descriptor  on  which  there  is
984       temporarily  no  data  available raises the EAGAIN or EWOULDBLOCK error
985       instead of blocking; writing on a descriptor on which there  is  tempo‐
986       rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
987
988
989
990       val clear_nonblock : file_descr -> unit
991
992       Clear  the  ``non-blocking'' flag on the given descriptor.  See UnixLa‐
993       bels.set_nonblock .
994
995
996
997       val set_close_on_exec : file_descr -> unit
998
999       Set the ``close-on-exec'' flag on the given descriptor.   A  descriptor
1000       with  the  close-on-exec  flag is automatically closed when the current
1001       process starts another program with one of the  exec  ,  create_process
1002       and open_process functions.
1003
1004       It  is often a security hole to leak file descriptors opened on, say, a
1005       private file to an external program: the program, then, gets access  to
1006       the  private  file  and can do bad things with it.  Hence, it is highly
1007       recommended to set all file descriptors  ``close-on-exec'',  except  in
1008       the  very few cases where a file descriptor actually needs to be trans‐
1009       mitted to another program.
1010
1011       The best way to set a file descriptor ``close-on-exec'' is to create it
1012       in  this  state.   To this end, the openfile function has O_CLOEXEC and
1013       O_KEEPEXEC flags to enforce ``close-on-exec'' mode or  ``keep-on-exec''
1014       mode,  respectively.  All other operations in the Unix module that cre‐
1015       ate file descriptors have an optional argument ?cloexec:bool  to  indi‐
1016       cate whether the file descriptor should be created in ``close-on-exec''
1017       mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by  writ‐
1018       ing  ~cloexec:false  ).   For  historical reasons, the default file de‐
1019       scriptor creation mode is ``keep-on-exec'', if no cloexec optional  ar‐
1020       gument is given.  This is not a safe default, hence it is highly recom‐
1021       mended to pass explicit cloexec arguments  to  operations  that  create
1022       file descriptors.
1023
1024       The  cloexec optional arguments and the O_KEEPEXEC flag were introduced
1025       in OCaml 4.05.  Earlier, the common practice was  to  create  file  de‐
1026       scriptors   in   the   default,   ``keep-on-exec''   mode,   then  call
1027       set_close_on_exec on those freshly-created file descriptors.   This  is
1028       not  as  safe as creating the file descriptor in ``close-on-exec'' mode
1029       because, in multithreaded programs, a window  of  vulnerability  exists
1030       between  the  time  when  the  file  descriptor is created and the time
1031       set_close_on_exec completes.  If another thread spawns another  program
1032       during  this  window,  the  descriptor will leak, as it is still in the
1033       ``keep-on-exec'' mode.
1034
1035       Regarding the atomicity guarantees given by ~cloexec:true or by the use
1036       of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
1037       rently-executing Caml thread cannot leak the descriptor by  starting  a
1038       new  process.  On Linux, this guarantee extends to concurrently-execut‐
1039       ing C threads.  As of Feb 2017, other operating systems lack the neces‐
1040       sary  system  calls  and  still expose a window of vulnerability during
1041       which  a  C  thread  can  see  the  newly-created  file  descriptor  in
1042       ``keep-on-exec'' mode.
1043
1044
1045
1046       val clear_close_on_exec : file_descr -> unit
1047
1048       Clear  the ``close-on-exec'' flag on the given descriptor.  See UnixLa‐
1049       bels.set_close_on_exec .
1050
1051
1052
1053
1054   Directories
1055       val mkdir : string -> perm:file_perm -> unit
1056
1057       Create a directory with the given permissions (see UnixLabels.umask ).
1058
1059
1060
1061       val rmdir : string -> unit
1062
1063       Remove an empty directory.
1064
1065
1066
1067       val chdir : string -> unit
1068
1069       Change the process working directory.
1070
1071
1072
1073       val getcwd : unit -> string
1074
1075       Return the name of the current working directory.
1076
1077
1078
1079       val chroot : string -> unit
1080
1081       Change the process root directory.
1082
1083
1084       Raises Invalid_argument on Windows
1085
1086
1087       type dir_handle = Unix.dir_handle
1088
1089
1090       The type of descriptors over opened directories.
1091
1092
1093
1094       val opendir : string -> dir_handle
1095
1096       Open a descriptor on a directory
1097
1098
1099
1100       val readdir : dir_handle -> string
1101
1102       Return the next entry in a directory.
1103
1104
1105       Raises End_of_file when the end of the directory has been reached.
1106
1107
1108
1109       val rewinddir : dir_handle -> unit
1110
1111       Reposition the descriptor to the beginning of the directory
1112
1113
1114
1115       val closedir : dir_handle -> unit
1116
1117       Close a directory descriptor.
1118
1119
1120
1121
1122   Pipes and redirections
1123       val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
1124
1125       Create a pipe. The first component of the result is opened for reading,
1126       that's  the  exit to the pipe. The second component is opened for writ‐
1127       ing, that's the entrance to the pipe.  See UnixLabels.set_close_on_exec
1128       for documentation on the cloexec optional argument.
1129
1130
1131
1132       val mkfifo : string -> perm:file_perm -> unit
1133
1134       Create a named pipe with the given permissions (see UnixLabels.umask ).
1135
1136
1137       Raises Invalid_argument on Windows
1138
1139
1140
1141
1142   High-level process and redirection management
1143       val create_process : prog:string -> args:string array -> stdin:file_de‐
1144       scr -> stdout:file_descr -> stderr:file_descr -> int
1145
1146
1147       create_process ~prog ~args ~stdin ~stdout ~stderr forks a  new  process
1148       that  executes the program in file prog , with arguments args . The pid
1149       of the new process is returned immediately; the  new  process  executes
1150       concurrently  with the current process.  The standard input and outputs
1151       of the new process are connected to the descriptors stdin , stdout  and
1152       stderr .  Passing e.g.  Unix.stdout for stdout prevents the redirection
1153       and causes the new process to have the same standard output as the cur‐
1154       rent  process.   The executable file prog is searched in the path.  The
1155       new process has the same environment as the current process.
1156
1157
1158
1159       val create_process_env : prog:string -> args:string array -> env:string
1160       array  -> stdin:file_descr -> stdout:file_descr -> stderr:file_descr ->
1161       int
1162
1163
1164       create_process_env ~prog ~args ~env ~stdin  ~stdout  ~stderr  works  as
1165       UnixLabels.create_process  ,  except that the extra argument env speci‐
1166       fies the environment passed to the program.
1167
1168
1169
1170       val open_process_in : string -> in_channel
1171
1172       High-level pipe and process management. This function  runs  the  given
1173       command  in parallel with the program.  The standard output of the com‐
1174       mand is redirected to a pipe, which can be read via the returned  input
1175       channel.   The  command is interpreted by the shell /bin/sh (or cmd.exe
1176       on Windows), cf.  UnixLabels.system .  The Filename.quote_command func‐
1177       tion  can be used to quote the command and its arguments as appropriate
1178       for the shell being used.  If the command  does  not  need  to  be  run
1179       through  the  shell,  UnixLabels.open_process_args_in  can be used as a
1180       more   robust   and   more    efficient    alternative    to    UnixLa‐
1181       bels.open_process_in .
1182
1183
1184
1185       val open_process_out : string -> out_channel
1186
1187       Same as UnixLabels.open_process_in , but redirect the standard input of
1188       the command to a pipe.  Data written to the returned output channel  is
1189       sent  to  the standard input of the command.  Warning: writes on output
1190       channels are buffered, hence be careful to  call  flush  at  the  right
1191       times  to ensure correct synchronization.  If the command does not need
1192       to be run through the shell,  UnixLabels.open_process_args_out  can  be
1193       used instead of UnixLabels.open_process_out .
1194
1195
1196
1197       val open_process : string -> in_channel * out_channel
1198
1199       Same  as  UnixLabels.open_process_out , but redirects both the standard
1200       input and standard output of the command to pipes connected to the  two
1201       returned channels.  The input channel is connected to the output of the
1202       command, and the output channel to the input of the  command.   If  the
1203       command   does   not   need  to  be  run  through  the  shell,  UnixLa‐
1204       bels.open_process_args can be used instead of UnixLabels.open_process .
1205
1206
1207
1208       val open_process_full : string ->  env:string  array  ->  in_channel  *
1209       out_channel * in_channel
1210
1211       Similar  to UnixLabels.open_process , but the second argument specifies
1212       the environment passed to the command.  The result is a triple of chan‐
1213       nels connected respectively to the standard output, standard input, and
1214       standard error of the command.  If the command does not need to be  run
1215       through  the  shell,  UnixLabels.open_process_args_full can be used in‐
1216       stead of UnixLabels.open_process_full .
1217
1218
1219
1220       val open_process_args_in : string -> string array -> in_channel
1221
1222
1223       open_process_args_in prog args runs the  program  prog  with  arguments
1224       args .  The new process executes concurrently with the current process.
1225       The standard output of the new process is redirected to a  pipe,  which
1226       can be read via the returned input channel.
1227
1228       The  executable  file  prog  is  searched  in  the path. This behaviour
1229       changed in 4.12; previously prog was looked up only in the current  di‐
1230       rectory.
1231
1232       The new process has the same environment as the current process.
1233
1234
1235       Since 4.08.0
1236
1237
1238
1239       val open_process_args_out : string -> string array -> out_channel
1240
1241       Same as UnixLabels.open_process_args_in , but redirect the standard in‐
1242       put of the new process to a pipe.  Data written to the returned  output
1243       channel  is sent to the standard input of the program.  Warning: writes
1244       on output channels are buffered, hence be careful to call flush at  the
1245       right times to ensure correct synchronization.
1246
1247
1248       Since 4.08.0
1249
1250
1251
1252       val  open_process_args  :  string  ->  string  array  ->  in_channel  *
1253       out_channel
1254
1255       Same as UnixLabels.open_process_args_out , but redirects both the stan‐
1256       dard input and standard output of the new process to pipes connected to
1257       the two returned channels.  The input channel is connected to the  out‐
1258       put of the program, and the output channel to the input of the program.
1259
1260
1261       Since 4.08.0
1262
1263
1264
1265       val  open_process_args_full : string -> string array -> string array ->
1266       in_channel * out_channel * in_channel
1267
1268       Similar to UnixLabels.open_process_args , but the third argument speci‐
1269       fies the environment passed to the new process.  The result is a triple
1270       of channels connected respectively to the standard output, standard in‐
1271       put, and standard error of the program.
1272
1273
1274       Since 4.08.0
1275
1276
1277
1278       val process_in_pid : in_channel -> int
1279
1280       Return  the  pid  of a process opened via UnixLabels.open_process_in or
1281       UnixLabels.open_process_args_in .
1282
1283
1284       Since 4.12.0
1285
1286
1287
1288       val process_out_pid : out_channel -> int
1289
1290       Return the pid of a process opened via  UnixLabels.open_process_out  or
1291       UnixLabels.open_process_args_out .
1292
1293
1294       Since 4.12.0
1295
1296
1297
1298       val process_pid : in_channel * out_channel -> int
1299
1300       Return  the  pid  of  a  process  opened via UnixLabels.open_process or
1301       UnixLabels.open_process_args .
1302
1303
1304       Since 4.12.0
1305
1306
1307
1308       val process_full_pid : in_channel * out_channel * in_channel -> int
1309
1310       Return the pid of a process opened via UnixLabels.open_process_full  or
1311       UnixLabels.open_process_args_full .
1312
1313
1314       Since 4.12.0
1315
1316
1317
1318       val close_process_in : in_channel -> process_status
1319
1320       Close  channels opened by UnixLabels.open_process_in , wait for the as‐
1321       sociated command to terminate, and return its termination status.
1322
1323
1324
1325       val close_process_out : out_channel -> process_status
1326
1327       Close channels opened by UnixLabels.open_process_out , wait for the as‐
1328       sociated command to terminate, and return its termination status.
1329
1330
1331
1332       val close_process : in_channel * out_channel -> process_status
1333
1334       Close channels opened by UnixLabels.open_process , wait for the associ‐
1335       ated command to terminate, and return its termination status.
1336
1337
1338
1339       val close_process_full :  in_channel  *  out_channel  *  in_channel  ->
1340       process_status
1341
1342       Close  channels  opened  by UnixLabels.open_process_full , wait for the
1343       associated command to terminate, and return its termination status.
1344
1345
1346
1347
1348   Symbolic links
1349       val symlink : ?to_dir:bool -> src:string -> dst:string -> unit
1350
1351
1352       symlink ?to_dir ~src ~dst creates the file dst as a  symbolic  link  to
1353       the  file  src  .  On  Windows,  ~to_dir indicates if the symbolic link
1354       points to a directory or a file; if omitted, symlink examines src using
1355       stat  and  picks appropriately, if src does not exist then false is as‐
1356       sumed (for this reason, it is recommended that the ~to_dir parameter be
1357       specified in new code). On Unix, ~to_dir is ignored.
1358
1359       Windows  symbolic  links  are available in Windows Vista onwards. There
1360       are some important differences between Windows symlinks and their POSIX
1361       counterparts.
1362
1363       Windows  symbolic  links  come  in two flavours: directory and regular,
1364       which designate whether the symbolic link points to a  directory  or  a
1365       file.  The  type  must  be correct - a directory symlink which actually
1366       points to a file cannot be selected with chdir and a file symlink which
1367       actually  points  to  a  directory cannot be read or written (note that
1368       Cygwin's emulation layer ignores this distinction).
1369
1370       When symbolic links are created to existing targets,  this  distinction
1371       doesn't  matter  and symlink will automatically create the correct kind
1372       of symbolic link. The distinction matters when a symbolic link is  cre‐
1373       ated to a non-existent target.
1374
1375       The other caveat is that by default symbolic links are a privileged op‐
1376       eration. Administrators will always need to  be  running  elevated  (or
1377       with  UAC  disabled)  and  by  default  normal user accounts need to be
1378       granted the SeCreateSymbolicLinkPrivilege  via  Local  Security  Policy
1379       (secpol.msc) or via Active Directory.
1380
1381
1382       UnixLabels.has_symlink  can  be used to check that a process is able to
1383       create symbolic links.
1384
1385
1386
1387       val has_symlink : unit -> bool
1388
1389       Returns true if the user is able to create symbolic links. On  Windows,
1390       this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1391       ilege but is also running elevated, if necessary. On  other  platforms,
1392       this is simply indicates that the symlink system call is available.
1393
1394
1395       Since 4.03.0
1396
1397
1398
1399       val readlink : string -> string
1400
1401       Read the contents of a symbolic link.
1402
1403
1404
1405
1406   Polling
1407       val  select  :  read:file_descr  list  ->  write:file_descr list -> ex‐
1408       cept:file_descr list -> timeout:float -> file_descr list  *  file_descr
1409       list * file_descr list
1410
1411       Wait  until  some input/output operations become possible on some chan‐
1412       nels. The three list arguments are, respectively, a set of  descriptors
1413       to  check  for reading (first argument), for writing (second argument),
1414       or for exceptional conditions (third argument).  The fourth argument is
1415       the  maximal  timeout,  in seconds; a negative fourth argument means no
1416       timeout (unbounded wait).  The result is composed of three sets of  de‐
1417       scriptors: those ready for reading (first component), ready for writing
1418       (second component), and over which an exceptional condition is  pending
1419       (third component).
1420
1421
1422
1423
1424   Locking
1425       type lock_command = Unix.lock_command =
1426        | F_ULOCK  (* Unlock a region
1427        *)
1428        | F_LOCK  (* Lock a region for writing, and block if already locked
1429        *)
1430        | F_TLOCK  (* Lock a region for writing, or fail if already locked
1431        *)
1432        | F_TEST  (* Test a region for other process locks
1433        *)
1434        | F_RLOCK  (* Lock a region for reading, and block if already locked
1435        *)
1436        | F_TRLOCK  (* Lock a region for reading, or fail if already locked
1437        *)
1438
1439
1440       Commands for UnixLabels.lockf .
1441
1442
1443
1444       val lockf : file_descr -> mode:lock_command -> len:int -> unit
1445
1446
1447       lockf  fd ~mode ~len puts a lock on a region of the file opened as fd .
1448       The region starts at the current read/write position for fd (as set  by
1449       UnixLabels.lseek  ),  and extends len bytes forward if len is positive,
1450       len bytes backwards if len is negative, or to the end of  the  file  if
1451       len  is zero.  A write lock prevents any other process from acquiring a
1452       read or write lock on the region.   A  read  lock  prevents  any  other
1453       process  from acquiring a write lock on the region, but lets other pro‐
1454       cesses acquire read locks on it.
1455
1456       The F_LOCK and F_TLOCK commands attempts to put a  write  lock  on  the
1457       specified  region.  The F_RLOCK and F_TRLOCK commands attempts to put a
1458       read lock on the specified region.  If one or several locks put by  an‐
1459       other  process  prevent  the  current  process from acquiring the lock,
1460       F_LOCK and F_RLOCK block until these locks are removed,  while  F_TLOCK
1461       and  F_TRLOCK  fail immediately with an exception.  The F_ULOCK removes
1462       whatever locks the current process has on the  specified  region.   Fi‐
1463       nally, the F_TEST command tests whether a write lock can be acquired on
1464       the specified region, without actually putting a lock.  It returns  im‐
1465       mediately if successful, or fails otherwise.
1466
1467       What  happens  when  a process tries to lock a region of a file that is
1468       already locked by the same process depends on the OS.  On POSIX-compli‐
1469       ant  systems,  the second lock operation succeeds and may "promote" the
1470       older lock from read lock to write lock.  On Windows, the  second  lock
1471       operation will block or fail.
1472
1473
1474
1475
1476   Signals
1477       Note:  installation  of  signal handlers is performed via the functions
1478       Sys.signal and Sys.set_signal .
1479
1480       val kill : pid:int -> signal:int -> unit
1481
1482
1483       kill ~pid ~signal sends signal number signal to the process with id pid
1484       .
1485
1486       On Windows: only the Sys.sigkill signal is emulated.
1487
1488
1489       type sigprocmask_command = Unix.sigprocmask_command =
1490        | SIG_SETMASK
1491        | SIG_BLOCK
1492        | SIG_UNBLOCK
1493
1494
1495
1496
1497
1498       val sigprocmask : mode:sigprocmask_command -> int list -> int list
1499
1500
1501       sigprocmask  ~mode sigs changes the set of blocked signals.  If mode is
1502       SIG_SETMASK , blocked signals are set to those in the list sigs  .   If
1503       mode is SIG_BLOCK , the signals in sigs are added to the set of blocked
1504       signals.  If mode is SIG_UNBLOCK , the signals in sigs are removed from
1505       the  set of blocked signals.  sigprocmask returns the set of previously
1506       blocked signals.
1507
1508       When the systhreads version of the Thread module is loaded, this  func‐
1509       tion  redirects  to Thread.sigmask . I.e., sigprocmask only changes the
1510       mask of the current thread.
1511
1512
1513       Raises Invalid_argument on Windows (no inter-process  signals  on  Win‐
1514       dows)
1515
1516
1517
1518       val sigpending : unit -> int list
1519
1520       Return the set of blocked signals that are currently pending.
1521
1522
1523       Raises  Invalid_argument  on  Windows (no inter-process signals on Win‐
1524       dows)
1525
1526
1527
1528       val sigsuspend : int list -> unit
1529
1530
1531       sigsuspend sigs atomically sets the blocked signals to sigs  and  waits
1532       for  a non-ignored, non-blocked signal to be delivered.  On return, the
1533       blocked signals are reset to their initial value.
1534
1535
1536       Raises Invalid_argument on Windows (no inter-process  signals  on  Win‐
1537       dows)
1538
1539
1540
1541       val pause : unit -> unit
1542
1543       Wait until a non-ignored, non-blocked signal is delivered.
1544
1545
1546       Raises  Invalid_argument  on  Windows (no inter-process signals on Win‐
1547       dows)
1548
1549
1550
1551
1552   Time functions
1553       type process_times = Unix.process_times = {
1554        tms_utime : float ;  (* User time for the process
1555        *)
1556        tms_stime : float ;  (* System time for the process
1557        *)
1558        tms_cutime : float ;  (* User time for the children processes
1559        *)
1560        tms_cstime : float ;  (* System time for the children processes
1561        *)
1562        }
1563
1564
1565       The execution times (CPU times) of a process.
1566
1567
1568       type tm = Unix.tm = {
1569        tm_sec : int ;  (* Seconds 0..60
1570        *)
1571        tm_min : int ;  (* Minutes 0..59
1572        *)
1573        tm_hour : int ;  (* Hours 0..23
1574        *)
1575        tm_mday : int ;  (* Day of month 1..31
1576        *)
1577        tm_mon : int ;  (* Month of year 0..11
1578        *)
1579        tm_year : int ;  (* Year - 1900
1580        *)
1581        tm_wday : int ;  (* Day of week (Sunday is 0)
1582        *)
1583        tm_yday : int ;  (* Day of year 0..365
1584        *)
1585        tm_isdst : bool ;  (* Daylight time savings in effect
1586        *)
1587        }
1588
1589
1590       The type representing wallclock time and calendar date.
1591
1592
1593
1594       val time : unit -> float
1595
1596       Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1597
1598
1599
1600       val gettimeofday : unit -> float
1601
1602       Same as UnixLabels.time , but with resolution better than 1 second.
1603
1604
1605
1606       val gmtime : float -> tm
1607
1608       Convert a time in seconds, as returned by UnixLabels.time , into a date
1609       and  a  time.  Assumes  UTC (Coordinated Universal Time), also known as
1610       GMT.  To perform the inverse conversion, set the TZ  environment  vari‐
1611       able  to  "UTC",  use UnixLabels.mktime , and then restore the original
1612       value of TZ.
1613
1614
1615
1616       val localtime : float -> tm
1617
1618       Convert a time in seconds, as returned by UnixLabels.time , into a date
1619       and  a  time. Assumes the local time zone.  The function performing the
1620       inverse conversion is UnixLabels.mktime .
1621
1622
1623
1624       val mktime : tm -> float * tm
1625
1626       Convert a date and time, specified by the tm argument, into a  time  in
1627       seconds,  as  returned by UnixLabels.time .  The tm_isdst , tm_wday and
1628       tm_yday fields of tm are ignored.  Also return a normalized copy of the
1629       given  tm  record, with the tm_wday , tm_yday , and tm_isdst fields re‐
1630       computed from the other fields, and the  other  fields  normalized  (so
1631       that, e.g., 40 October is changed into 9 November).  The tm argument is
1632       interpreted in the local time zone.
1633
1634
1635
1636       val alarm : int -> int
1637
1638       Schedule a SIGALRM signal after the given number of seconds.
1639
1640
1641       Raises Invalid_argument on Windows
1642
1643
1644
1645       val sleep : int -> unit
1646
1647       Stop execution for the given number of seconds.
1648
1649
1650
1651       val sleepf : float -> unit
1652
1653       Stop execution for the given number of seconds.  Like sleep , but frac‐
1654       tions of seconds are supported.
1655
1656
1657       Since 4.12.0
1658
1659
1660
1661       val times : unit -> process_times
1662
1663       Return the execution times of the process.
1664
1665       On  Windows:  partially  implemented, will not report timings for child
1666       processes.
1667
1668
1669
1670       val utimes : string -> access:float -> modif:float -> unit
1671
1672       Set the last access time (second arg) and last modification time (third
1673       arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1674       1, 1970.  If both times are 0.0 ,  the  access  and  last  modification
1675       times are both set to the current time.
1676
1677
1678       type interval_timer = Unix.interval_timer =
1679        |  ITIMER_REAL   (*  decrements  in  real  time,  and sends the signal
1680       SIGALRM when expired.
1681        *)
1682        | ITIMER_VIRTUAL  (* decrements in process  virtual  time,  and  sends
1683       SIGVTALRM when expired.
1684        *)
1685        |  ITIMER_PROF  (* (for profiling) decrements both when the process is
1686       running and when the system is running on behalf  of  the  process;  it
1687       sends SIGPROF when expired.
1688        *)
1689
1690
1691       The three kinds of interval timers.
1692
1693
1694       type interval_timer_status = Unix.interval_timer_status = {
1695        it_interval : float ;  (* Period
1696        *)
1697        it_value : float ;  (* Current value of the timer
1698        *)
1699        }
1700
1701
1702       The type describing the status of an interval timer
1703
1704
1705
1706       val getitimer : interval_timer -> interval_timer_status
1707
1708       Return the current status of the given interval timer.
1709
1710
1711       Raises Invalid_argument on Windows
1712
1713
1714
1715       val  setitimer  :  interval_timer  ->  interval_timer_status  -> inter‐
1716       val_timer_status
1717
1718
1719       setitimer t s sets the interval timer t and returns its  previous  sta‐
1720       tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1721       is the time to the next timer expiration; s.it_interval ,  if  nonzero,
1722       specifies  a  value to be used in reloading it_value when the timer ex‐
1723       pires.   Setting  s.it_value  to  zero  disables  the  timer.   Setting
1724       s.it_interval  to  zero  causes the timer to be disabled after its next
1725       expiration.
1726
1727
1728       Raises Invalid_argument on Windows
1729
1730
1731
1732
1733   User id, group id
1734       val getuid : unit -> int
1735
1736       Return the user id of the user executing the process.
1737
1738       On Windows: always returns 1 .
1739
1740
1741
1742       val geteuid : unit -> int
1743
1744       Return the effective user id under which the process runs.
1745
1746       On Windows: always returns 1 .
1747
1748
1749
1750       val setuid : int -> unit
1751
1752       Set the real user id and effective user id for the process.
1753
1754
1755       Raises Invalid_argument on Windows
1756
1757
1758
1759       val getgid : unit -> int
1760
1761       Return the group id of the user executing the process.
1762
1763       On Windows: always returns 1 .
1764
1765
1766
1767       val getegid : unit -> int
1768
1769       Return the effective group id under which the process runs.
1770
1771       On Windows: always returns 1 .
1772
1773
1774
1775       val setgid : int -> unit
1776
1777       Set the real group id and effective group id for the process.
1778
1779
1780       Raises Invalid_argument on Windows
1781
1782
1783
1784       val getgroups : unit -> int array
1785
1786       Return the list of groups to which the user executing the  process  be‐
1787       longs.
1788
1789       On Windows: always returns [|1|] .
1790
1791
1792
1793       val setgroups : int array -> unit
1794
1795
1796       setgroups  groups  sets  the  supplementary  group  IDs for the calling
1797       process. Appropriate privileges are required.
1798
1799
1800       Raises Invalid_argument on Windows
1801
1802
1803
1804       val initgroups : string -> int -> unit
1805
1806
1807       initgroups user group initializes the group access list by reading  the
1808       group  database /etc/group and using all groups of which user is a mem‐
1809       ber. The additional group group is also added to the list.
1810
1811
1812       Raises Invalid_argument on Windows
1813
1814
1815       type passwd_entry = Unix.passwd_entry = {
1816        pw_name : string ;
1817        pw_passwd : string ;
1818        pw_uid : int ;
1819        pw_gid : int ;
1820        pw_gecos : string ;
1821        pw_dir : string ;
1822        pw_shell : string ;
1823        }
1824
1825
1826       Structure of entries in the passwd database.
1827
1828
1829       type group_entry = Unix.group_entry = {
1830        gr_name : string ;
1831        gr_passwd : string ;
1832        gr_gid : int ;
1833        gr_mem : string array ;
1834        }
1835
1836
1837       Structure of entries in the groups database.
1838
1839
1840
1841       val getlogin : unit -> string
1842
1843       Return the login name of the user executing the process.
1844
1845
1846
1847       val getpwnam : string -> passwd_entry
1848
1849       Find an entry in passwd with the given name.
1850
1851
1852       Raises Not_found if no such entry exists, or always on Windows.
1853
1854
1855
1856       val getgrnam : string -> group_entry
1857
1858       Find an entry in group with the given name.
1859
1860
1861       Raises Not_found if no such entry exists, or always on Windows.
1862
1863
1864
1865       val getpwuid : int -> passwd_entry
1866
1867       Find an entry in passwd with the given user id.
1868
1869
1870       Raises Not_found if no such entry exists, or always on Windows.
1871
1872
1873
1874       val getgrgid : int -> group_entry
1875
1876       Find an entry in group with the given group id.
1877
1878
1879       Raises Not_found if no such entry exists, or always on Windows.
1880
1881
1882
1883
1884   Internet addresses
1885       type inet_addr = Unix.inet_addr
1886
1887
1888       The abstract type of Internet addresses.
1889
1890
1891
1892       val inet_addr_of_string : string -> inet_addr
1893
1894       Conversion from the printable representation of an Internet address  to
1895       its internal representation.  The argument string consists of 4 numbers
1896       separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up  to
1897       8 numbers separated by colons for IPv6 addresses.
1898
1899
1900       Raises Failure when given a string that does not match these formats.
1901
1902
1903
1904       val string_of_inet_addr : inet_addr -> string
1905
1906       Return the printable representation of the given Internet address.  See
1907       UnixLabels.inet_addr_of_string for a description of the printable  rep‐
1908       resentation.
1909
1910
1911
1912       val inet_addr_any : inet_addr
1913
1914       A  special  IPv4 address, for use only with bind , representing all the
1915       Internet addresses that the host machine possesses.
1916
1917
1918
1919       val inet_addr_loopback : inet_addr
1920
1921       A special IPv4 address representing the host machine ( 127.0.0.1 ).
1922
1923
1924
1925       val inet6_addr_any : inet_addr
1926
1927       A special IPv6 address, for use only with bind , representing  all  the
1928       Internet addresses that the host machine possesses.
1929
1930
1931
1932       val inet6_addr_loopback : inet_addr
1933
1934       A special IPv6 address representing the host machine ( ::1 ).
1935
1936
1937
1938       val is_inet6_addr : inet_addr -> bool
1939
1940       Whether the given inet_addr is an IPv6 address.
1941
1942
1943       Since 4.12.0
1944
1945
1946
1947
1948   Sockets
1949       type socket_domain = Unix.socket_domain =
1950        | PF_UNIX  (* Unix domain
1951        *)
1952        | PF_INET  (* Internet domain (IPv4)
1953        *)
1954        | PF_INET6  (* Internet domain (IPv6)
1955        *)
1956
1957
1958       The  type  of  socket  domains.  Not all platforms support IPv6 sockets
1959       (type PF_INET6 ).
1960
1961       On Windows: PF_UNIX supported since  4.14.0  on  Windows  10  1803  and
1962       later.
1963
1964
1965       type socket_type = Unix.socket_type =
1966        | SOCK_STREAM  (* Stream socket
1967        *)
1968        | SOCK_DGRAM  (* Datagram socket
1969        *)
1970        | SOCK_RAW  (* Raw socket
1971        *)
1972        | SOCK_SEQPACKET  (* Sequenced packets socket
1973        *)
1974
1975
1976       The  type  of socket kinds, specifying the semantics of communications.
1977       SOCK_SEQPACKET is included for completeness, but is rarely supported by
1978       the OS, and needs system calls that are not available in this library.
1979
1980
1981       type sockaddr = Unix.sockaddr =
1982        | ADDR_UNIX of string
1983        | ADDR_INET of inet_addr * int
1984
1985
1986       The  type  of  socket addresses.  ADDR_UNIX name is a socket address in
1987       the  Unix  domain;  name  is  a  file  name   in   the   file   system.
1988       ADDR_INET(addr,port)  is  a socket address in the Internet domain; addr
1989       is the Internet address of the machine, and port is the port number.
1990
1991
1992
1993       val socket : ?cloexec:bool -> domain:socket_domain ->  kind:socket_type
1994       -> protocol:int -> file_descr
1995
1996       Create  a  new socket in the given domain, and with the given kind. The
1997       third argument is the protocol type; 0 selects the default protocol for
1998       that  kind of sockets.  See UnixLabels.set_close_on_exec for documenta‐
1999       tion on the cloexec optional argument.
2000
2001
2002
2003       val domain_of_sockaddr : sockaddr -> socket_domain
2004
2005       Return the socket domain adequate for the given socket address.
2006
2007
2008
2009       val   socketpair   :   ?cloexec:bool   ->    domain:socket_domain    ->
2010       kind:socket_type -> protocol:int -> file_descr * file_descr
2011
2012       Create  a  pair  of  unnamed  sockets, connected together.  See UnixLa‐
2013       bels.set_close_on_exec for documentation on the cloexec optional  argu‐
2014       ment.
2015
2016
2017       Raises Invalid_argument on Windows
2018
2019
2020
2021       val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
2022
2023       Accept  connections  on  the given socket. The returned descriptor is a
2024       socket connected to the client; the returned address is the address  of
2025       the connecting client.  See UnixLabels.set_close_on_exec for documenta‐
2026       tion on the cloexec optional argument.
2027
2028
2029
2030       val bind : file_descr -> addr:sockaddr -> unit
2031
2032       Bind a socket to an address.
2033
2034
2035
2036       val connect : file_descr -> addr:sockaddr -> unit
2037
2038       Connect a socket to an address.
2039
2040
2041
2042       val listen : file_descr -> max:int -> unit
2043
2044       Set up a socket for receiving connection requests. The integer argument
2045       is the maximal number of pending requests.
2046
2047
2048       type shutdown_command = Unix.shutdown_command =
2049        | SHUTDOWN_RECEIVE  (* Close for receiving
2050        *)
2051        | SHUTDOWN_SEND  (* Close for sending
2052        *)
2053        | SHUTDOWN_ALL  (* Close both
2054        *)
2055
2056
2057       The type of commands for shutdown .
2058
2059
2060
2061       val shutdown : file_descr -> mode:shutdown_command -> unit
2062
2063       Shutdown  a socket connection.  SHUTDOWN_SEND as second argument causes
2064       reads on the other end of the connection to return an end-of-file  con‐
2065       dition.  SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
2066       tion to return a closed pipe condition ( SIGPIPE signal).
2067
2068
2069
2070       val getsockname : file_descr -> sockaddr
2071
2072       Return the address of the given socket.
2073
2074
2075
2076       val getpeername : file_descr -> sockaddr
2077
2078       Return the address of the host connected to the given socket.
2079
2080
2081       type msg_flag = Unix.msg_flag =
2082        | MSG_OOB
2083        | MSG_DONTROUTE
2084        | MSG_PEEK
2085
2086
2087       The flags for UnixLabels.recv , UnixLabels.recvfrom  ,  UnixLabels.send
2088       and UnixLabels.sendto .
2089
2090
2091
2092       val   recv   :  file_descr  ->  buf:bytes  ->  pos:int  ->  len:int  ->
2093       mode:msg_flag list -> int
2094
2095       Receive data from a connected socket.
2096
2097
2098
2099       val recvfrom :  file_descr  ->  buf:bytes  ->  pos:int  ->  len:int  ->
2100       mode:msg_flag list -> int * sockaddr
2101
2102       Receive data from an unconnected socket.
2103
2104
2105
2106       val   send   :  file_descr  ->  buf:bytes  ->  pos:int  ->  len:int  ->
2107       mode:msg_flag list -> int
2108
2109       Send data over a connected socket.
2110
2111
2112
2113       val send_substring : file_descr -> buf:string -> pos:int -> len:int  ->
2114       mode:msg_flag list -> int
2115
2116       Same  as  send  , but take the data from a string instead of a byte se‐
2117       quence.
2118
2119
2120       Since 4.02.0
2121
2122
2123
2124       val  sendto  :  file_descr  ->  buf:bytes  ->  pos:int  ->  len:int  ->
2125       mode:msg_flag list -> addr:sockaddr -> int
2126
2127       Send data over an unconnected socket.
2128
2129
2130
2131       val  sendto_substring  : file_descr -> buf:string -> pos:int -> len:int
2132       -> mode:msg_flag list -> sockaddr -> int
2133
2134       Same as sendto , but take the data from a string instead of a byte  se‐
2135       quence.
2136
2137
2138       Since 4.02.0
2139
2140
2141
2142
2143   Socket options
2144       type socket_bool_option = Unix.socket_bool_option =
2145        | SO_DEBUG  (* Record debugging information
2146        *)
2147        | SO_BROADCAST  (* Permit sending of broadcast messages
2148        *)
2149        | SO_REUSEADDR  (* Allow reuse of local addresses for bind
2150        *)
2151        | SO_KEEPALIVE  (* Keep connection active
2152        *)
2153        | SO_DONTROUTE  (* Bypass the standard routing algorithms
2154        *)
2155        | SO_OOBINLINE  (* Leave out-of-band data in line
2156        *)
2157        | SO_ACCEPTCONN  (* Report whether socket listening is enabled
2158        *)
2159        | TCP_NODELAY  (* Control the Nagle algorithm for TCP sockets
2160        *)
2161        | IPV6_ONLY  (* Forbid binding an IPv6 socket to an IPv4 address
2162        *)
2163        | SO_REUSEPORT  (* Allow reuse of address and port bindings
2164        *)
2165
2166
2167       The socket options that can be consulted with UnixLabels.getsockopt and
2168       modified with UnixLabels.setsockopt .  These options have a  boolean  (
2169       true / false ) value.
2170
2171
2172       type socket_int_option = Unix.socket_int_option =
2173        | SO_SNDBUF  (* Size of send buffer
2174        *)
2175        | SO_RCVBUF  (* Size of received buffer
2176        *)
2177        | SO_ERROR  (* Deprecated.  Use UnixLabels.getsockopt_error instead.
2178        *)
2179        | SO_TYPE  (* Report the socket type
2180        *)
2181        |  SO_RCVLOWAT  (* Minimum number of bytes to process for input opera‐
2182       tions
2183        *)
2184        | SO_SNDLOWAT  (* Minimum number of bytes to process for output opera‐
2185       tions
2186        *)
2187
2188
2189       The socket options that can be consulted with UnixLabels.getsockopt_int
2190       and modified with UnixLabels.setsockopt_int .  These  options  have  an
2191       integer value.
2192
2193
2194       type socket_optint_option = Unix.socket_optint_option =
2195        | SO_LINGER  (* Whether to linger on closed connections that have data
2196       present, and for how long (in seconds)
2197        *)
2198
2199
2200       The socket options  that  can  be  consulted  with  UnixLabels.getsock‐
2201       opt_optint  and modified with UnixLabels.setsockopt_optint .  These op‐
2202       tions have a value of type int option , with None meaning ``disabled''.
2203
2204
2205       type socket_float_option = Unix.socket_float_option =
2206        | SO_RCVTIMEO  (* Timeout for input operations
2207        *)
2208        | SO_SNDTIMEO  (* Timeout for output operations
2209        *)
2210
2211
2212       The socket options  that  can  be  consulted  with  UnixLabels.getsock‐
2213       opt_float  and  modified  with UnixLabels.setsockopt_float .  These op‐
2214       tions have a floating-point value representing a time in seconds.   The
2215       value 0 means infinite timeout.
2216
2217
2218
2219       val getsockopt : file_descr -> socket_bool_option -> bool
2220
2221       Return  the  current  status  of  a  boolean-valued option in the given
2222       socket.
2223
2224
2225
2226       val setsockopt : file_descr -> socket_bool_option -> bool -> unit
2227
2228       Set or clear a boolean-valued option in the given socket.
2229
2230
2231
2232       val getsockopt_int : file_descr -> socket_int_option -> int
2233
2234       Same as UnixLabels.getsockopt for an integer-valued socket option.
2235
2236
2237
2238       val setsockopt_int : file_descr -> socket_int_option -> int -> unit
2239
2240       Same as UnixLabels.setsockopt for an integer-valued socket option.
2241
2242
2243
2244       val getsockopt_optint : file_descr -> socket_optint_option ->  int  op‐
2245       tion
2246
2247       Same as UnixLabels.getsockopt for a socket option whose value is an int
2248       option .
2249
2250
2251
2252       val setsockopt_optint : file_descr -> socket_optint_option ->  int  op‐
2253       tion -> unit
2254
2255       Same as UnixLabels.setsockopt for a socket option whose value is an int
2256       option .
2257
2258
2259
2260       val getsockopt_float : file_descr -> socket_float_option -> float
2261
2262       Same as UnixLabels.getsockopt for a socket  option  whose  value  is  a
2263       floating-point number.
2264
2265
2266
2267       val  setsockopt_float  :  file_descr -> socket_float_option -> float ->
2268       unit
2269
2270       Same as UnixLabels.setsockopt for a socket  option  whose  value  is  a
2271       floating-point number.
2272
2273
2274
2275       val getsockopt_error : file_descr -> error option
2276
2277       Return  the error condition associated with the given socket, and clear
2278       it.
2279
2280
2281
2282
2283   High-level network connection functions
2284       val open_connection : sockaddr -> in_channel * out_channel
2285
2286       Connect to a server at the given address.  Return a  pair  of  buffered
2287       channels connected to the server.  Remember to call flush on the output
2288       channel at the right times to ensure correct synchronization.
2289
2290       The two channels returned by open_connection share a  descriptor  to  a
2291       socket.   Therefore,  when  the  connection  is  over,  you should call
2292       close_out on the output channel, which will also close  the  underlying
2293       socket.   Do  not  call  close_in on the input channel; it will be col‐
2294       lected by the GC eventually.
2295
2296
2297
2298       val shutdown_connection : in_channel -> unit
2299
2300       ``Shut down'' a connection established with  UnixLabels.open_connection
2301       ;  that  is, transmit an end-of-file condition to the server reading on
2302       the other side of the connection. This does not close  the  socket  and
2303       the  channels used by the connection.  See Unix.open_connection for how
2304       to close them once the connection is over.
2305
2306
2307
2308       val  establish_server  :  (in_channel  ->  out_channel  ->   unit)   ->
2309       addr:sockaddr -> unit
2310
2311       Establish  a  server on the given address.  The function given as first
2312       argument is called for each connection with two buffered channels  con‐
2313       nected to the client. A new process is created for each connection. The
2314       function UnixLabels.establish_server never returns normally.
2315
2316       The two channels given to the function share a descriptor to a  socket.
2317       The function does not need to close the channels, since this occurs au‐
2318       tomatically when the function returns.  If  the  function  prefers  ex‐
2319       plicit  closing, it should close the output channel using close_out and
2320       leave  the  input  channel   unclosed,   for   reasons   explained   in
2321       Unix.in_channel_of_descr .
2322
2323
2324       Raises Invalid_argument on Windows. Use threads instead.
2325
2326
2327
2328
2329   Host and protocol databases
2330       type host_entry = Unix.host_entry = {
2331        h_name : string ;
2332        h_aliases : string array ;
2333        h_addrtype : socket_domain ;
2334        h_addr_list : inet_addr array ;
2335        }
2336
2337
2338       Structure of entries in the hosts database.
2339
2340
2341       type protocol_entry = Unix.protocol_entry = {
2342        p_name : string ;
2343        p_aliases : string array ;
2344        p_proto : int ;
2345        }
2346
2347
2348       Structure of entries in the protocols database.
2349
2350
2351       type service_entry = Unix.service_entry = {
2352        s_name : string ;
2353        s_aliases : string array ;
2354        s_port : int ;
2355        s_proto : string ;
2356        }
2357
2358
2359       Structure of entries in the services database.
2360
2361
2362
2363       val gethostname : unit -> string
2364
2365       Return the name of the local host.
2366
2367
2368
2369       val gethostbyname : string -> host_entry
2370
2371       Find an entry in hosts with the given name.
2372
2373
2374       Raises Not_found if no such entry exists.
2375
2376
2377
2378       val gethostbyaddr : inet_addr -> host_entry
2379
2380       Find an entry in hosts with the given address.
2381
2382
2383       Raises Not_found if no such entry exists.
2384
2385
2386
2387       val getprotobyname : string -> protocol_entry
2388
2389       Find an entry in protocols with the given name.
2390
2391
2392       Raises Not_found if no such entry exists.
2393
2394
2395
2396       val getprotobynumber : int -> protocol_entry
2397
2398       Find an entry in protocols with the given protocol number.
2399
2400
2401       Raises Not_found if no such entry exists.
2402
2403
2404
2405       val getservbyname : string -> protocol:string -> service_entry
2406
2407       Find an entry in services with the given name.
2408
2409
2410       Raises Not_found if no such entry exists.
2411
2412
2413
2414       val getservbyport : int -> protocol:string -> service_entry
2415
2416       Find an entry in services with the given service number.
2417
2418
2419       Raises Not_found if no such entry exists.
2420
2421
2422       type addr_info = Unix.addr_info = {
2423        ai_family : socket_domain ;  (* Socket domain
2424        *)
2425        ai_socktype : socket_type ;  (* Socket type
2426        *)
2427        ai_protocol : int ;  (* Socket protocol number
2428        *)
2429        ai_addr : sockaddr ;  (* Address
2430        *)
2431        ai_canonname : string ;  (* Canonical host name
2432        *)
2433        }
2434
2435
2436       Address information returned by UnixLabels.getaddrinfo .
2437
2438
2439       type getaddrinfo_option = Unix.getaddrinfo_option =
2440        | AI_FAMILY of socket_domain
2441         (* Impose the given socket domain
2442        *)
2443        | AI_SOCKTYPE of socket_type
2444         (* Impose the given socket type
2445        *)
2446        | AI_PROTOCOL of int
2447         (* Impose the given protocol
2448        *)
2449        |  AI_NUMERICHOST  (* Do not call name resolver, expect numeric IP ad‐
2450       dress
2451        *)
2452        | AI_CANONNAME  (* Fill the ai_canonname field of the result
2453        *)
2454        | AI_PASSIVE  (* Set address to ``any'' address for use  with  UnixLa‐
2455       bels.bind
2456
2457        *)
2458
2459
2460       Options to UnixLabels.getaddrinfo .
2461
2462
2463
2464       val  getaddrinfo  :  string  ->  string  ->  getaddrinfo_option list ->
2465       addr_info list
2466
2467
2468       getaddrinfo host service opts returns a  list  of  UnixLabels.addr_info
2469       records  describing socket parameters and addresses suitable for commu‐
2470       nicating with the given host and service.  The empty list  is  returned
2471       if  the host or service names are unknown, or the constraints expressed
2472       in opts cannot be satisfied.
2473
2474
2475       host is either a host name or the string representation of  an  IP  ad‐
2476       dress.   host  can  be  given  as  the  empty string; in this case, the
2477       ``any'' address or the ``loopback'' address are used, depending whether
2478       opts  contains  AI_PASSIVE  .   service is either a service name or the
2479       string representation of a port number.  service can be  given  as  the
2480       empty string; in this case, the port field of the returned addresses is
2481       set to 0.  opts is a possibly empty list of  options  that  allows  the
2482       caller  to  force  a  particular  socket domain (e.g. IPv6 only or IPv4
2483       only) or a particular socket type (e.g. TCP only or UDP only).
2484
2485
2486       type name_info = Unix.name_info = {
2487        ni_hostname : string ;  (* Name or IP address of host
2488        *)
2489        ni_service : string ;  (* Name of service or port number
2490        *)
2491        }
2492
2493
2494       Host and service information returned by UnixLabels.getnameinfo .
2495
2496
2497       type getnameinfo_option = Unix.getnameinfo_option =
2498        | NI_NOFQDN  (* Do not qualify local host names
2499        *)
2500        | NI_NUMERICHOST  (* Always return host as IP address
2501        *)
2502        | NI_NAMEREQD  (* Fail if host name cannot be determined
2503        *)
2504        | NI_NUMERICSERV  (* Always return service as port number
2505        *)
2506        | NI_DGRAM  (* Consider the service as UDP-based instead  of  the  de‐
2507       fault TCP
2508        *)
2509
2510
2511       Options to UnixLabels.getnameinfo .
2512
2513
2514
2515       val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2516
2517
2518       getnameinfo  addr  opts  returns  the host name and service name corre‐
2519       sponding to the socket address addr .  opts is a possibly empty list of
2520       options that governs how these names are obtained.
2521
2522
2523       Raises Not_found if an error occurs.
2524
2525
2526
2527
2528   Terminal interface
2529       The  following  functions  implement the POSIX standard terminal inter‐
2530       face. They provide control over asynchronous  communication  ports  and
2531       pseudo-terminals. Refer to the termios man page for a complete descrip‐
2532       tion.
2533
2534       type terminal_io = Unix.terminal_io = {
2535
2536       mutable c_ignbrk : bool ;  (* Ignore the break condition.
2537        *)
2538
2539       mutable c_brkint : bool ;  (* Signal interrupt on break condition.
2540        *)
2541
2542       mutable c_ignpar : bool ;  (* Ignore characters with parity errors.
2543        *)
2544
2545       mutable c_parmrk : bool ;  (* Mark parity errors.
2546        *)
2547
2548       mutable c_inpck : bool ;  (* Enable parity check on input.
2549        *)
2550
2551       mutable c_istrip : bool ;  (* Strip 8th bit on input characters.
2552        *)
2553
2554       mutable c_inlcr : bool ;  (* Map NL to CR on input.
2555        *)
2556
2557       mutable c_igncr : bool ;  (* Ignore CR on input.
2558        *)
2559
2560       mutable c_icrnl : bool ;  (* Map CR to NL on input.
2561        *)
2562
2563       mutable c_ixon : bool ;  (* Recognize XON/XOFF characters on input.
2564        *)
2565
2566       mutable c_ixoff : bool ;  (* Emit XON/XOFF chars to control input flow.
2567        *)
2568
2569       mutable c_opost : bool ;  (* Enable output processing.
2570        *)
2571
2572       mutable c_obaud : int ;  (* Output baud rate  (0  means  close  connec‐
2573       tion).
2574        *)
2575
2576       mutable c_ibaud : int ;  (* Input baud rate.
2577        *)
2578
2579       mutable c_csize : int ;  (* Number of bits per character (5-8).
2580        *)
2581
2582       mutable c_cstopb : int ;  (* Number of stop bits (1-2).
2583        *)
2584
2585       mutable c_cread : bool ;  (* Reception is enabled.
2586        *)
2587
2588       mutable c_parenb : bool ;  (* Enable parity generation and detection.
2589        *)
2590
2591       mutable c_parodd : bool ;  (* Specify odd parity instead of even.
2592        *)
2593
2594       mutable c_hupcl : bool ;  (* Hang up on last close.
2595        *)
2596
2597       mutable c_clocal : bool ;  (* Ignore modem status lines.
2598        *)
2599
2600       mutable c_isig : bool ;  (* Generate signal on INTR, QUIT, SUSP.
2601        *)
2602
2603       mutable c_icanon : bool ;  (* Enable canonical processing (line buffer‐
2604       ing and editing)
2605        *)
2606
2607       mutable c_noflsh : bool ;  (* Disable flush after INTR, QUIT, SUSP.
2608        *)
2609
2610       mutable c_echo : bool ;  (* Echo input characters.
2611        *)
2612
2613       mutable c_echoe : bool ;  (* Echo ERASE (to erase previous character).
2614        *)
2615
2616       mutable c_echok : bool ;  (* Echo KILL (to erase the current line).
2617        *)
2618
2619       mutable c_echonl : bool ;  (* Echo NL even if c_echo is not set.
2620        *)
2621
2622       mutable c_vintr : char ;  (* Interrupt character (usually ctrl-C).
2623        *)
2624
2625       mutable c_vquit : char ;  (* Quit character (usually ctrl-\).
2626        *)
2627
2628       mutable c_verase : char ;  (* Erase character (usually DEL or ctrl-H).
2629        *)
2630
2631       mutable c_vkill : char ;  (* Kill line character (usually ctrl-U).
2632        *)
2633
2634       mutable c_veof : char ;  (* End-of-file character (usually ctrl-D).
2635        *)
2636
2637       mutable c_veol : char ;  (* Alternate end-of-line char. (usually none).
2638        *)
2639
2640       mutable c_vmin : int ;  (* Minimum number of characters to read  before
2641       the read request is satisfied.
2642        *)
2643
2644       mutable c_vtime : int ;  (* Maximum read wait (in 0.1s units).
2645        *)
2646
2647       mutable c_vstart : char ;  (* Start character (usually ctrl-Q).
2648        *)
2649
2650       mutable c_vstop : char ;  (* Stop character (usually ctrl-S).
2651        *)
2652        }
2653
2654
2655
2656
2657
2658       val tcgetattr : file_descr -> terminal_io
2659
2660       Return  the  status  of  the terminal referred to by the given file de‐
2661       scriptor.
2662
2663
2664       Raises Invalid_argument on Windows
2665
2666
2667       type setattr_when = Unix.setattr_when =
2668        | TCSANOW
2669        | TCSADRAIN
2670        | TCSAFLUSH
2671
2672
2673
2674
2675
2676       val tcsetattr : file_descr -> mode:setattr_when -> terminal_io -> unit
2677
2678       Set the status of the terminal referred to by the given  file  descrip‐
2679       tor.  The second argument indicates when the status change takes place:
2680       immediately ( TCSANOW ), when all pending output has been transmitted (
2681       TCSADRAIN ), or after flushing all input that has been received but not
2682       read ( TCSAFLUSH ).  TCSADRAIN is recommended when changing the  output
2683       parameters; TCSAFLUSH , when changing the input parameters.
2684
2685
2686       Raises Invalid_argument on Windows
2687
2688
2689
2690       val tcsendbreak : file_descr -> duration:int -> unit
2691
2692       Send  a break condition on the given file descriptor.  The second argu‐
2693       ment is the duration of the break, in 0.1s units; 0 means standard  du‐
2694       ration (0.25s).
2695
2696
2697       Raises Invalid_argument on Windows
2698
2699
2700
2701       val tcdrain : file_descr -> unit
2702
2703       Waits  until  all  output written on the given file descriptor has been
2704       transmitted.
2705
2706
2707       Raises Invalid_argument on Windows
2708
2709
2710       type flush_queue = Unix.flush_queue =
2711        | TCIFLUSH
2712        | TCOFLUSH
2713        | TCIOFLUSH
2714
2715
2716
2717
2718
2719       val tcflush : file_descr -> mode:flush_queue -> unit
2720
2721       Discard data written on the given file descriptor but not yet transmit‐
2722       ted,  or  data received but not yet read, depending on the second argu‐
2723       ment: TCIFLUSH flushes data received but  not  read,  TCOFLUSH  flushes
2724       data written but not transmitted, and TCIOFLUSH flushes both.
2725
2726
2727       Raises Invalid_argument on Windows
2728
2729
2730       type flow_action = Unix.flow_action =
2731        | TCOOFF
2732        | TCOON
2733        | TCIOFF
2734        | TCION
2735
2736
2737
2738
2739
2740       val tcflow : file_descr -> mode:flow_action -> unit
2741
2742       Suspend  or restart reception or transmission of data on the given file
2743       descriptor, depending on the second argument: TCOOFF  suspends  output,
2744       TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2745       put, and TCION transmits a START character to restart input.
2746
2747
2748       Raises Invalid_argument on Windows
2749
2750
2751
2752       val setsid : unit -> int
2753
2754       Put the calling process in a new session and detach it  from  its  con‐
2755       trolling terminal.
2756
2757
2758       Raises Invalid_argument on Windows
2759
2760
2761
2762
2763
2764OCamldoc                          2023-01-23                     UnixLabels(3)
Impressum