1UnixLabels(3) OCaml library UnixLabels(3)
2
6 UnixLabels - Interface to the Unix system.
7
9 Module UnixLabels
10
12 Module UnixLabels
13 : sig end
14 Interface to the Unix system.
17 To use the labeled version of this module, add module Unix = UnixLabels
19 in your implementation.
20 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 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 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 exception Unix_error of error * string * string
182 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 UnixLabels.Unix_error and Unix.Unix_error are the same, and catching
191 one will catch the other.
192 val error_message : error -> string
196 Return a string describing the given error code.
198 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
202 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 Access to the process environment
212 val environment : unit -> string array
213 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 val unsafe_environment : unit -> string array
221 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 Since 4.12.0
229 val getenv : string -> string
233 Return the value associated to a variable in the process environment,
235 unless the process has special privileges.
236 Raises Not_found if the variable is unbound or the process has special
239 privileges.
240 This function is identical to Sys.getenv .
242 val unsafe_getenv : string -> string
246 Return the value associated to a variable in the process environment.
248 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 Since 4.06.0
257 Raises Not_found if the variable is unbound.
260 val putenv : string -> string -> unit
264 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 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 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 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 Flags for UnixLabels.waitpid .
303 val execv : prog:string -> args:string array -> 'a
307 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 Raises Unix_error on failure
316 val execve : prog:string -> args:string array -> env:string array -> 'a
320 Same as UnixLabels.execv , except that the third argument provides the
322 environment to the program executed.
323 val execvp : prog:string -> args:string array -> 'a
327 Same as UnixLabels.execv , except that the program is searched in the
329 path.
330 val execvpe : prog:string -> args:string array -> env:string array ->
334 'a
335 Same as UnixLabels.execve , except that the program is searched in the
337 path.
338 val fork : unit -> int
342 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 On Windows: not implemented, use UnixLabels.create_process or threads.
347 val wait : unit -> int * process_status
351 Wait until one of the children processes die, and return its pid and
353 termination status.
354 On Windows: not implemented, use UnixLabels.waitpid .
356 val waitpid : mode:wait_flag list -> int -> int * process_status
360 Same as UnixLabels.wait , but waits for the child process whose pid is
362 given. A pid of -1 means wait for any child. A pid of 0 means wait
363 for any child in the same process group as the current process. Nega‐
364 tive pid arguments represent process groups. The list of options indi‐
365 cates whether waitpid should return immediately without waiting, and
366 whether it should report stopped children.
367 On Windows: can only wait for a given PID, not any child process.
369 val system : string -> process_status
373 Execute the given command, wait until it terminates, and return its
375 termination status. The string is interpreted by the shell /bin/sh (or
376 the command interpreter cmd.exe on Windows) and therefore can contain
377 redirections, quotes, variables, etc. To properly quote whitespace and
378 shell special characters occurring in file names or command arguments,
379 the use of Filename.quote_command is recommended. The result WEXITED
380 127 indicates that the shell couldn't be executed.
381 val _exit : int -> 'a
385 Terminate the calling process immediately, returning the given status
387 code to the operating system: usually 0 to indicate no errors, and a
388 small positive integer to indicate failure. Unlike exit , Unix._exit
389 performs no finalization whatsoever: functions registered with at_exit
390 are not called, input/output channels are not flushed, and the C
391 run-time system is not finalized either.
392 The typical use of Unix._exit is after a Unix.fork operation, when the
394 child process runs into a fatal error and must exit. In this case, it
395 is preferable to not perform any finalization action in the child
396 process, as these actions could interfere with similar actions per‐
397 formed by the parent process. For example, output channels should not
398 be flushed by the child process, as the parent process may flush them
399 again later, resulting in duplicate output.
400 Since 4.12.0
403 val getpid : unit -> int
407 Return the pid of the process.
409 val getppid : unit -> int
413 Return the pid of the parent process.
415 On Windows: not implemented (because it is meaningless).
417 val nice : int -> int
421 Change the process priority. The integer argument is added to the
423 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
424 ties.) Return the new nice value.
425 On Windows: not implemented.
427 Basic file input/output
432 type file_descr = Unix.file_descr
433 The abstract type of file descriptors.
436 val stdin : file_descr
440 File descriptor for standard input.
442 val stdout : file_descr
446 File descriptor for standard output.
448 val stderr : file_descr
452 File descriptor for standard error.
454 type open_flag = Unix.open_flag =
457 | O_RDONLY (* Open for reading
458 *)
459 | O_WRONLY (* Open for writing
460 *)
461 | O_RDWR (* Open for reading and writing
462 *)
463 | O_NONBLOCK (* Open in non-blocking mode
464 *)
465 | O_APPEND (* Open for append
466 *)
467 | O_CREAT (* Create if nonexistent
468 *)
469 | O_TRUNC (* Truncate to 0 length if existing
470 *)
471 | O_EXCL (* Fail if existing
472 *)
473 | O_NOCTTY (* Don't make this dev a controlling tty
474 *)
475 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
476 pletion'
477 *)
478 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
479 pletion'
480 *)
481 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
482 *)
483 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
484 still open
485 *)
486 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
487 by UnixLabels.openfile . See UnixLabels.set_close_on_exec for more in‐
488 formation.
489 *)
490 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
491 default.
492 *)
493 The flags to UnixLabels.openfile .
496 type file_perm = int
499 The type of file access rights, e.g. 0o640 is read and write for user,
502 read for group, none for others
503 val openfile : string -> mode:open_flag list -> perm:file_perm ->
507 file_descr
508 Open the named file with the given flags. Third argument is the permis‐
510 sions to give to the file if it is created (see UnixLabels.umask ). Re‐
511 turn a file descriptor on the named file.
512 val close : file_descr -> unit
516 Close a file descriptor.
518 val fsync : file_descr -> unit
522 Flush file buffers to disk.
524 Since 4.12.0
527 val read : file_descr -> buf:bytes -> pos:int -> len:int -> int
531 read fd ~buf ~pos ~len reads len bytes from descriptor fd , storing
534 them in byte sequence buf , starting at position pos in buf . Return
535 the number of bytes actually read.
536 val write : file_descr -> buf:bytes -> pos:int -> len:int -> int
540 write fd ~buf ~pos ~len writes len bytes to descriptor fd , taking them
543 from byte sequence buf , starting at position pos in buff . Return the
544 number of bytes actually written. write repeats the writing operation
545 until all bytes have been written or an error occurs.
546 val single_write : file_descr -> buf:bytes -> pos:int -> len:int -> int
550 Same as UnixLabels.write , but attempts to write only once. Thus, if
552 an error occurs, single_write guarantees that no data has been written.
553 val write_substring : file_descr -> buf:string -> pos:int -> len:int ->
557 int
558 Same as UnixLabels.write , but take the data from a string instead of a
560 byte sequence.
561 Since 4.02.0
564 val single_write_substring : file_descr -> buf:string -> pos:int ->
568 len:int -> int
569 Same as UnixLabels.single_write , but take the data from a string in‐
571 stead of a byte sequence.
572 Since 4.02.0
575 Interfacing with the standard input/output library
580 val in_channel_of_descr : file_descr -> in_channel
581 Create an input channel reading from the given descriptor. The channel
583 is initially in binary mode; use set_binary_mode_in ic false if text
584 mode is desired. Text mode is supported only if the descriptor refers
585 to a file or pipe, but is not supported if it refers to a socket.
586 On Windows: set_binary_mode_in always fails on channels created with
588 this function.
589 Beware that input channels are buffered, so more characters may have
591 been read from the descriptor than those accessed using channel func‐
592 tions. Channels also keep a copy of the current position in the file.
593 Closing the channel ic returned by in_channel_of_descr fd using
595 close_in ic also closes the underlying descriptor fd . It is incorrect
596 to close both the channel ic and the descriptor fd .
597 If several channels are created on the same descriptor, one of the
599 channels must be closed, but not the others. Consider for example a
600 descriptor s connected to a socket and two channels ic = in_chan‐
601 nel_of_descr s and oc = out_channel_of_descr s . The recommended clos‐
602 ing protocol is to perform close_out oc , which flushes buffered output
603 to the socket then closes the socket. The ic channel must not be
604 closed and will be collected by the GC eventually.
605 val out_channel_of_descr : file_descr -> out_channel
609 Create an output channel writing on the given descriptor. The channel
611 is initially in binary mode; use set_binary_mode_out oc false if text
612 mode is desired. Text mode is supported only if the descriptor refers
613 to a file or pipe, but is not supported if it refers to a socket.
614 On Windows: set_binary_mode_out always fails on channels created with
616 this function.
617 Beware that output channels are buffered, so you may have to call flush
619 to ensure that all data has been sent to the descriptor. Channels also
620 keep a copy of the current position in the file.
621 Closing the channel oc returned by out_channel_of_descr fd using
623 close_out oc also closes the underlying descriptor fd . It is incor‐
624 rect to close both the channel ic and the descriptor fd .
625 See Unix.in_channel_of_descr for a discussion of the closing protocol
627 when several channels are created on the same descriptor.
628 val descr_of_in_channel : in_channel -> file_descr
632 Return the descriptor corresponding to an input channel.
634 val descr_of_out_channel : out_channel -> file_descr
638 Return the descriptor corresponding to an output channel.
640 Seeking and truncating
645 type seek_command = Unix.seek_command =
646 | SEEK_SET (* indicates positions relative to the beginning of the
647 file
648 *)
649 | SEEK_CUR (* indicates positions relative to the current position
650 *)
651 | SEEK_END (* indicates positions relative to the end of the file
652 *)
653 Positioning modes for UnixLabels.lseek .
656 val lseek : file_descr -> int -> mode:seek_command -> int
660 Set the current position for a file descriptor, and return the result‐
662 ing offset (from the beginning of the file).
663 val truncate : string -> len:int -> unit
667 Truncates the named file to the given size.
669 val ftruncate : file_descr -> len:int -> unit
673 Truncates the file corresponding to the given descriptor to the given
675 size.
676 File status
681 type file_kind = Unix.file_kind =
682 | S_REG (* Regular file
683 *)
684 | S_DIR (* Directory
685 *)
686 | S_CHR (* Character device
687 *)
688 | S_BLK (* Block device
689 *)
690 | S_LNK (* Symbolic link
691 *)
692 | S_FIFO (* Named pipe
693 *)
694 | S_SOCK (* Socket
695 *)
696 type stats = Unix.stats = {
701 st_dev : int ; (* Device number
702 *)
703 st_ino : int ; (* Inode number
704 *)
705 st_kind : file_kind ; (* Kind of the file
706 *)
707 st_perm : file_perm ; (* Access rights
708 *)
709 st_nlink : int ; (* Number of links
710 *)
711 st_uid : int ; (* User id of the owner
712 *)
713 st_gid : int ; (* Group ID of the file's group
714 *)
715 st_rdev : int ; (* Device ID (if special file)
716 *)
717 st_size : int ; (* Size in bytes
718 *)
719 st_atime : float ; (* Last access time
720 *)
721 st_mtime : float ; (* Last modification time
722 *)
723 st_ctime : float ; (* Last status change time
724 *)
725 }
726 The information returned by the UnixLabels.stat calls.
729 val stat : string -> stats
733 Return the information for the named file.
735 val lstat : string -> stats
739 Same as UnixLabels.stat , but in case the file is a symbolic link, re‐
741 turn the information for the link itself.
742 val fstat : file_descr -> stats
746 Return the information for the file associated with the given descrip‐
748 tor.
749 val isatty : file_descr -> bool
753 Return true if the given file descriptor refers to a terminal or con‐
755 sole window, false otherwise.
756 File operations on large files
761 module LargeFile : sig end
762 File operations on large files. This sub-module provides 64-bit vari‐
765 ants of the functions UnixLabels.LargeFile.lseek (for positioning a
766 file descriptor), UnixLabels.LargeFile.truncate and UnixLabels.Large‐
767 File.ftruncate (for changing the size of a file), and UnixLabels.Large‐
768 File.stat , UnixLabels.LargeFile.lstat and UnixLabels.LargeFile.fstat
769 (for obtaining information on files). These alternate functions repre‐
770 sent positions and sizes by 64-bit integers (type int64 ) instead of
771 regular integers (type int ), thus allowing operating on files whose
772 sizes are greater than max_int .
773 Mapping files into memory
778 val map_file : file_descr -> ?pos:int64 -> kind:('a, 'b) Bigarray.kind
779 -> layout:'c Bigarray.layout -> shared:bool -> dims:int array -> ('a,
780 'b, 'c) Bigarray.Genarray.t
781 Memory mapping of a file as a Bigarray. map_file fd ~kind ~layout
783 ~shared ~dims returns a Bigarray of kind kind , layout layout , and di‐
784 mensions as specified in dims . The data contained in this Bigarray
785 are the contents of the file referred to by the file descriptor fd (as
786 opened previously with UnixLabels.openfile , for example). The op‐
787 tional pos parameter is the byte offset in the file of the data being
788 mapped; it defaults to 0 (map from the beginning of the file).
789 If shared is true , all modifications performed on the array are re‐
791 flected in the file. This requires that fd be opened with write per‐
792 missions. If shared is false , modifications performed on the array
793 are done in memory only, using copy-on-write of the modified pages; the
794 underlying file is not affected.
795 Genarray.map_file is much more efficient than reading the whole file in
798 a Bigarray, modifying that Bigarray, and writing it afterwards.
799 To adjust automatically the dimensions of the Bigarray to the actual
801 size of the file, the major dimension (that is, the first dimension for
802 an array with C layout, and the last dimension for an array with For‐
803 tran layout) can be given as -1 . Genarray.map_file then determines
804 the major dimension from the size of the file. The file must contain
805 an integral number of sub-arrays as determined by the non-major dimen‐
806 sions, otherwise Failure is raised.
807 If all dimensions of the Bigarray are given, the file size is matched
809 against the size of the Bigarray. If the file is larger than the Bi‐
810 garray, only the initial portion of the file is mapped to the Bigarray.
811 If the file is smaller than the big array, the file is automatically
812 grown to the size of the Bigarray. This requires write permissions on
813 fd .
814 Array accesses are bounds-checked, but the bounds are determined by the
816 initial call to map_file . Therefore, you should make sure no other
817 process modifies the mapped file while you're accessing it, or a SIGBUS
818 signal may be raised. This happens, for instance, if the file is
819 shrunk.
820 Invalid_argument or Failure may be raised in cases where argument vali‐
823 dation fails.
824 Since 4.06.0
827 Operations on file names
832 val unlink : string -> unit
833 Removes the named file.
835 If the named file is a directory, raises:
837 - EPERM on POSIX compliant system
839 - EISDIR on Linux >= 2.1.132
841 - EACCESS on Windows
843 val rename : src:string -> dst:string -> unit
848 rename ~src ~dst changes the name of a file from src to dst , moving it
851 between directories if needed. If dst already exists, its contents
852 will be replaced with those of src . Depending on the operating sys‐
853 tem, the metadata (permissions, owner, etc) of dst can either be pre‐
854 served or be replaced by those of src .
855 val link : ?follow:bool -> src:string -> dst:string -> unit
859 link ?follow ~src ~dst creates a hard link named dst to the file named
862 src .
863 Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
866 able.
867 Raises ENOSYS On Windows if ~follow:false is requested.
870 val realpath : string -> string
874 realpath p is an absolute pathname for p obtained by resolving all ex‐
877 tra / characters, relative path segments and symbolic links.
878 Since 4.13.0
881 File permissions and ownership
886 type access_permission = Unix.access_permission =
887 | R_OK (* Read permission
888 *)
889 | W_OK (* Write permission
890 *)
891 | X_OK (* Execution permission
892 *)
893 | F_OK (* File exists
894 *)
895 Flags for the UnixLabels.access call.
898 val chmod : string -> perm:file_perm -> unit
902 Change the permissions of the named file.
904 val fchmod : file_descr -> perm:file_perm -> unit
908 Change the permissions of an opened file.
910 On Windows: not implemented.
912 val chown : string -> uid:int -> gid:int -> unit
916 Change the owner uid and owner gid of the named file.
918 On Windows: not implemented.
920 val fchown : file_descr -> uid:int -> gid:int -> unit
924 Change the owner uid and owner gid of an opened file.
926 On Windows: not implemented.
928 val umask : int -> int
932 Set the process's file mode creation mask, and return the previous
934 mask.
935 On Windows: not implemented.
937 val access : string -> perm:access_permission list -> unit
941 Check that the process has the given permissions over the named file.
943 On Windows: execute permission X_OK cannot be tested, just tests for
945 read permission instead.
946 Raises Unix_error otherwise.
949 Operations on file descriptors
954 val dup : ?cloexec:bool -> file_descr -> file_descr
955 Return a new file descriptor referencing the same file as the given de‐
957 scriptor. See UnixLabels.set_close_on_exec for documentation on the
958 cloexec optional argument.
959 val dup2 : ?cloexec:bool -> src:file_descr -> dst:file_descr -> unit
963 dup2 ~src ~dst duplicates src to dst , closing dst if already opened.
966 See UnixLabels.set_close_on_exec for documentation on the cloexec op‐
967 tional argument.
968 val set_nonblock : file_descr -> unit
972 Set the ``non-blocking'' flag on the given descriptor. When the
974 non-blocking flag is set, reading on a descriptor on which there is
975 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
976 instead of blocking; writing on a descriptor on which there is tempo‐
977 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
978 val clear_nonblock : file_descr -> unit
982 Clear the ``non-blocking'' flag on the given descriptor. See UnixLa‐
984 bels.set_nonblock .
985 val set_close_on_exec : file_descr -> unit
989 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
991 with the close-on-exec flag is automatically closed when the current
992 process starts another program with one of the exec , create_process
993 and open_process functions.
994 It is often a security hole to leak file descriptors opened on, say, a
996 private file to an external program: the program, then, gets access to
997 the private file and can do bad things with it. Hence, it is highly
998 recommended to set all file descriptors ``close-on-exec'', except in
999 the very few cases where a file descriptor actually needs to be trans‐
1000 mitted to another program.
1001 The best way to set a file descriptor ``close-on-exec'' is to create it
1003 in this state. To this end, the openfile function has O_CLOEXEC and
1004 O_KEEPEXEC flags to enforce ``close-on-exec'' mode or ``keep-on-exec''
1005 mode, respectively. All other operations in the Unix module that cre‐
1006 ate file descriptors have an optional argument ?cloexec:bool to indi‐
1007 cate whether the file descriptor should be created in ``close-on-exec''
1008 mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by writ‐
1009 ing ~cloexec:false ). For historical reasons, the default file de‐
1010 scriptor creation mode is ``keep-on-exec'', if no cloexec optional ar‐
1011 gument is given. This is not a safe default, hence it is highly recom‐
1012 mended to pass explicit cloexec arguments to operations that create
1013 file descriptors.
1014 The cloexec optional arguments and the O_KEEPEXEC flag were introduced
1016 in OCaml 4.05. Earlier, the common practice was to create file de‐
1017 scriptors in the default, ``keep-on-exec'' mode, then call
1018 set_close_on_exec on those freshly-created file descriptors. This is
1019 not as safe as creating the file descriptor in ``close-on-exec'' mode
1020 because, in multithreaded programs, a window of vulnerability exists
1021 between the time when the file descriptor is created and the time
1022 set_close_on_exec completes. If another thread spawns another program
1023 during this window, the descriptor will leak, as it is still in the
1024 ``keep-on-exec'' mode.
1025 Regarding the atomicity guarantees given by ~cloexec:true or by the use
1027 of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
1028 rently-executing Caml thread cannot leak the descriptor by starting a
1029 new process. On Linux, this guarantee extends to concurrently-execut‐
1030 ing C threads. As of Feb 2017, other operating systems lack the neces‐
1031 sary system calls and still expose a window of vulnerability during
1032 which a C thread can see the newly-created file descriptor in
1033 ``keep-on-exec'' mode.
1034 val clear_close_on_exec : file_descr -> unit
1038 Clear the ``close-on-exec'' flag on the given descriptor. See UnixLa‐
1040 bels.set_close_on_exec .
1041 Directories
1046 val mkdir : string -> perm:file_perm -> unit
1047 Create a directory with the given permissions (see UnixLabels.umask ).
1049 val rmdir : string -> unit
1053 Remove an empty directory.
1055 val chdir : string -> unit
1059 Change the process working directory.
1061 val getcwd : unit -> string
1065 Return the name of the current working directory.
1067 val chroot : string -> unit
1071 Change the process root directory.
1073 On Windows: not implemented.
1075 type dir_handle = Unix.dir_handle
1078 The type of descriptors over opened directories.
1081 val opendir : string -> dir_handle
1085 Open a descriptor on a directory
1087 val readdir : dir_handle -> string
1091 Return the next entry in a directory.
1093 Raises End_of_file when the end of the directory has been reached.
1096 val rewinddir : dir_handle -> unit
1100 Reposition the descriptor to the beginning of the directory
1102 val closedir : dir_handle -> unit
1106 Close a directory descriptor.
1108 Pipes and redirections
1113 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
1114 Create a pipe. The first component of the result is opened for reading,
1116 that's the exit to the pipe. The second component is opened for writ‐
1117 ing, that's the entrance to the pipe. See UnixLabels.set_close_on_exec
1118 for documentation on the cloexec optional argument.
1119 val mkfifo : string -> perm:file_perm -> unit
1123 Create a named pipe with the given permissions (see UnixLabels.umask ).
1125 On Windows: not implemented.
1127 High-level process and redirection management
1132 val create_process : prog:string -> args:string array -> stdin:file_de‐
1133 scr -> stdout:file_descr -> stderr:file_descr -> int
1134 create_process ~prog ~args ~stdin ~stdout ~stderr forks a new process
1137 that executes the program in file prog , with arguments args . The pid
1138 of the new process is returned immediately; the new process executes
1139 concurrently with the current process. The standard input and outputs
1140 of the new process are connected to the descriptors stdin , stdout and
1141 stderr . Passing e.g. Stdlib.stdout for stdout prevents the redirect‐
1142 ion and causes the new process to have the same standard output as the
1143 current process. The executable file prog is searched in the path.
1144 The new process has the same environment as the current process.
1145 val create_process_env : prog:string -> args:string array -> env:string
1149 array -> stdin:file_descr -> stdout:file_descr -> stderr:file_descr ->
1150 int
1151 create_process_env ~prog ~args ~env ~stdin ~stdout ~stderr works as
1154 UnixLabels.create_process , except that the extra argument env speci‐
1155 fies the environment passed to the program.
1156 val open_process_in : string -> in_channel
1160 High-level pipe and process management. This function runs the given
1162 command in parallel with the program. The standard output of the com‐
1163 mand is redirected to a pipe, which can be read via the returned input
1164 channel. The command is interpreted by the shell /bin/sh (or cmd.exe
1165 on Windows), cf. UnixLabels.system . The Filename.quote_command func‐
1166 tion can be used to quote the command and its arguments as appropriate
1167 for the shell being used. If the command does not need to be run
1168 through the shell, UnixLabels.open_process_args_in can be used as a
1169 more robust and more efficient alternative to UnixLa‐
1170 bels.open_process_in .
1171 val open_process_out : string -> out_channel
1175 Same as UnixLabels.open_process_in , but redirect the standard input of
1177 the command to a pipe. Data written to the returned output channel is
1178 sent to the standard input of the command. Warning: writes on output
1179 channels are buffered, hence be careful to call flush at the right
1180 times to ensure correct synchronization. If the command does not need
1181 to be run through the shell, UnixLabels.open_process_args_out can be
1182 used instead of UnixLabels.open_process_out .
1183 val open_process : string -> in_channel * out_channel
1187 Same as UnixLabels.open_process_out , but redirects both the standard
1189 input and standard output of the command to pipes connected to the two
1190 returned channels. The input channel is connected to the output of the
1191 command, and the output channel to the input of the command. If the
1192 command does not need to be run through the shell, UnixLa‐
1193 bels.open_process_args can be used instead of UnixLabels.open_process .
1194 val open_process_full : string -> env:string array -> in_channel *
1198 out_channel * in_channel
1199 Similar to UnixLabels.open_process , but the second argument specifies
1201 the environment passed to the command. The result is a triple of chan‐
1202 nels connected respectively to the standard output, standard input, and
1203 standard error of the command. If the command does not need to be run
1204 through the shell, UnixLabels.open_process_args_full can be used in‐
1205 stead of UnixLabels.open_process_full .
1206 val open_process_args_in : string -> string array -> in_channel
1210 open_process_args_in prog args runs the program prog with arguments
1213 args . The new process executes concurrently with the current process.
1214 The standard output of the new process is redirected to a pipe, which
1215 can be read via the returned input channel.
1216 The executable file prog is searched in the path. This behaviour
1218 changed in 4.12; previously prog was looked up only in the current di‐
1219 rectory.
1220 The new process has the same environment as the current process.
1222 Since 4.08.0
1225 val open_process_args_out : string -> string array -> out_channel
1229 Same as UnixLabels.open_process_args_in , but redirect the standard in‐
1231 put of the new process to a pipe. Data written to the returned output
1232 channel is sent to the standard input of the program. Warning: writes
1233 on output channels are buffered, hence be careful to call flush at the
1234 right times to ensure correct synchronization.
1235 Since 4.08.0
1238 val open_process_args : string -> string array -> in_channel *
1242 out_channel
1243 Same as UnixLabels.open_process_args_out , but redirects both the stan‐
1245 dard input and standard output of the new process to pipes connected to
1246 the two returned channels. The input channel is connected to the out‐
1247 put of the program, and the output channel to the input of the program.
1248 Since 4.08.0
1251 val open_process_args_full : string -> string array -> string array ->
1255 in_channel * out_channel * in_channel
1256 Similar to UnixLabels.open_process_args , but the third argument speci‐
1258 fies the environment passed to the new process. The result is a triple
1259 of channels connected respectively to the standard output, standard in‐
1260 put, and standard error of the program.
1261 Since 4.08.0
1264 val process_in_pid : in_channel -> int
1268 Return the pid of a process opened via UnixLabels.open_process_in or
1270 UnixLabels.open_process_args_in .
1271 Since 4.12.0
1274 val process_out_pid : out_channel -> int
1278 Return the pid of a process opened via UnixLabels.open_process_out or
1280 UnixLabels.open_process_args_out .
1281 Since 4.12.0
1284 val process_pid : in_channel * out_channel -> int
1288 Return the pid of a process opened via UnixLabels.open_process or
1290 UnixLabels.open_process_args .
1291 Since 4.12.0
1294 val process_full_pid : in_channel * out_channel * in_channel -> int
1298 Return the pid of a process opened via UnixLabels.open_process_full or
1300 UnixLabels.open_process_args_full .
1301 Since 4.12.0
1304 val close_process_in : in_channel -> process_status
1308 Close channels opened by UnixLabels.open_process_in , wait for the as‐
1310 sociated command to terminate, and return its termination status.
1311 val close_process_out : out_channel -> process_status
1315 Close channels opened by UnixLabels.open_process_out , wait for the as‐
1317 sociated command to terminate, and return its termination status.
1318 val close_process : in_channel * out_channel -> process_status
1322 Close channels opened by UnixLabels.open_process , wait for the associ‐
1324 ated command to terminate, and return its termination status.
1325 val close_process_full : in_channel * out_channel * in_channel ->
1329 process_status
1330 Close channels opened by UnixLabels.open_process_full , wait for the
1332 associated command to terminate, and return its termination status.
1333 Symbolic links
1338 val symlink : ?to_dir:bool -> src:string -> dst:string -> unit
1339 symlink ?to_dir ~src ~dst creates the file dst as a symbolic link to
1342 the file src . On Windows, ~to_dir indicates if the symbolic link
1343 points to a directory or a file; if omitted, symlink examines src using
1344 stat and picks appropriately, if src does not exist then false is as‐
1345 sumed (for this reason, it is recommended that the ~to_dir parameter be
1346 specified in new code). On Unix, ~to_dir is ignored.
1347 Windows symbolic links are available in Windows Vista onwards. There
1349 are some important differences between Windows symlinks and their POSIX
1350 counterparts.
1351 Windows symbolic links come in two flavours: directory and regular,
1353 which designate whether the symbolic link points to a directory or a
1354 file. The type must be correct - a directory symlink which actually
1355 points to a file cannot be selected with chdir and a file symlink which
1356 actually points to a directory cannot be read or written (note that
1357 Cygwin's emulation layer ignores this distinction).
1358 When symbolic links are created to existing targets, this distinction
1360 doesn't matter and symlink will automatically create the correct kind
1361 of symbolic link. The distinction matters when a symbolic link is cre‐
1362 ated to a non-existent target.
1363 The other caveat is that by default symbolic links are a privileged op‐
1365 eration. Administrators will always need to be running elevated (or
1366 with UAC disabled) and by default normal user accounts need to be
1367 granted the SeCreateSymbolicLinkPrivilege via Local Security Policy
1368 (secpol.msc) or via Active Directory.
1369 UnixLabels.has_symlink can be used to check that a process is able to
1372 create symbolic links.
1373 val has_symlink : unit -> bool
1377 Returns true if the user is able to create symbolic links. On Windows,
1379 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1380 ilege but is also running elevated, if necessary. On other platforms,
1381 this is simply indicates that the symlink system call is available.
1382 Since 4.03.0
1385 val readlink : string -> string
1389 Read the contents of a symbolic link.
1391 Polling
1396 val select : read:file_descr list -> write:file_descr list -> ex‐
1397 cept:file_descr list -> timeout:float -> file_descr list * file_descr
1398 list * file_descr list
1399 Wait until some input/output operations become possible on some chan‐
1401 nels. The three list arguments are, respectively, a set of descriptors
1402 to check for reading (first argument), for writing (second argument),
1403 or for exceptional conditions (third argument). The fourth argument is
1404 the maximal timeout, in seconds; a negative fourth argument means no
1405 timeout (unbounded wait). The result is composed of three sets of de‐
1406 scriptors: those ready for reading (first component), ready for writing
1407 (second component), and over which an exceptional condition is pending
1408 (third component).
1409 Locking
1414 type lock_command = Unix.lock_command =
1415 | F_ULOCK (* Unlock a region
1416 *)
1417 | F_LOCK (* Lock a region for writing, and block if already locked
1418 *)
1419 | F_TLOCK (* Lock a region for writing, or fail if already locked
1420 *)
1421 | F_TEST (* Test a region for other process locks
1422 *)
1423 | F_RLOCK (* Lock a region for reading, and block if already locked
1424 *)
1425 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1426 *)
1427 Commands for UnixLabels.lockf .
1430 val lockf : file_descr -> mode:lock_command -> len:int -> unit
1434 lockf fd ~mode ~len puts a lock on a region of the file opened as fd .
1437 The region starts at the current read/write position for fd (as set by
1438 UnixLabels.lseek ), and extends len bytes forward if len is positive,
1439 len bytes backwards if len is negative, or to the end of the file if
1440 len is zero. A write lock prevents any other process from acquiring a
1441 read or write lock on the region. A read lock prevents any other
1442 process from acquiring a write lock on the region, but lets other pro‐
1443 cesses acquire read locks on it.
1444 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1446 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1447 read lock on the specified region. If one or several locks put by an‐
1448 other process prevent the current process from acquiring the lock,
1449 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1450 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1451 whatever locks the current process has on the specified region. Fi‐
1452 nally, the F_TEST command tests whether a write lock can be acquired on
1453 the specified region, without actually putting a lock. It returns im‐
1454 mediately if successful, or fails otherwise.
1455 What happens when a process tries to lock a region of a file that is
1457 already locked by the same process depends on the OS. On POSIX-compli‐
1458 ant systems, the second lock operation succeeds and may "promote" the
1459 older lock from read lock to write lock. On Windows, the second lock
1460 operation will block or fail.
1461 Signals
1466 Note: installation of signal handlers is performed via the functions
1467 Sys.signal and Sys.set_signal .
1468 val kill : pid:int -> signal:int -> unit
1470 kill ~pid ~signal sends signal number signal to the process with id pid
1473 .
1474 On Windows: only the Sys.sigkill signal is emulated.
1476 type sigprocmask_command = Unix.sigprocmask_command =
1479 | SIG_SETMASK
1480 | SIG_BLOCK
1481 | SIG_UNBLOCK
1482 val sigprocmask : mode:sigprocmask_command -> int list -> int list
1488 sigprocmask ~mode sigs changes the set of blocked signals. If mode is
1491 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1492 mode is SIG_BLOCK , the signals in sigs are added to the set of blocked
1493 signals. If mode is SIG_UNBLOCK , the signals in sigs are removed from
1494 the set of blocked signals. sigprocmask returns the set of previously
1495 blocked signals.
1496 When the systhreads version of the Thread module is loaded, this func‐
1498 tion redirects to Thread.sigmask . I.e., sigprocmask only changes the
1499 mask of the current thread.
1500 On Windows: not implemented (no inter-process signals on Windows).
1502 val sigpending : unit -> int list
1506 Return the set of blocked signals that are currently pending.
1508 On Windows: not implemented (no inter-process signals on Windows).
1510 val sigsuspend : int list -> unit
1514 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1517 for a non-ignored, non-blocked signal to be delivered. On return, the
1518 blocked signals are reset to their initial value.
1519 On Windows: not implemented (no inter-process signals on Windows).
1521 val pause : unit -> unit
1525 Wait until a non-ignored, non-blocked signal is delivered.
1527 On Windows: not implemented (no inter-process signals on Windows).
1529 Time functions
1534 type process_times = Unix.process_times = {
1535 tms_utime : float ; (* User time for the process
1536 *)
1537 tms_stime : float ; (* System time for the process
1538 *)
1539 tms_cutime : float ; (* User time for the children processes
1540 *)
1541 tms_cstime : float ; (* System time for the children processes
1542 *)
1543 }
1544 The execution times (CPU times) of a process.
1547 type tm = Unix.tm = {
1550 tm_sec : int ; (* Seconds 0..60
1551 *)
1552 tm_min : int ; (* Minutes 0..59
1553 *)
1554 tm_hour : int ; (* Hours 0..23
1555 *)
1556 tm_mday : int ; (* Day of month 1..31
1557 *)
1558 tm_mon : int ; (* Month of year 0..11
1559 *)
1560 tm_year : int ; (* Year - 1900
1561 *)
1562 tm_wday : int ; (* Day of week (Sunday is 0)
1563 *)
1564 tm_yday : int ; (* Day of year 0..365
1565 *)
1566 tm_isdst : bool ; (* Daylight time savings in effect
1567 *)
1568 }
1569 The type representing wallclock time and calendar date.
1572 val time : unit -> float
1576 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1578 val gettimeofday : unit -> float
1582 Same as UnixLabels.time , but with resolution better than 1 second.
1584 val gmtime : float -> tm
1588 Convert a time in seconds, as returned by UnixLabels.time , into a date
1590 and a time. Assumes UTC (Coordinated Universal Time), also known as
1591 GMT. To perform the inverse conversion, set the TZ environment vari‐
1592 able to "UTC", use UnixLabels.mktime , and then restore the original
1593 value of TZ.
1594 val localtime : float -> tm
1598 Convert a time in seconds, as returned by UnixLabels.time , into a date
1600 and a time. Assumes the local time zone. The function performing the
1601 inverse conversion is UnixLabels.mktime .
1602 val mktime : tm -> float * tm
1606 Convert a date and time, specified by the tm argument, into a time in
1608 seconds, as returned by UnixLabels.time . The tm_isdst , tm_wday and
1609 tm_yday fields of tm are ignored. Also return a normalized copy of the
1610 given tm record, with the tm_wday , tm_yday , and tm_isdst fields re‐
1611 computed from the other fields, and the other fields normalized (so
1612 that, e.g., 40 October is changed into 9 November). The tm argument is
1613 interpreted in the local time zone.
1614 val alarm : int -> int
1618 Schedule a SIGALRM signal after the given number of seconds.
1620 On Windows: not implemented.
1622 val sleep : int -> unit
1626 Stop execution for the given number of seconds.
1628 val sleepf : float -> unit
1632 Stop execution for the given number of seconds. Like sleep , but frac‐
1634 tions of seconds are supported.
1635 Since 4.12.0
1638 val times : unit -> process_times
1642 Return the execution times of the process.
1644 On Windows: partially implemented, will not report timings for child
1646 processes.
1647 val utimes : string -> access:float -> modif:float -> unit
1651 Set the last access time (second arg) and last modification time (third
1653 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1654 1, 1970. If both times are 0.0 , the access and last modification
1655 times are both set to the current time.
1656 type interval_timer = Unix.interval_timer =
1659 | ITIMER_REAL (* decrements in real time, and sends the signal
1660 SIGALRM when expired.
1661 *)
1662 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1663 SIGVTALRM when expired.
1664 *)
1665 | ITIMER_PROF (* (for profiling) decrements both when the process is
1666 running and when the system is running on behalf of the process; it
1667 sends SIGPROF when expired.
1668 *)
1669 The three kinds of interval timers.
1672 type interval_timer_status = Unix.interval_timer_status = {
1675 it_interval : float ; (* Period
1676 *)
1677 it_value : float ; (* Current value of the timer
1678 *)
1679 }
1680 The type describing the status of an interval timer
1683 val getitimer : interval_timer -> interval_timer_status
1687 Return the current status of the given interval timer.
1689 On Windows: not implemented.
1691 val setitimer : interval_timer -> interval_timer_status -> inter‐
1695 val_timer_status
1696 setitimer t s sets the interval timer t and returns its previous sta‐
1699 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1700 is the time to the next timer expiration; s.it_interval , if nonzero,
1701 specifies a value to be used in reloading it_value when the timer ex‐
1702 pires. Setting s.it_value to zero disables the timer. Setting
1703 s.it_interval to zero causes the timer to be disabled after its next
1704 expiration.
1705 On Windows: not implemented.
1707 User id, group id
1712 val getuid : unit -> int
1713 Return the user id of the user executing the process.
1715 On Windows: always returns 1 .
1717 val geteuid : unit -> int
1721 Return the effective user id under which the process runs.
1723 On Windows: always returns 1 .
1725 val setuid : int -> unit
1729 Set the real user id and effective user id for the process.
1731 On Windows: not implemented.
1733 val getgid : unit -> int
1737 Return the group id of the user executing the process.
1739 On Windows: always returns 1 .
1741 val getegid : unit -> int
1745 Return the effective group id under which the process runs.
1747 On Windows: always returns 1 .
1749 val setgid : int -> unit
1753 Set the real group id and effective group id for the process.
1755 On Windows: not implemented.
1757 val getgroups : unit -> int array
1761 Return the list of groups to which the user executing the process be‐
1763 longs.
1764 On Windows: always returns [|1|] .
1766 val setgroups : int array -> unit
1770 setgroups groups sets the supplementary group IDs for the calling
1773 process. Appropriate privileges are required.
1774 On Windows: not implemented.
1776 val initgroups : string -> int -> unit
1780 initgroups user group initializes the group access list by reading the
1783 group database /etc/group and using all groups of which user is a mem‐
1784 ber. The additional group group is also added to the list.
1785 On Windows: not implemented.
1787 type passwd_entry = Unix.passwd_entry = {
1790 pw_name : string ;
1791 pw_passwd : string ;
1792 pw_uid : int ;
1793 pw_gid : int ;
1794 pw_gecos : string ;
1795 pw_dir : string ;
1796 pw_shell : string ;
1797 }
1798 Structure of entries in the passwd database.
1801 type group_entry = Unix.group_entry = {
1804 gr_name : string ;
1805 gr_passwd : string ;
1806 gr_gid : int ;
1807 gr_mem : string array ;
1808 }
1809 Structure of entries in the groups database.
1812 val getlogin : unit -> string
1816 Return the login name of the user executing the process.
1818 val getpwnam : string -> passwd_entry
1822 Find an entry in passwd with the given name.
1824 Raises Not_found if no such entry exists, or always on Windows.
1827 val getgrnam : string -> group_entry
1831 Find an entry in group with the given name.
1833 Raises Not_found if no such entry exists, or always on Windows.
1836 val getpwuid : int -> passwd_entry
1840 Find an entry in passwd with the given user id.
1842 Raises Not_found if no such entry exists, or always on Windows.
1845 val getgrgid : int -> group_entry
1849 Find an entry in group with the given group id.
1851 Raises Not_found if no such entry exists, or always on Windows.
1854 Internet addresses
1859 type inet_addr = Unix.inet_addr
1860 The abstract type of Internet addresses.
1863 val inet_addr_of_string : string -> inet_addr
1867 Conversion from the printable representation of an Internet address to
1869 its internal representation. The argument string consists of 4 numbers
1870 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1871 8 numbers separated by colons for IPv6 addresses.
1872 Raises Failure when given a string that does not match these formats.
1875 val string_of_inet_addr : inet_addr -> string
1879 Return the printable representation of the given Internet address. See
1881 UnixLabels.inet_addr_of_string for a description of the printable rep‐
1882 resentation.
1883 val inet_addr_any : inet_addr
1887 A special IPv4 address, for use only with bind , representing all the
1889 Internet addresses that the host machine possesses.
1890 val inet_addr_loopback : inet_addr
1894 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1896 val inet6_addr_any : inet_addr
1900 A special IPv6 address, for use only with bind , representing all the
1902 Internet addresses that the host machine possesses.
1903 val inet6_addr_loopback : inet_addr
1907 A special IPv6 address representing the host machine ( ::1 ).
1909 val is_inet6_addr : inet_addr -> bool
1913 Whether the given inet_addr is an IPv6 address.
1915 Since 4.12.0
1918 Sockets
1923 type socket_domain = Unix.socket_domain =
1924 | PF_UNIX (* Unix domain
1925 *)
1926 | PF_INET (* Internet domain (IPv4)
1927 *)
1928 | PF_INET6 (* Internet domain (IPv6)
1929 *)
1930 The type of socket domains. Not all platforms support IPv6 sockets
1933 (type PF_INET6 ).
1934 On Windows: PF_UNIX not implemented.
1936 type socket_type = Unix.socket_type =
1939 | SOCK_STREAM (* Stream socket
1940 *)
1941 | SOCK_DGRAM (* Datagram socket
1942 *)
1943 | SOCK_RAW (* Raw socket
1944 *)
1945 | SOCK_SEQPACKET (* Sequenced packets socket
1946 *)
1947 The type of socket kinds, specifying the semantics of communications.
1950 SOCK_SEQPACKET is included for completeness, but is rarely supported by
1951 the OS, and needs system calls that are not available in this library.
1952 type sockaddr = Unix.sockaddr =
1955 | ADDR_UNIX of string
1956 | ADDR_INET of inet_addr * int
1957 The type of socket addresses. ADDR_UNIX name is a socket address in
1960 the Unix domain; name is a file name in the file system.
1961 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1962 is the Internet address of the machine, and port is the port number.
1963 val socket : ?cloexec:bool -> domain:socket_domain -> kind:socket_type
1967 -> protocol:int -> file_descr
1968 Create a new socket in the given domain, and with the given kind. The
1970 third argument is the protocol type; 0 selects the default protocol for
1971 that kind of sockets. See UnixLabels.set_close_on_exec for documenta‐
1972 tion on the cloexec optional argument.
1973 val domain_of_sockaddr : sockaddr -> socket_domain
1977 Return the socket domain adequate for the given socket address.
1979 val socketpair : ?cloexec:bool -> domain:socket_domain ->
1983 kind:socket_type -> protocol:int -> file_descr * file_descr
1984 Create a pair of unnamed sockets, connected together. See UnixLa‐
1986 bels.set_close_on_exec for documentation on the cloexec optional argu‐
1987 ment.
1988 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1992 Accept connections on the given socket. The returned descriptor is a
1994 socket connected to the client; the returned address is the address of
1995 the connecting client. See UnixLabels.set_close_on_exec for documenta‐
1996 tion on the cloexec optional argument.
1997 val bind : file_descr -> addr:sockaddr -> unit
2001 Bind a socket to an address.
2003 val connect : file_descr -> addr:sockaddr -> unit
2007 Connect a socket to an address.
2009 val listen : file_descr -> max:int -> unit
2013 Set up a socket for receiving connection requests. The integer argument
2015 is the maximal number of pending requests.
2016 type shutdown_command = Unix.shutdown_command =
2019 | SHUTDOWN_RECEIVE (* Close for receiving
2020 *)
2021 | SHUTDOWN_SEND (* Close for sending
2022 *)
2023 | SHUTDOWN_ALL (* Close both
2024 *)
2025 The type of commands for shutdown .
2028 val shutdown : file_descr -> mode:shutdown_command -> unit
2032 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
2034 reads on the other end of the connection to return an end-of-file con‐
2035 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
2036 tion to return a closed pipe condition ( SIGPIPE signal).
2037 val getsockname : file_descr -> sockaddr
2041 Return the address of the given socket.
2043 val getpeername : file_descr -> sockaddr
2047 Return the address of the host connected to the given socket.
2049 type msg_flag = Unix.msg_flag =
2052 | MSG_OOB
2053 | MSG_DONTROUTE
2054 | MSG_PEEK
2055 The flags for UnixLabels.recv , UnixLabels.recvfrom , UnixLabels.send
2058 and UnixLabels.sendto .
2059 val recv : file_descr -> buf:bytes -> pos:int -> len:int ->
2063 mode:msg_flag list -> int
2064 Receive data from a connected socket.
2066 val recvfrom : file_descr -> buf:bytes -> pos:int -> len:int ->
2070 mode:msg_flag list -> int * sockaddr
2071 Receive data from an unconnected socket.
2073 val send : file_descr -> buf:bytes -> pos:int -> len:int ->
2077 mode:msg_flag list -> int
2078 Send data over a connected socket.
2080 val send_substring : file_descr -> buf:string -> pos:int -> len:int ->
2084 mode:msg_flag list -> int
2085 Same as send , but take the data from a string instead of a byte se‐
2087 quence.
2088 Since 4.02.0
2091 val sendto : file_descr -> buf:bytes -> pos:int -> len:int ->
2095 mode:msg_flag list -> addr:sockaddr -> int
2096 Send data over an unconnected socket.
2098 val sendto_substring : file_descr -> buf:string -> pos:int -> len:int
2102 -> mode:msg_flag list -> sockaddr -> int
2103 Same as sendto , but take the data from a string instead of a byte se‐
2105 quence.
2106 Since 4.02.0
2109 Socket options
2114 type socket_bool_option = Unix.socket_bool_option =
2115 | SO_DEBUG (* Record debugging information
2116 *)
2117 | SO_BROADCAST (* Permit sending of broadcast messages
2118 *)
2119 | SO_REUSEADDR (* Allow reuse of local addresses for bind
2120 *)
2121 | SO_KEEPALIVE (* Keep connection active
2122 *)
2123 | SO_DONTROUTE (* Bypass the standard routing algorithms
2124 *)
2125 | SO_OOBINLINE (* Leave out-of-band data in line
2126 *)
2127 | SO_ACCEPTCONN (* Report whether socket listening is enabled
2128 *)
2129 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
2130 *)
2131 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
2132 *)
2133 | SO_REUSEPORT (* Allow reuse of address and port bindings
2134 *)
2135 The socket options that can be consulted with UnixLabels.getsockopt and
2138 modified with UnixLabels.setsockopt . These options have a boolean (
2139 true / false ) value.
2140 type socket_int_option = Unix.socket_int_option =
2143 | SO_SNDBUF (* Size of send buffer
2144 *)
2145 | SO_RCVBUF (* Size of received buffer
2146 *)
2147 | SO_ERROR (* Deprecated. Use UnixLabels.getsockopt_error instead.
2148 *)
2149 | SO_TYPE (* Report the socket type
2150 *)
2151 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
2152 tions
2153 *)
2154 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
2155 tions
2156 *)
2157 The socket options that can be consulted with UnixLabels.getsockopt_int
2160 and modified with UnixLabels.setsockopt_int . These options have an
2161 integer value.
2162 type socket_optint_option = Unix.socket_optint_option =
2165 | SO_LINGER (* Whether to linger on closed connections that have data
2166 present, and for how long (in seconds)
2167 *)
2168 The socket options that can be consulted with UnixLabels.getsock‐
2171 opt_optint and modified with UnixLabels.setsockopt_optint . These op‐
2172 tions have a value of type int option , with None meaning ``disabled''.
2173 type socket_float_option = Unix.socket_float_option =
2176 | SO_RCVTIMEO (* Timeout for input operations
2177 *)
2178 | SO_SNDTIMEO (* Timeout for output operations
2179 *)
2180 The socket options that can be consulted with UnixLabels.getsock‐
2183 opt_float and modified with UnixLabels.setsockopt_float . These op‐
2184 tions have a floating-point value representing a time in seconds. The
2185 value 0 means infinite timeout.
2186 val getsockopt : file_descr -> socket_bool_option -> bool
2190 Return the current status of a boolean-valued option in the given
2192 socket.
2193 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
2197 Set or clear a boolean-valued option in the given socket.
2199 val getsockopt_int : file_descr -> socket_int_option -> int
2203 Same as UnixLabels.getsockopt for an integer-valued socket option.
2205 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
2209 Same as UnixLabels.setsockopt for an integer-valued socket option.
2211 val getsockopt_optint : file_descr -> socket_optint_option -> int op‐
2215 tion
2216 Same as UnixLabels.getsockopt for a socket option whose value is an int
2218 option .
2219 val setsockopt_optint : file_descr -> socket_optint_option -> int op‐
2223 tion -> unit
2224 Same as UnixLabels.setsockopt for a socket option whose value is an int
2226 option .
2227 val getsockopt_float : file_descr -> socket_float_option -> float
2231 Same as UnixLabels.getsockopt for a socket option whose value is a
2233 floating-point number.
2234 val setsockopt_float : file_descr -> socket_float_option -> float ->
2238 unit
2239 Same as UnixLabels.setsockopt for a socket option whose value is a
2241 floating-point number.
2242 val getsockopt_error : file_descr -> error option
2246 Return the error condition associated with the given socket, and clear
2248 it.
2249 High-level network connection functions
2254 val open_connection : sockaddr -> in_channel * out_channel
2255 Connect to a server at the given address. Return a pair of buffered
2257 channels connected to the server. Remember to call flush on the output
2258 channel at the right times to ensure correct synchronization.
2259 The two channels returned by open_connection share a descriptor to a
2261 socket. Therefore, when the connection is over, you should call
2262 close_out on the output channel, which will also close the underlying
2263 socket. Do not call close_in on the input channel; it will be col‐
2264 lected by the GC eventually.
2265 val shutdown_connection : in_channel -> unit
2269 ``Shut down'' a connection established with UnixLabels.open_connection
2271 ; that is, transmit an end-of-file condition to the server reading on
2272 the other side of the connection. This does not close the socket and
2273 the channels used by the connection. See Unix.open_connection for how
2274 to close them once the connection is over.
2275 val establish_server : (in_channel -> out_channel -> unit) ->
2279 addr:sockaddr -> unit
2280 Establish a server on the given address. The function given as first
2282 argument is called for each connection with two buffered channels con‐
2283 nected to the client. A new process is created for each connection. The
2284 function UnixLabels.establish_server never returns normally.
2285 The two channels given to the function share a descriptor to a socket.
2287 The function does not need to close the channels, since this occurs au‐
2288 tomatically when the function returns. If the function prefers ex‐
2289 plicit closing, it should close the output channel using close_out and
2290 leave the input channel unclosed, for reasons explained in
2291 Unix.in_channel_of_descr .
2292 On Windows: not implemented (use threads).
2294 Host and protocol databases
2299 type host_entry = Unix.host_entry = {
2300 h_name : string ;
2301 h_aliases : string array ;
2302 h_addrtype : socket_domain ;
2303 h_addr_list : inet_addr array ;
2304 }
2305 Structure of entries in the hosts database.
2308 type protocol_entry = Unix.protocol_entry = {
2311 p_name : string ;
2312 p_aliases : string array ;
2313 p_proto : int ;
2314 }
2315 Structure of entries in the protocols database.
2318 type service_entry = Unix.service_entry = {
2321 s_name : string ;
2322 s_aliases : string array ;
2323 s_port : int ;
2324 s_proto : string ;
2325 }
2326 Structure of entries in the services database.
2329 val gethostname : unit -> string
2333 Return the name of the local host.
2335 val gethostbyname : string -> host_entry
2339 Find an entry in hosts with the given name.
2341 Raises Not_found if no such entry exists.
2344 val gethostbyaddr : inet_addr -> host_entry
2348 Find an entry in hosts with the given address.
2350 Raises Not_found if no such entry exists.
2353 val getprotobyname : string -> protocol_entry
2357 Find an entry in protocols with the given name.
2359 Raises Not_found if no such entry exists.
2362 val getprotobynumber : int -> protocol_entry
2366 Find an entry in protocols with the given protocol number.
2368 Raises Not_found if no such entry exists.
2371 val getservbyname : string -> protocol:string -> service_entry
2375 Find an entry in services with the given name.
2377 Raises Not_found if no such entry exists.
2380 val getservbyport : int -> protocol:string -> service_entry
2384 Find an entry in services with the given service number.
2386 Raises Not_found if no such entry exists.
2389 type addr_info = Unix.addr_info = {
2392 ai_family : socket_domain ; (* Socket domain
2393 *)
2394 ai_socktype : socket_type ; (* Socket type
2395 *)
2396 ai_protocol : int ; (* Socket protocol number
2397 *)
2398 ai_addr : sockaddr ; (* Address
2399 *)
2400 ai_canonname : string ; (* Canonical host name
2401 *)
2402 }
2403 Address information returned by UnixLabels.getaddrinfo .
2406 type getaddrinfo_option = Unix.getaddrinfo_option =
2409 | AI_FAMILY of socket_domain
2410 (* Impose the given socket domain
2411 *)
2412 | AI_SOCKTYPE of socket_type
2413 (* Impose the given socket type
2414 *)
2415 | AI_PROTOCOL of int
2416 (* Impose the given protocol
2417 *)
2418 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP ad‐
2419 dress
2420 *)
2421 | AI_CANONNAME (* Fill the ai_canonname field of the result
2422 *)
2423 | AI_PASSIVE (* Set address to ``any'' address for use with UnixLa‐
2424 bels.bind
2425 *)
2427 Options to UnixLabels.getaddrinfo .
2430 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2434 addr_info list
2435 getaddrinfo host service opts returns a list of UnixLabels.addr_info
2438 records describing socket parameters and addresses suitable for commu‐
2439 nicating with the given host and service. The empty list is returned
2440 if the host or service names are unknown, or the constraints expressed
2441 in opts cannot be satisfied.
2442 host is either a host name or the string representation of an IP ad‐
2445 dress. host can be given as the empty string; in this case, the
2446 ``any'' address or the ``loopback'' address are used, depending whether
2447 opts contains AI_PASSIVE . service is either a service name or the
2448 string representation of a port number. service can be given as the
2449 empty string; in this case, the port field of the returned addresses is
2450 set to 0. opts is a possibly empty list of options that allows the
2451 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2452 only) or a particular socket type (e.g. TCP only or UDP only).
2453 type name_info = Unix.name_info = {
2456 ni_hostname : string ; (* Name or IP address of host
2457 *)
2458 ni_service : string ; (* Name of service or port number
2459 *)
2460 }
2461 Host and service information returned by UnixLabels.getnameinfo .
2464 type getnameinfo_option = Unix.getnameinfo_option =
2467 | NI_NOFQDN (* Do not qualify local host names
2468 *)
2469 | NI_NUMERICHOST (* Always return host as IP address
2470 *)
2471 | NI_NAMEREQD (* Fail if host name cannot be determined
2472 *)
2473 | NI_NUMERICSERV (* Always return service as port number
2474 *)
2475 | NI_DGRAM (* Consider the service as UDP-based instead of the de‐
2476 fault TCP
2477 *)
2478 Options to UnixLabels.getnameinfo .
2481 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2485 getnameinfo addr opts returns the host name and service name corre‐
2488 sponding to the socket address addr . opts is a possibly empty list of
2489 options that governs how these names are obtained.
2490 Raises Not_found if an error occurs.
2493 Terminal interface
2498 The following functions implement the POSIX standard terminal inter‐
2499 face. They provide control over asynchronous communication ports and
2500 pseudo-terminals. Refer to the termios man page for a complete descrip‐
2501 tion.
2502 type terminal_io = Unix.terminal_io = {
2504 mutable c_ignbrk : bool ; (* Ignore the break condition.
2506 *)
2507 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2509 *)
2510 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2512 *)
2513 mutable c_parmrk : bool ; (* Mark parity errors.
2515 *)
2516 mutable c_inpck : bool ; (* Enable parity check on input.
2518 *)
2519 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2521 *)
2522 mutable c_inlcr : bool ; (* Map NL to CR on input.
2524 *)
2525 mutable c_igncr : bool ; (* Ignore CR on input.
2527 *)
2528 mutable c_icrnl : bool ; (* Map CR to NL on input.
2530 *)
2531 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2533 *)
2534 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2536 *)
2537 mutable c_opost : bool ; (* Enable output processing.
2539 *)
2540 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2542 tion).
2543 *)
2544 mutable c_ibaud : int ; (* Input baud rate.
2546 *)
2547 mutable c_csize : int ; (* Number of bits per character (5-8).
2549 *)
2550 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2552 *)
2553 mutable c_cread : bool ; (* Reception is enabled.
2555 *)
2556 mutable c_parenb : bool ; (* Enable parity generation and detection.
2558 *)
2559 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2561 *)
2562 mutable c_hupcl : bool ; (* Hang up on last close.
2564 *)
2565 mutable c_clocal : bool ; (* Ignore modem status lines.
2567 *)
2568 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2570 *)
2571 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2573 ing and editing)
2574 *)
2575 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2577 *)
2578 mutable c_echo : bool ; (* Echo input characters.
2580 *)
2581 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2583 *)
2584 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2586 *)
2587 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2589 *)
2590 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2592 *)
2593 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2595 *)
2596 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2598 *)
2599 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2601 *)
2602 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2604 *)
2605 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2607 *)
2608 mutable c_vmin : int ; (* Minimum number of characters to read before
2610 the read request is satisfied.
2611 *)
2612 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2614 *)
2615 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2617 *)
2618 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2620 *)
2621 }
2622 val tcgetattr : file_descr -> terminal_io
2628 Return the status of the terminal referred to by the given file de‐
2630 scriptor.
2631 On Windows: not implemented.
2633 type setattr_when = Unix.setattr_when =
2636 | TCSANOW
2637 | TCSADRAIN
2638 | TCSAFLUSH
2639 val tcsetattr : file_descr -> mode:setattr_when -> terminal_io -> unit
2645 Set the status of the terminal referred to by the given file descrip‐
2647 tor. The second argument indicates when the status change takes place:
2648 immediately ( TCSANOW ), when all pending output has been transmitted (
2649 TCSADRAIN ), or after flushing all input that has been received but not
2650 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2651 parameters; TCSAFLUSH , when changing the input parameters.
2652 On Windows: not implemented.
2654 val tcsendbreak : file_descr -> duration:int -> unit
2658 Send a break condition on the given file descriptor. The second argu‐
2660 ment is the duration of the break, in 0.1s units; 0 means standard du‐
2661 ration (0.25s).
2662 On Windows: not implemented.
2664 val tcdrain : file_descr -> unit
2668 Waits until all output written on the given file descriptor has been
2670 transmitted.
2671 On Windows: not implemented.
2673 type flush_queue = Unix.flush_queue =
2676 | TCIFLUSH
2677 | TCOFLUSH
2678 | TCIOFLUSH
2679 val tcflush : file_descr -> mode:flush_queue -> unit
2685 Discard data written on the given file descriptor but not yet transmit‐
2687 ted, or data received but not yet read, depending on the second argu‐
2688 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2689 data written but not transmitted, and TCIOFLUSH flushes both.
2690 On Windows: not implemented.
2692 type flow_action = Unix.flow_action =
2695 | TCOOFF
2696 | TCOON
2697 | TCIOFF
2698 | TCION
2699 val tcflow : file_descr -> mode:flow_action -> unit
2705 Suspend or restart reception or transmission of data on the given file
2707 descriptor, depending on the second argument: TCOOFF suspends output,
2708 TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2709 put, and TCION transmits a START character to restart input.
2710 On Windows: not implemented.
2712 val setsid : unit -> int
2716 Put the calling process in a new session and detach it from its con‐
2718 trolling terminal.
2719 On Windows: not implemented.
2721OCamldoc 2022-02-04 UnixLabels(3)